awesome-selfhosted
A list of Free Software network services and web applications which can be hosted on your own servers
- 339k
- 5 d ago
Provides a simple way to run Selenium Grid with Chrome, Firefox, and Edge using Container Platform, making it easier to perform browser automation at scale
Repo SeleniumHQ/docker-selenium, read from GitHub 1 h ago. SeleniumHQ has not joined Take My Repo.
SeleniumHQ/docker-selenium is a public repo on GitHub by SeleniumHQ. Provides a simple way to run Selenium Grid with Chrome, Firefox, and Edge using Container Platform, making it easier to perform browser automation at scale. It declares no license on GitHub. Public does not mean open source: without a license, nobody is granted the right to reuse it. It is written mainly in Go, has 8,661 stars and last changed on 2026-11-22. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-22.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
The project is made possible by volunteer contributors who have put in thousands of hours of their own time, and made the source code freely available under the Apache License 2.0.
These Docker images come with a handful of tags to simplify its usage, have a look at them in one of our releases.
To get notifications of new releases, add yourself as a "Releases only" watcher.
These images are published to the Docker Hub registry at Selenium Docker Hub.
Helm Chart enables the creation of a Selenium Grid Server in Kubernetes at
Do you need help to use these Docker images? Talk to us at https://www.selenium.dev/support/
docker run -d -p 4444:4444 -p 7900:7900 --shm-size="2g" selenium/standalone-firefox:4.53.0-20261120
Point your WebDriver tests to http://localhost:4444
That's it!
(Optional) To see what is happening inside the container, head to http://localhost:7900/?autoconnect=1&resize=scale&password=secret.
For more details about visualising the container activity, check the Debugging section.
:point_up: When executing docker run for an image that contains a browser please use
the flag --shm-size=2g to use the host's shared memory.
:point_up: Always use a Docker image with a full tag to pin a specific browser and Grid version. See Tagging Conventions for details.
From image tag based 4.21.0 onwards, the architectures supported by this project are as below:
| Architecture | Available |
|---|---|
| x86_64 (aka amd64) | ✅ |
| aarch64 (aka arm64/armv8) | ✅ |
| armhf (aka arm32/armv7l) | ❌ |
The following browsers are available in multi-arch images:
| Architecture | Chrome | Chromium | Firefox | Edge | CfT |
|---|---|---|---|---|---|
| x86_64 (aka amd64) | ✅ | ✅ | ✅ | ✅ | ✅ |
| aarch64 (aka arm64/armv8) | ✅ | ✅ | ✅ | ❌ | ❌ |
| armhf (aka arm32/armv7l) | ❌ | ❌ | ❌ | ❌ | ❌ |
Note:
Running an AMD64 image under emulation on an ARM64 platform is not recommended due to performance and stability issues, or browsers could not launch.
Google Chrome (google-chrome) now is available for Linux/ARM64 via APT stable channel from v150+. The Chrome (node and standalone) images are available in multi-arch. Older Chrome versions remain AMD64 only; the supported platforms per version are tracked in the browser matrix via the CHROME_PLATFORMS key.
Microsoft does not build Edge (microsoft-edge) for Linux/ARM platforms, hence the Edge (node and standalone) images are only available for AMD64.
Google does not publish a ChromeDriver build for Linux/ARM64 (Chrome for Testing only ships linux64). On ARM64 the Chrome images use the Chromium driver of the same major version instead, taken from the Debian chromium-driver package archived at NDViet/chromium-stable. Those packages follow the stable channel, hence the Chrome dev and beta images are only available for AMD64.
We also supply Chrome for Testing (CfT), but it is only available for Linux/AMD64.
For older Linux/ARM setups you can also use the open source Chromium browser. The Chromium (node and standalone) images are available in multi-arch.
$ docker run --rm -it -p 4444:4444 -p 5900:5900 -p 7900:7900 --shm-size 2g selenium/standalone-chromium:latest
Multi-arch images are tested on CircleCI with resource class Linux/ARM64. See the status below. (Moved to GitHub Actions)
For experimental docker container images, which run on platforms such as the Apple M-series or Raspberry Pi, the repository at seleniumhq-community/docker-seleniarm provided images which are published on the Seleniarm Docker Hub registry.
See issue #1076 for more information on these images.
Now, the fork seleniumhq-community/docker-seleniarm was merged.
We recommend to enable the experimental feature containerd image store in Docker Engine.
containerd understands multiplatform images, where a single image tag can refer to different variants covering a range of OS and hardware architectures.
It simplifies the process of building, storing, and distributing images across different platforms.
A single command to enable that feature in Docker Engine:
make set_containerd_image_store
Noted: That command is only compatible with Ubuntu. For users use Docker Desktop on macOS, it can be enabled easily via
Settings > General > Use containerd for pulling and storing images
To build all the images for multiplatform at once, run the following command:
PLATFORMS=linux/amd64,linux/arm64 make all
To build the images for a specific platform, run the following command:
PLATFORMS=linux/arm64 make all
By default, without specifying the PLATFORMS variable, the images are built with current host architecture.
Similarly, if you are using host ARM64 architecture, you can build the images for AMD64 architecture by running the following command:
PLATFORMS=linux/amd64 make all
Nightly images are built on top of the Nightly build on the upstream project Selenium with the latest changes on main branch in this repository. The image tag is nightly. This is not recommended to use images in production. It is only for testing purpose.
$ docker run -d -p 4442-4444:4442-4444 --name selenium-hub selenium/hub:nightly
Check out the docker compose to get started with Nightly images docker-compose-v3-full-grid-nightly.yml
To run tests or otherwise work with pre-release browsers, Google, Mozilla, and Microsoft maintain a Dev and Beta release channel for those who need to see what's soon to be released to the general population.
Here are the instructions to run them in Standalone mode:
Chrome Beta:
$ docker run --platform linux/amd64 --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-chrome:beta
Chrome Dev:
$ docker run --platform linux/amd64 --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-chrome:dev
Firefox Beta:
$ docker run --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-firefox:beta
Firefox Dev:
$ docker run --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-firefox:dev
Edge Beta:
$ docker run --platform linux/amd64 --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-edge:beta
Edge Dev:
$ docker run --platform linux/amd64 --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-edge:dev
Chrome for Testing Beta:
$ docker run --platform linux/amd64 --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-chrome-for-testing:beta
Chrome for Testing Dev:
$ docker run --platform linux/amd64 --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-chrome-for-testing:dev
Chrome for Testing Canary:
$ docker run --platform linux/amd64 --rm -it -p 4444:4444 -p 7900:7900 --shm-size 2g selenium/standalone-chrome-for-testing:canary
docker-compose-v3-beta-channel.yml:
# To execute this docker compose yml file use `docker compose -f docker-compose-v3-beta-channel.yml up`
# Add the `-d` flag at the end for detached execution
# To stop the execution, hit Ctrl+C, and then `docker compose -f docker-compose-v3-beta-channel.yml down`
services:
chrome:
image: selenium/node-chrome:beta
platform: linux/amd64
shm_size: 2gb
depends_on:
- selenium-hub
environment:
- SE_EVENT_BUS_HOST=selenium-hub
edge:
image: selenium/node-edge:beta
platform: linux/amd64
shm_size: 2gb
depends_on:
- selenium-hub
environment:
- SE_EVENT_BUS_HOST=selenium-hub
firefox:
image: selenium/node-firefox:beta
shm_size: 2gb
depends_on:
- selenium-hub
environment:
- SE_EVENT_BUS_HOST=selenium-hub
chrome-for-testing:
image: selenium/node-chrome-for-testing:beta
platform: linux/amd64
shm_size: 2gb
depends_on:
- selenium-hub
environment:
- SE_EVENT_BUS_HOST=selenium-hub
selenium-hub:
image: selenium/hub:latest
container_name: selenium-hub
ports:
- "4442:4442"
- "4443:4443"
- "4444:4444"
docker-compose-v3-dev-channel.yml:
# To execute this docker compose yml file use `docker compose -f docker-compose-v3-dev-channel.yml up`
# Add the `-d` flag at the end for detached execution
# To stop the execution, hit Ctrl+C, and then `docker compose -f docker-compose-v3-dev-channel.yml down`
services:
chrome:
image: selenium/node-chrome:dev
platform: linux/amd64
shm_size: 2gb
depends_on:
- selenium-hub
environment:
- SE_EVENT_BUS_HOST=selenium-hub
edge:
image: selenium/node-edge:dev
platform: linux/amd64
shm_size: 2gb
depends_on:
- selenium-hub
environment:
- SE_EVENT_BUS_HOST=selenium-hub
firefox:
image: selenium/node-firefox:dev
shm_size: 2gb
depends_on:
- selenium-hub
environment:
- SE_EVENT_BUS_HOST=selenium-hub
chrome-for-testing:
image: selenium/node-chrome-for-testing:dev
platform: linux/amd64
shm_size: 2gb
depends_on:
- selenium-hub
environment:
- SE_EVENT_BUS_HOST=selenium-hub
selenium-hub:
image: selenium/hub:latest
container_name: selenium-hub
ports:
- "4442:4442"
- "4443:4443"
- "4444:4444"
For more information on the Dev and Beta channel container images, see the blog post on Dev and Beta Channel Browsers via Docker Selenium.
From image tag 4.35.0 onwards, a single Node/Standalone image is available with all browsers are pre-installed. Those images are selenium/standalone-all-browsers (standalone all in one), selenium/node-all-browsers (for Hub-Node mode).
These two images are suitable for users:
According to multi-arch support, browsers are available in images selenium/node-all-browsers and selenium/standalone-all-browsers would be different per architecture.
| Browser / Arch | x86_64 (aka amd64) | aarch64 (aka arm64/armv8) |
|---|---|---|
| Chrome | ✅ | ✅ |
| Edge | ✅ | ❌ |
| Firefox | ✅ | ✅ |
| Chromium | ✅ | ✅ |
Both Chrome and Chromium browser binary are available in image arch linux/amd64. However, Chrome browser binary is activated by default. In case you want to switch to Chromium browser binary, you can set environment variable SE_BROWSER_BINARY_LOCATION_CHROME=/usr/bin/chromium.
Via environment variable SE_NODE_ENABLE_BROWSER_<BROWSER>, with <BROWSER> is the name of browser in uppercase (e.g. CHROME, FIREFOX, EDGE). You can disable a browser to be installed in the Node/Standalone image all browsers.
For example with image linux/amd64 and linux/arm64, you can disable Firefox browser by setting environment variable SE_NODE_ENABLE_BROWSER_FIREFOX=false.
For example with image linux/amd64, you can disable Chrome browser by setting environment variable SE_NODE_ENABLE_BROWSER_CHROME=false. Similar for Edge browser, set SE_NODE_ENABLE_BROWSER_EDGE=false.
Here is list of environment variables which support suffix _<BROWSER> in Node/Standalone image all browsers:
SE_NODE_STEREOTYPE
SE_NODE_BROWSER_NAME
SE_NODE_BROWSER_VERSION
SE_NODE_PLATFORM_NAME
SE_BROWSER_BINARY_LOCATION
SE_NODE_STEREOTYPE_EXTRA
SE_NODE_MAX_SESSIONS
Checkout full list of environment variables here.
How to update or contribute to list of environment variables? Follow below steps:
Refresh the list to pick up new environment variables or default value
make update_list_env_vars
The script can be updated in scripts/generate_list_env_vars/extract_env.py.
Update the description for each environment variable in the file scripts/generate_list_env_vars/description.yaml.
Run the command in step (1) one more time to update the list of environment variables with new descriptions.
Firefoxdocker run -d -p 4444:4444 --shm-size="2g" selenium/standalone-firefox:4.53.0-20261120
Chromedocker run -d -p 4444:4444 --shm-size="2g" selenium/standalone-chrome:4.53.0-20261120
Edgedocker run -d -p 4444:4444 --shm-size="2g" selenium/standalone-edge:4.53.0-20261120
docker run -d -p 4444:4444 --shm-size="3g" selenium/standalone-all-browsers:4.53.0-20261120
Note: Only one Standalone container can run on port 4444 at the same time.
There are different ways to run the images and create a Grid with a Hub and Nodes, check the following options.
The Hub and Nodes will be created in the same network and they will recognize each other by their container name. A Docker network needs to be created as a first step.
Hub and multiple browser Node containers
$ docker network create grid
$ docker run -d -p 4442-4444:4442-4444 --net grid --name selenium-hub selenium/hub:4.53.0-20261120
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \
--shm-size="2g" \
selenium/node-chrome:4.53.0-20261120
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \
--shm-size="2g" \
selenium/node-edge:4.53.0-20261120
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \
--shm-size="2g" \
selenium/node-firefox:4.53.0-20261120
Hub and single Node container with all browsers
$ docker network create grid
$ docker run -d -p 4442-4444:4442-4444 --net grid --name selenium-hub selenium/hub:4.53.0-20261120
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \
--shm-size="3g" \
selenium/node-all-browsers:4.53.0-20261120
Hub and multiple browser Node containers
$ docker network create grid
$ docker run -d -p 4442-4444:4442-4444 --net grid --name selenium-hub selenium/hub:4.53.0-20261120
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub `
--shm-size="2g" `
selenium/node-chrome:4.53.0-20261120
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub `
--shm-size="2g" `
selenium/node-edge:4.53.0-20261120
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub `
--shm-size="2g" `
selenium/node-firefox:4.53.0-20261120
Hub and single Node container with all browsers
$ docker network create grid
$ docker run -d -p 4442-4444:4442-4444 --net grid --name selenium-hub selenium/hub:4.53.0-20261120
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub `
--shm-size="3g" `
selenium/node-all-browsers:4.53.0-20261120
When you are done using the Grid, and the containers have exited, the network can be removed with the following command:
# Removes the grid network
$ docker network rm grid
The Hub and Nodes will be created on different machines/VMs, they need to know each other's IPs to communicate properly. If more than one node will be running on the same Machine/VM, they must be configured to expose different ports.
$ docker run -d -p 4442-4444:4442-4444 --name selenium-hub selenium/hub:4.53.0-20261120
$ docker run -d -p 5555:5555 \
--shm-size="2g" \
-e SE_EVENT_BUS_HOST=<ip-from-machine-1> \
-e SE_NODE_HOST=<ip-from-machine-2> \
selenium/node-chrome:4.53.0-20261120
$ docker run -d -p 5555:5555 `
--shm-size="2g" `
-e SE_EVENT_BUS_HOST=<ip-from-machine-1> `
-e SE_NODE_HOST=<ip-from-machine-2> `
selenium/node-chrome:4.53.0-20261120
$ docker run -d -p 5555:5555 \
--shm-size="2g" \
-e SE_EVENT_BUS_HOST=<ip-from-machine-1> \
-e SE_NODE_HOST=<ip-from-machine-3> \
selenium/node-edge:4.53.0-20261120
$ docker run -d -p 5555:5555 `
--shm-size="2g" `
-e SE_EVENT_BUS_HOST=<ip-from-machine-1> `
-e SE_NODE_HOST=<ip-from-machine-3> `
selenium/node-edge:4.53.0-20261120
$ docker run -d -p 5555:5555 \
--shm-size="2g" \
-e SE_EVENT_BUS_HOST=<ip-from-machine-1> \
-e SE_NODE_HOST=<ip-from-machine-4> \
selenium/node-firefox:4.53.0-20261120
$ docker run -d -p 5555:5555 `
--shm-size="2g" `
-e SE_EVENT_BUS_HOST=<ip-from-machine-1> `
-e SE_NODE_HOST=<ip-from-machine-4> `
selenium/node-firefox:4.53.0-20261120
$ docker run -d -p 5556:5556 \
--shm-size="2g" \
-e SE_EVENT_BUS_HOST=<ip-from-machine-1> \
-e SE_NODE_HOST=<ip-from-machine-4> \
-e SE_NODE_PORT=5556 \
selenium/node-chrome:4.53.0-20261120
$ docker run -d -p 5556:5556 `
--shm-size="2g" `
-e SE_EVENT_BUS_HOST=<ip-from-machine-1> `
-e SE_NODE_HOST=<ip-from-machine-4> `
-e SE_NODE_PORT=5556 `
selenium/node-chrome:4.53.0-20261120
Docker Compose is the simplest way to start a Grid. Use the linked resources below, save them locally and check the execution instructions on top of each file.
To stop the Grid and cleanup the created containers, run docker compose down.
It is possible to start a Selenium Grid with all its components apart. For simplicity, only an example with docker compose will be provided. Save the file locally, and check the execution instructions on top of it.
docker-compose-v3-full-grid.yml
| Environment variable | Option | Type | Default value | Description |
|---|---|---|---|---|
SE_REJECT_UNSUPPORTED_CAPS |
--reject-unsupported-caps |
boolean | false |
Allow the Distributor to reject a request immediately if the Grid does not support the requested capability. |
SE_HEALTHCHECK_INTERVAL |
--healthcheck-interval |
int | 120 |
This ensures the server can ping all the Nodes successfully after an interval. |
SE_DISTRIBUTOR_SLOT_SELECTOR |
--slot-selector |
string | `` | Full class name of non-default slot selector. This is used to select a slot in a Node once the Node has been matched. |
Distributor component comes with two main built-in Slot Selector implementations
org.openqa.selenium.grid.distributor.selector.DefaultSlotSelector: Grid’s default strategy (used if you don’t configure anything else). It follows the balanced, least-recently-used approach described above. The DefaultSlotSelector will choose the Node that has been free for the longest time, ensuring no single node is overused when others are idle. This simple strategy has minimal overhead and works well for most general testing scenarios where an even distribution of sessions is desired.
org.openqa.selenium.grid.distributor.selector.GreedySlotSelector: An alternative built-in provided. The GreedySlotSelector aims to maximize node utilization by concentrating sessions on one node before using another. As noted, it will tend to fill up a node’s slots one by one, reducing the number of nodes that are partially utilized at any given time. This strategy is beneficial for resource-intensive or high-concurrency scenarios (for example, load testing or running in an environment where you scale nodes on demand). More insight, let's refer to #2990.
Tests execution can be recorded by using the selenium/video:ffmpeg-8.1-20261120
Docker image. One container is needed per each container where a browser is running. This means if you are
running 5 Nodes/Standalone containers, you will need 5 video containers, the mapping is 1-1.
Currently, the only way to do this mapping is manually (either starting the containers manually or through
docker compose). We are iterating on this process and probably this setup will be more simple in the future.
The video Docker image we provide is based on the ffmpeg Ubuntu image provided by the jrottenberg/ffmpeg project, thank you for providing this image and simplifying our work :tada:
From image tag based 4.20.0 onwards, the video Docker image is based on the FFmpeg Ubuntu image provided by
linuxserver/docker-ffmpeg project since the image is available for multi-platform.
Thank you for simplifying our project and helping us move forward with multiple architecture support.
Notes:
/videos directory inside the video container. Map a local directory to get the videos.FILE_NAME
environment variable to avoid unexpected results.This example shows how to start the containers manually:
$ docker network create grid
$ docker run -d -p 4444:4444 -p 6900:5900 --net grid --name selenium --shm-size="2g" selenium/standalone-chrome:4.53.0-20261120
$ docker run -d --net grid --name video -v /tmp/videos:/videos selenium/video:ffmpeg-8.1-20261120
# Run your tests
$ docker stop video && docker rm video
$ docker stop selenium && docker rm selenium
After the containers are stopped and removed, you should see a video file on your machine's /tmp/videos directory.
Here is an example using a Hub and a few Nodes:
Based on the support of Metadata in tests. When the video recorder is sidecar deployed with the browser node with enabling SE_VIDEO_FILE_NAME=auto and adding metadata to your tests, video file name will extract value of capability se:name and use it as the video file name.
For example in Python binding:
from selenium.webdriver.chrome.options import Options as ChromeOptions
from selenium import webdriver
options = ChromeOptions()
options.set_capability('se:name', 'test_visit_basic_auth_secured_page (ChromeTests)')
driver = webdriver.Remote(options=options, command_executor="http://localhost:4444")
driver.get("https://selenium.dev")
driver.quit()
The output video file name will be test_visit_basic_auth_secured_page_ChromeTests_<sessionId>.mp4.
If your test name is handled by the test framework, and it is unique for sure, you also can disable the session id appends to the video file name by setting SE_VIDEO_FILE_NAME_SUFFIX=false.
File name will be trimmed to 255 characters to avoid long file names. Moreover, space character will be replaced by _ and only characters alphabets, numbers, - (hyphen), _ (underscore) are retained in the file name.
The trim regex is able to be customized by setting SE_VIDEO_FILE_NAME_TRIM_REGEX environment variable. The default value is [^a-zA-Z0-9-_]. The regex should be compatible with Python re.compile() function.
At deployment level, the recorder container is always up and stays in standby, watching for sessions. Whether a given session is recorded is controlled per session by the se:recordVideo capability, which overrides the SE_RECORD_VIDEO environment variable used as the default when the capability is not present:
se:recordVideo capability present on the session: its value wins for that session (true records, false skips), regardless of SE_RECORD_VIDEO.se:recordVideo capability absent: the recorder falls back to SE_RECORD_VIDEO (default true for the standalone video image, false for the Node images).This means you can keep recording disabled by default and opt in per test. For example, with SE_RECORD_VIDEO=false, the recorder stays in standby and only records sessions that explicitly request it:
# Recorded only because the session opts in, even when SE_RECORD_VIDEO=false
options.set_capability('se:recordVideo', True)
Conversely, with recording enabled by default (SE_RECORD_VIDEO=true) you can disable it for a specific session:
options.set_capability('se:recordVideo', False)
This per-session control applies to both recording modes:
SE_VIDEO_EVENT_DRIVEN=true, default in the Node images): the recorder subscribes to the Grid event bus and reads se:recordVideo from each session's capabilities on the SessionCreated event.SE_VIDEO_EVENT_DRIVEN=false): the recorder queries the Node /status endpoint (or the Hub GraphQL endpoint) based on the Node SessionId and extracts se:recordVideo from the capabilities before deciding whether to start recording.Notes: For the shell/polling mode to reach the GraphQL endpoint, the recorder container needs to know the Hub URL. The Hub URL can be passed via environment variable SE_NODE_GRID_URL. For example SE_NODE_GRID_URL is http://selenium-hub:4444.
RCLONE is installed in the video recorder image. You can use it to upload the videos to a cloud storage service. Besides the video recording mentioned above, you can enable the upload functionality by setting the following environment variables:
services:
chrome_video:
image: selenium/video:ffmpeg-8.1-20261120
depends_on:
- chrome
environment:
- DISPLAY_CONTAINER_NAME=chrome
- SE_VIDEO_FILE_NAME=auto
- SE_VIDEO_UPLOAD_ENABLED=true
- SE_UPLOAD_DESTINATION_PREFIX=s3://mybucket/path
- RCLONE_CONFIG_S3_TYPE=s3
- RCLONE_CONFIG_S3_PROVIDER=GCS
- RCLONE_CONFIG_S3_ENV_AUTH=true
- RCLONE_CONFIG_S3_REGION=asia-southeast1
- RCLONE_CONFIG_S3_LOCATION_CONSTRAINT=asia-southeast1
- RCLONE_CONFIG_S3_ACL=private
- RCLONE_CONFIG_S3_ACCESS_KEY_ID=xxx
- RCLONE_CONFIG_S3_SECRET_ACCESS_KEY=xxx
- RCLONE_CONFIG_S3_ENDPOINT=https://storage.googleapis.com
- RCLONE_CONFIG_S3_NO_CHECK_BUCKET=true
SE_VIDEO_FILE_NAME=auto will use the session id as the video file name. This ensures that the video file name is unique to upload.
Video file name construction automatically works based on Node endpoint /status (and optional GraphQL endpoint) to get session ID, capabilities.
SE_VIDEO_UPLOAD_ENABLED=true enables upload in the legacy shell-based mode (SE_VIDEO_EVENT_DRIVEN=false). In event-driven mode (the default), this variable is deprecated — upload is enabled automatically when SE_UPLOAD_DESTINATION_PREFIX is set to a non-empty value.
SE_VIDEO_INTERNAL_UPLOAD=true (by default) will use RCLONE installed in the container for upload. If you want to use another sidecar container for upload, set it to false.
| ENV variables per mode | Hub/Nodes | Standalone roles | Dynamic Grid |
|---|---|---|---|
SE_VIDEO_RECORD_STANDALONE (mandatory) |
false (default) |
true |
true |
DISPLAY_CONTAINER_NAME (mandatory) |
user input | user input | (not required) |
SE_NODE_PORT (optional) |
5555 |
4444 |
(not required) |
SE_NODE_GRID_URL (optional) |
user input | (not required) | (not required) |
For environment variables with prefix RCLONE_ is used to pass remote configuration to RCLONE. You can find more information about RCLONE configuration here.
When using in Dynamic Grid, those variables should be combined with the prefix SE_, for example SE_RCLONE_. See below reference for more details.
Configure video recording and uploading for Hub and Nodes: docker-compose-v3-video-upload.yml
Configure video recording and uploading for Standalone roles: docker-compose-v3-video-upload-standalone.yml
Configure video recording and uploading for Dynamic Grid (node-docker): docker-compose-v3-video-upload-dynamic-grid.yml
Configure video recording and uploading for Dynamic Grid standalone (standalone-docker): tests/docker-compose-v3-test-standalone-docker.yaml
| Environment variable | Default value | Description |
|---|---|---|
SE_UPLOAD_RETAIN_LOCAL_FILE |
false |
Keep local file after uploading successfully |
SE_UPLOAD_COMMAND |
copy |
RCLONE command is used to transfer file. Enforce move when retain local file is false |
SE_UPLOAD_OPTS |
-P --cutoff-mode SOFT --metadata --inplace |
Other options belong to RCLONE command can be set. |
SE_UPLOAD_CONFIG_FILE_NAME |
upload.conf |
Config file for remote host instead of set via env variable prefix SE_RCLONE_* |
SE_UPLOAD_CONFIG_DIRECTORY |
/opt/bin |
Directory of config file (change it when conf file in another directory is mounted) |
In event-driven mode (SE_VIDEO_EVENT_DRIVEN=true, the default), the video service subscribes to the Grid's ZeroMQ event bus and reacts to session lifecycle events in real time. This enables a retain-on-failure strategy: record every session, but automatically discard the video when the session passes and only keep (and upload) recordings from sessions that fail.
Enable it globally with the environment variable:
SE_RETAIN_ON_FAILURE=true
A session is treated as failed when either of the following is true:
eventType contains a substring from SE_FAILURE_SESSION_EVENTS (default: :failed,:failure,:error,:aborted).TIMEOUT, NODE_REMOVED, or NODE_RESTARTED — instead of the normal QUIT_COMMAND.| Environment variable | Default | Description |
|---|---|---|
SE_RETAIN_ON_FAILURE |
false |
Discard recordings of sessions that pass. Only recordings from failed sessions are retained on disk and queued for upload. |
SE_FAILURE_SESSION_EVENTS |
:failed,:failure,:error,:aborted |
Comma-separated substrings. Any session event whose eventType contains one of these (case-insensitive) marks the session as failed. |
The se:retainOnFailure session capability overrides the global container env var for a specific session. For example, to retain the recording of a single session regardless of the global setting:
options.set_capability('se:retainOnFailure', True)
se:retainOnFailure cap |
SE_RETAIN_ON_FAILURE env |
Effective behaviour |
|---|---|---|
true |
false (default) |
Retain on failure for this session |
false |
true |
Always retain for this session |
| absent | true |
Retain on failure (global default) |
| absent | false (default) |
Always retain (global default) |
The Session Event API lets test code push named events directly to the Grid. The video service listens for these events on the ZeroMQ bus and uses them to determine session failure.
Call driver.fire_session_event(eventType, payload) from your test. Any eventType that contains a configured failure substring (e.g. "test:failed" contains ":failed") marks the session as failed.
from selenium.webdriver.chrome.options import Options as ChromeOptions
from selenium import webdriver
options = ChromeOptions()
options.set_capability('se:name', 'checkout_flow')
options.set_capability('se:retainOnFailure', True) # discard video if this session passes
driver = webdriver.Remote(options=options, command_executor="http://localhost:4444")
try:
driver.get("https://selenium.dev")
# ... test steps ...
except Exception as exc:
# "test:failed" contains ":failed" — matches the default SE_FAILURE_SESSION_EVENTS
driver.fire_session_event("test:failed", {"error": str(exc)})
raise
finally:
driver.quit()
Note: If the test catches an exception and still calls
driver.quit()normally, the session close reason isQUIT_COMMAND(not abnormal). In that case, firing a failure event beforequit()is the only way to mark the session as failed and prevent the recording from being discarded.
So, you can control the retain-on-failure strategy fully from test code via session capabilities and fire session event.
We utilize File Browser as a video manager. It is a web-based file manager that allows you to manage files and folders in the storage.
The File Browser container dir /srv should be mounted to the same storage as video recordings stored. For example a compose file:
services:
chrome:
deploy:
mode: replicated
replicas: 3
image: selenium/node-chrome:4.53.0-20261120
platform: linux/amd64
shm_size: 2gb
depends_on:
- selenium-hub
volumes:
- /tmp/videos:/videos
environment:
- SE_EVENT_BUS_HOST=selenium-hub
- SE_RECORD_VIDEO=true
- SE_VIDEO_FILE_NAME=auto
- SE_NODE_GRID_URL=http://selenium-hub:4444
file_browser:
image: filebrowser/filebrowser:latest
container_name: file_browser
restart: always
ports:
- "8081:80"
volumes:
- /tmp/videos:/srv
environment:
- FB_NOAUTH=true
Grid 4 has the ability to start Docker containers on demand, this means that it starts a Docker container in the background for each new session request, the test gets executed there, and when the test completes, the container gets thrown away.
This execution mode can be used either in the Standalone or Node roles. The "dynamic"
execution mode needs to be told what Docker images to use when the containers get started.
Additionally, the Grid needs to know the URI of the Docker daemon. This configuration can
be placed in a local toml file.
You can save this file locally and name it, for example, config.toml.
[docker]
# Configs have a mapping between the Docker image to use and the capabilities that need to be matched to
# start a container with the given image.
configs = [
"selenium/standalone-firefox:4.53.0-20261120", '{"browserName": "firefox"}',
"selenium/standalone-chrome:4.53.0-20261120", '{"browserName": "chrome"}',
"selenium/standalone-edge:4.53.0-20261120", '{"browserName": "MicrosoftEdge"}'
]
host-config-keys = ["Dns", "DnsOptions", "DnsSearch", "ExtraHosts", "Binds"]
# URL for connecting to the docker daemon
# Most simple approach, leave it as http://127.0.0.1:2375, and mount /var/run/docker.sock.
# 127.0.0.1 is used because internally the container uses socat when /var/run/docker.sock is mounted
# If var/run/docker.sock is not mounted:
# Windows: make sure Docker Desktop exposes the daemon via tcp, and use http://host.docker.internal:2375.
# macOS: install socat and run the following command, socat -4 TCP-LISTEN:2375,fork UNIX-CONNECT:/var/run/docker.sock,
# then use http://host.docker.internal:2375.
# Linux: varies from machine to machine, please mount /var/run/docker.sock. If this does not work, please create an issue.
url = "http://127.0.0.1:2375"
# Docker image used for video recording
video-image = "selenium/video:ffmpeg-8.1-20261120"
# Uncomment the following section if you are running the node on a separate VM
# Fill out the placeholders with appropriate values
#[server]
#host = <ip-from-node-machine>
#port = <port-from-node-machine>
Mount the local config.toml file to the container path /opt/selenium/docker.toml.
This config file path specific for Dynamic Grid (node/standalone docker) by default to avoid conflict with the config file in node browser containers (since users can share volumes config to node browser containers, see below section for details).
With the optional config key host-config-keys under section [docker] in a config.toml file (or CLI option --docker-host-config-keys). Users can specify a list of docker host configuration keys that should be passed to browser containers.
Valid key names for Docker host config can be found in the Docker API documentation or via the command docker inspect the node-docker container.
In case you want to access download directory in node browser containers (e.g /home/seluser/Downloads) via volumes config of Dynamic Grid container, you can add the following config to the config.toml file
[docker]
host-config-keys = ["Binds"]
Volumes config in docker compose file
services:
node-docker:
image: selenium/node-docker:latest
volumes:
- ./assets:/opt/selenium/assets
- ./config.toml:/opt/selenium/docker.toml
- ./downloads:/home/seluser/Downloads
- /var/run/docker.sock:/var/run/docker.sock
environment:
- SE_NODE_DOCKER_CONFIG_FILENAME=docker.toml
/opt/selenium/config.toml is the default path for the config file in all images. Once volumes config is shared to node browser containers, its config.toml could be overwritten by node-docker container config file.
In this case, mount your config.toml file to /opt/selenium/docker.toml in node-docker container. And set the environment variable SE_NODE_DOCKER_CONFIG_FILENAME=docker.toml to specify that config file name for the startup script.
Refer to example docker-compose-v3-test-node-docker.yaml
This can be expanded to a full Grid deployment, all components deployed individually. The overall idea is to have the Hub in one virtual machine, and each of the Nodes in separate and more powerful virtual machines.
$ docker network create grid
$ docker run -d -p 4442-4444:4442-4444 --net grid --name selenium-hub selenium/hub:4.53.0-20261120
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \
-v ${PWD}/config.toml:/opt/selenium/docker.toml \
-v ${PWD}/assets:/opt/selenium/assets \
-v /var/run/docker.sock:/var/run/docker.sock \
selenium/node-docker:4.53.0-20261120
$ docker network create grid
$ docker run -d -p 4442-4444:4442-4444 --net grid --name selenium-hub selenium/hub:4.53.0-20261120
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub `
-v ${PWD}/config.toml:/opt/selenium/docker.toml `
-v ${PWD}/assets:/opt/selenium/assets `
-v /var/run/docker.sock:/var/run/docker.sock `
selenium/node-docker:4.53.0-20261120
To have the assets saved on your host, please mount your host path to /opt/selenium/assets.
When you are done using the Grid, and the containers have exited, the network can be removed with the following command:
# Removes the grid network
$ docker network rm grid
docker run --rm --name selenium-docker -p 4444:4444 \
-v ${PWD}/config.toml:/opt/selenium/docker.toml \
-v ${PWD}/assets:/opt/selenium/assets \
-v /var/run/docker.sock:/var/run/docker.sock \
selenium/standalone-docker:4.53.0-20261120
docker run --rm --name selenium-docker -p 4444:4444 `
-v ${PWD}/config.toml:/opt/selenium/docker.toml `
-v ${PWD}/assets:/opt/selenium/assets `
-v /var/run/docker.sock:/var/run/docker.sock `
selenium/standalone-docker:4.53.0-20261120
$ docker run -d -p 4442-4444:4442-4444 --name selenium-hub selenium/hub:4.53.0-20261120
$ docker run -d -p 5555:5555 \
-e SE_EVENT_BUS_HOST=<ip-from-machine-1> \
-v ${PWD}/config.toml:/opt/selenium/docker.toml \
-v ${PWD}/assets:/opt/selenium/assets \
-v /var/run/docker.sock:/var/run/docker.sock \
selenium/node-docker:4.53.0-20261120
$ docker run -d -p 5555:5555 `
-e SE_EVENT_BUS_HOST=<ip-from-machine-1> `
-v ${PWD}/config.toml:/opt/selenium/docker.toml `
-v ${PWD}/assets:/opt/selenium/assets `
-v /var/run/docker.sock:/var/run/docker.sock `
selenium/node-docker:4.53.0-20261120
Complete the [server] section in the config.toml file.
[docker]
# Configs have a mapping between the Docker image to use and the capabilities that need to be matched to
# start a container with the given image.
configs = [
"selenium/standalone-firefox:4.53.0-20261120", "{\"browserName\": \"firefox\"}",
"selenium/standalone-chrome:4.53.0-20261120", "{\"browserName\": \"chrome\"}",
"selenium/standalone-edge:4.53.0-20261120", "{\"browserName\": \"MicrosoftEdge\"}"
]
# URL for connecting to the docker daemon
# Most simple approach, leave it as http://127.0.0.1:2375, and mount /var/run/docker.sock.
# 127.0.0.1 is used because interally the container uses socat when /var/run/docker.sock is mounted
# If var/run/docker.sock is not mounted:
# Windows: make sure Docker Desktop exposes the daemon via tcp, and use http://host.docker.internal:2375.
# macOS: install socat and run the following command, socat -4 TCP-LISTEN:2375,fork UNIX-CONNECT:/var/run/docker.sock,
# then use http://host.docker.internal:2375.
# Linux: varies from machine to machine, please mount /var/run/docker.sock. If this does not work, please create an issue.
url = "http://127.0.0.1:2375"
# Docker image used for video recording
video-image = "selenium/video:ffmpeg-8.1-20261120"
# Uncomment the following section if you are running the node on a separate VM
# Fill out the placeholders with appropriate values
[server]
host = <ip-from-node-machine>
port = <port-from-node-machine>
To have the assets saved on your host, please mount your host path to /opt/selenium/assets.
Here is an example using a Hub and a Node:
docker-compose-v3-dynamic-grid.yml
Containers can be further configured through environment variables, such as SE_NODE_SESSION_TIMEOUT
and SE_OPTS. When a child container is created, all environment variables prefixed with SE_ will
be forwared and set in the container. You can set the desired environment variables in the
standalone-docker or node-docker containers. The following example sets the session timeout to
700 seconds for all sessions:
docker run --rm --name selenium-docker -p 4444:4444 \
-e SE_NODE_SESSION_TIMEOUT=700 \
-v ${PWD}/config.toml:/opt/selenium/docker.toml \
-v ${PWD}/assets:/opt/selenium/assets \
-v /var/run/docker.sock:/var/run/docker.sock \
selenium/standalone-docker:4.53.0-20261120
docker run --rm --name selenium-docker -p 4444:4444 `
-e SE_NODE_SESSION_TIMEOUT=700 `
-v ${PWD}/config.toml:/opt/selenium/docker.toml `
-v ${PWD}/assets:/opt/selenium/assets `
-v /var/run/docker.sock:/var/run/docker.sock `
selenium/standalone-docker:4.53.0-20261120
To record your WebDriver session, you need to add a se:recordVideo
field set to true. You can also set a time zone and a screen resolution,
for example:
{
"browserName": "firefox",
"platformName": "linux",
"se:recordVideo": "true",
"se:timeZone": "US/Pacific",
"se:screenResolution": "1920x1080"
}
After running a test, check the path you mounted to the Docker container,
(${PWD}/assets), and you should see videos and session information.
From language bindings, you can set the se:name capability to change output video file name dynamically. For example, in Python binding:
from selenium.webdriver.chrome.options import Options as ChromeOptions
from selenium import webdriver
options = ChromeOptions()
options.set_capability('se:recordVideo', True)
options.set_capability('se:screenResolution', '1920x1080')
options.set_capability('se:name', 'test_visit_basic_auth_secured_page (ChromeTests)')
driver = webdriver.Remote(options=options, command_executor="http://localhost:4444")
driver.get("https://selenium.dev")
driver.quit()
After test executed, under (${PWD}/assets) you can see the video file name in path /<sessionId>/test_visit_basic_auth_secured_page_ChromeTests.mp4
The file name will be trimmed to 255 characters to avoid long file names. Moreover, the space character will be replaced by _, and only the characters alphabets, numbers, - (hyphen), and _ (underscore) are retained in the file name. (This feat is available once this PR merged)
tzdata is installed in based images, and you can set the time zone in container by using the env variable TZ.
By default, the time zone is set to UTC.
List of supported time zones can be found here. For example:
$ docker run --rm --entrypoint="" -e TZ=Asia/Ho_Chi_Minh selenium/node-chromium:latest date +%FT%T%Z
2024-08-28T18:19:26+07
Get started to deploy Selenium Grid on Kubernetes, you can refer to YAML files in the kubernetes directory.
To simplify the deployment process, hide the complexity of Kubernetes objects, and provide a more straightforward way to deploy Selenium Grid on Kubernetes, we offer a Helm chart to deploy Selenium Grid to Kubernetes. Read more details at the Helm chart README and chart CONFIGURATION.
You can pass SE_OPTS variable with additional command line parameters for starting a hub or a node.
$ docker run -d -p 4444:4444 -e SE_OPTS="--log-level FINE" --name selenium-hub selenium/hub:4.53.0-20261120
You can pass SE_JAVA_OPTS environment variable to the Java process.
$ docker run -d -p 4444:4444 -e SE_JAVA_OPTS=-Xmx512m --name selenium-hub selenium/hub:4.53.0-20261120
Instead of adding arguments via the browser options from language bindings, for example:
options = ChromeOptions()
options.add_argument('--incognito')
options.add_argument('--disable-dev-shm-usage')
driver = webdriver.Remote(options=options, command_executor="http://localhost:4444/wd/hub")
You also can proactive to force applying arguments directly from (node, standalone or node-docker) container environment variables. Define the environment variable with name starts with SE_BROWSER_ARGS_ and following by config key is up to you (ensure those are unique when you define multiple arguments). For example:
docker run -d -p 4444:4444 \
-e SE_BROWSER_ARGS_INCOGNITO=--incognito \
-e SE_BROWSER_ARGS_DISABLE_DSHM=--disable-dev-shm-usage \
selenium/standalone-chrome:latest
List chromium command-line arguments for your reference.
Note: Currently, this is applicable for node browsers Chrome/Chromium, Edge.
The Nodes register themselves through the Event Bus. When the Grid is started in its typical Hub/Node setup, the Hub will be the one acting as the Event Bus, and when the Grid is started with all its five elements apart, the Event Bus will be running on its own.
In both cases, it is necessary to tell the Node where the Event Bus is, so it can register itself. That is
the purpose of the SE_EVENT_BUS_HOST, SE_EVENT_BUS_PUBLISH_PORT and SE_EVENT_BUS_SUBSCRIBE_PORT environment
variables.
In some cases, for example, if you want to tag a node, it might be necessary to supply a custom stereotype to the node config. The environment variable SE_NODE_STEREOTYPE
sets the stereotype entry in the node's config.toml. An example config.toml file can be found here: Setting custom capabilities for matching specific Nodes.
Here is an example with the default values of these environment variables:
$ docker run -d \
-e SE_EVENT_BUS_HOST=<event_bus_ip|event_bus_name> \
-e SE_NODE_STEREOTYPE="{\"browserName\":\"${SE_NODE_BROWSER_NAME}\", \"browserVersion\":\"${SE_NODE_BROWSER_VERSION}\", \"platformName\":\"${SE_NODE_PLATFORM_NAME}\"}" \
--shm-size="2g" selenium/node-chrome:4.53.0-20261120
In another case, if you want to retain the default Node stereotype and append additional capabilities, you can use the SE_NODE_STEREOTYPE_EXTRA environment variable to set your capabilities. Those will be merged to the default stereotype. For example:
$ docker run -d \
-e SE_EVENT_BUS_HOST=<event_bus_ip|event_bus_name> \
-e SE_NODE_STEREOTYPE_EXTRA="{\"myApp:version\":\"beta\", \"myApp:publish:\":\"public\"}" \
--shm-size="2g" selenium/node-chrome:4.53.0-20261120
This help setting custom capabilities for matching specific Nodes. For example, you added your custom capabilities when starting the Node, and you want assign a test to run on that Node which matches your capabilities. For example in test code:
options = ChromeOptions()
options.set_capability('myApp:version', 'beta')
options.set_capability('myApp:publish', 'public')
driver = webdriver.Remote(options=options, command_executor=SELENIUM_GRID_URL)
Noted: Your custom capabilities with key values should be in W3C capabilities convention, extension capabilities key must contain a ":" (colon) character, denoting an implementation specific namespace.
Noted: Ensure that Node config detect-drivers = false in config.toml (or --detect-drivers false in CLI option) to make feature setting custom capabilities for matching specific Nodes get working.
In addition, default Node stereotype includes capability se:containerName which can visible in node capabilities, or session capabilities to identify the container name where the node/session is running. The prefixed se:containerName is not included in slot matcher. By default, value is getting from hostname command in container, this value is equivalent to the container_id that you saw via docker ps command. If you want to override this value, you can set the environment variable SE_NODE_CONTAINER_NAME to your desired value. For example, when deploy to Kubernetes cluster, you can assign Pod name to env var SE_NODE_CONTAINER_NAME to track a node is running in which Pod.
env:
- name: SE_NODE_CONTAINER_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
In an advanced case, where you control to spawn up a Node container, let it register to Hub, and then trigger a test to be assigned exactly to run on that Node. By default, the value of command $(hostname) is added to capability name container:hostname in Node stereotype. Combine with above feature setting custom capabilities for matching specific Nodes. You can use the hostname of the Node container just spawned up and set it as a custom capability. For example, in Python binding:
$ docker run -d --name my-node-1 -e SE_EVENT_BUS_HOST=localhost \
--shm-size="2g" selenium/node-chrome:4.53.0-20261120
$ docker exec -i my-node-1 hostname
a6971f95bbab
options = ChromeOptions()
options.set_capability('container:hostname', 'a6971f95bbab')
driver = webdriver.Remote(options=options, command_executor=SELENIUM_GRID_URL)
Noted: Those above changes require new image tag where the changeset is included & released.
Relaying commands to a service endpoint that supports WebDriver. It is useful to connect an external service that supports WebDriver to Selenium Grid. An example of such service could be a cloud provider or an Appium server. In this way, Grid can enable more coverage to platforms and versions not present locally.
The following is an en example of configuration relay commands.
docker-compose-v3-test-node-relay.yml
If you want to relay commands only, selenium/node-base is suitable and lightweight for this purpose.
In case you want to configure node with both browsers and relay commands, respective node images can be used.
To use environment variables for generate relay configs, set SE_NODE_RELAY_URL and other variables as below. Those will be used to generate the default relay config in TOML format looks like below.
[relay]
url = "${SE_NODE_RELAY_URL}"
status-endpoint = "${SE_NODE_RELAY_STATUS_ENDPOINT}"
protocol-version = "${SE_NODE_RELAY_PROTOCOL_VERSION}"
configs = [ '${SE_NODE_RELAY_MAX_SESSIONS}', '{"browserName": "${SE_NODE_RELAY_BROWSER_NAME}", "platformName": "${SE_NODE_RELAY_PLATFORM_NAME}", "appium:platformVersion": "${SE_NODE_RELAY_PLATFORM_VERSION}"}' ]
Instead of input value for each environment variable to construct the default relay stereotype, you can use the SE_NODE_RELAY_STEREOTYPE environment variable to overwrite the default relay stereotype with your custom stereotype.
In another case, if you want to retain the default relay stereotype and append additional capabilities, you can use the SE_NODE_RELAY_STEREOTYPE_EXTRA environment variable to set your capabilities. Those will be merged to the default relay stereotype.
To run a sample test with the relayed node, you can clone the project and try below command:
make test_node_relay
By default, Selenium is reachable at http://127.0.0.1:4444/. Selenium can be configured to use a custom subpath by specifying the SE_SUB_PATH
environmental variable. In the example below Selenium is reachable at http://127.0.0.1:4444/selenium-grid/
$ docker run -d -p 4444:4444 -e SE_SUB_PATH=/selenium-grid/ --name selenium-hub selenium/hub:4.53.0-20261120
By default, nodes start with a screen resolution of 1920 x 1080 with a color depth of 24 bits and a dpi of 96.
These settings can be adjusted by specifying SE_SCREEN_WIDTH, SE_SCREEN_HEIGHT, SE_SCREEN_DEPTH, and/or SE_SCREEN_DPI
environmental variables when starting the container.
docker run -d -e SE_SCREEN_WIDTH=1366 -e SE_SCREEN_HEIGHT=768 -e SE_SCREEN_DEPTH=24 -e SE_SCREEN_DPI=74 selenium/standalone-firefox:4.53.0-20261120
In some use cases, you might need to set the Grid URL to the Node, for example, if you'd like to access the BiDi/CDP endpoint.
This is also needed when you want to use the new RemoteWebDriver.builder() or Augmenter() present in Selenium 4
(since they setup the BiDi/CDP connection implicitly). You can do that through the SE_NODE_GRID_URL environment
variable, eg -e SE_NODE_GRID_URL=http://<hostMachine>:4444. Setting this env var is needed if you want to see the live view while sessions are executing.
Grid has a default session timeout of 300 seconds, where the session can be in a stale state until it is killed. You can use
SE_NODE_SESSION_TIMEOUT to overwrite that value in seconds.
A new session request is placed in the Session Queue before it is processed, and the request sits in the queue until a matching slot is found across the registered Nodes. However, the new session request might timeout if no slot was found. By default, a request will stay in the queue for up to 300 seconds before it a timeout is reached. In addition, an attempt to process the request is done every 5 seconds (by default).
It is possible to override those values through environment variables in the Hub and the SessionQueue (SE_SESSION_REQUEST_TIMEOUT
and SE_SESSION_RETRY_INTERVAL). For example, a timeout of 500 seconds would be SE_SESSION_REQUEST_TIMEOUT=500 and a retry
interval of 2 seconds would be SE_SESSION_RETRY_INTERVAL=2.
By default, only one session is configured to run per container through the SE_NODE_MAX_SESSIONS environment variable. It is
possible to increase that number up to the maximum available processors, this is because more stability is achieved when one
container/browser has 1 CPU to run.
However, if you have measured performance and based on that, you think more sessions can be executed in each container, you can
override the maximum limit by setting both SE_NODE_MAX_SESSIONS to a desired number and SE_NODE_OVERRIDE_MAX_SESSIONS to
true. Nevertheless, running more browser sessions than the available processors is not recommended since you will be overloading
the resources.
Overriding this setting has an undesired side effect when video recording is enabled since more than one browser session might be captured in the same video.
Firefox, Chrome, When using headless mode, there's no need for the Xvfb server to be started.
To avoid starting the server you can set the SE_START_XVFB environment variable to false
(or any other value than true), for example:
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \
-e SE_START_XVFB=false --shm-size="2g" selenium/node-chrome:4.53.0-20261120
For more information, see this GitHub issue.
Noted:
SE_START_XVFB is required to be set to true to run in --headless=new mode.--headless only runs in the new mode, so you need to set SE_START_XVFB to true when using --headless mode.In some environments, like Docker Swarm or Kubernetes, it is useful to shut down the Node or Standalone
container after N tests have been executed. For example, this can be used in Kubernetes to terminate the
pod and then scale a new one after N sessions. Set the environment variable SE_DRAIN_AFTER_SESSION_COUNT to
a value higher than zero to enable this behaviour.
$ docker run -e SE_DRAIN_AFTER_SESSION_COUNT=5 --shm-size="2g" selenium/standalone-firefox:4.53.0-20261120
With the previous command, the Standalone container will shut down after 5 sessions have been executed.
In long-running containers, it can happen that browsers leave some leftovers. These can be stuck browser processes
of jobs that have already finished but failed to fully stop the browser, or temporary files written to the /tmp
file system (notably on Chrome-based browsers). To avoid these filling up resources like process IDs and file system
usage in the container, there is an automatic cleanup script running every hour in the node containers. This will
clean up old processes and old temporary files. By default, this is disabled. When enabled, this will clean up browsers
running for longer than 2 hours, and files older than 1 day. These can be enabled and tweaked with the following
environment variables:
SE_ENABLE_BROWSER_LEFTOVERS_CLEANUP: default value false, set to true to enable the cleanup.SE_BROWSER_LEFTOVERS_INTERVAL_SECS: default value 3600 (1 hour), cleanup interval in seconds.SE_BROWSER_LEFTOVERS_PROCESSES_SECS: default value 7200 (2 hours), browsers running for longer than this time will be killed.SE_BROWSER_LEFTOVERS_TEMPFILES_DAYS: default value 1 (1 day), files generated by Chrome-based browsers in /tmp will be removed after these number of days (ignored when using Firefox).If you use Selenium for long-running sessions and expect browsers to be running for longer than 2 hours, either do
not set SE_ENABLE_BROWSER_LEFTOVERS_CLEANUP to true (leave the default value of false), or tweak
SE_BROWSER_LEFTOVERS_PROCESSES_SECS to set a value higher than your expected long-running browser processes.
$ docker run -e SE_ENABLE_BROWSER_LEFTOVERS_CLEANUP=true --shm-size="2g" selenium/node-chrome:4.53.0-20261120
With the previous command, the cleanup will be enabled with the default timings.
$ docker run -e SE_ENABLE_BROWSER_LEFTOVERS_CLEANUP=true \
-e SE_BROWSER_LEFTOVERS_INTERVAL_SECS=7200 \
-e SE_BROWSER_LEFTOVERS_PROCESSES_SECS=3600 \
-e SE_BROWSER_LEFTOVERS_TEMPFILES_DAYS=2 \
--shm-size="2g" selenium/node-chrome:4.53.0-20261120
With the previous command, the cleanup will be enabled, but will run every 2 hours (instead of 1), will kill browsers running longer than 1 hour (instead of 2 hours), and will remove temp files older than 2 days (instead of 1).
Few variables output like password, secret, etc. are masked in console logs. For debugging purposes, you can disable it by setting SE_MASK_SECRETS to false
While creating bash script, your can mask the output by using syntax echo "Current value is $(mask ${YOUR_VARIABLE})
SE_MASK_SECRETS_MIN_LENGTH default is 3. It means a long string will be masked to *** to avoid exposing length for brute force attack.
By default, there are default self-signed certificates available in the image in location /opt/selenium/secrets includes
server.jks: truststore file to configure for JVM via system property javax.net.ssl.trustStore when start the server.server.pass: file contains the truststore password for JVM via system property javax.net.ssl.trustStorePassword.tls.crt: Server certificate for https connection is set to Selenium option --https-certificate.tls.key: Server private key (in PKCS8 format) for https connection is set to Selenium option --https-private-key.There are environment variables to configure the secure connection:
| Environment variables | Default | Option of | Description |
|---|---|---|---|
| SE_ENABLE_TLS | false |
Enable secure connection with default configs | |
| SE_JAVA_SSL_TRUST_STORE | /opt/selenium/secrets/server.jks |
JVM | |
| SE_JAVA_SSL_TRUST_STORE_PASSWORD | /opt/selenium/secrets/server.pass |
JVM | |
| SE_JAVA_DISABLE_HOSTNAME_VERIFICATION | true |
JVM | Disable host checks for components internally |
| SE_HTTPS_CERTIFICATE | /opt/selenium/secrets/tls.crt |
Selenium | Set to CLI option --https-certificate |
| SE_HTTPS_PRIVATE_KEY | /opt/selenium/secrets/tls.key |
Selenium | Set to CLI option --https-private-key |
Via volume mount, you can replace the default certificates with your own certificates.
The self-signed certificate also needs to be trusted by the client (add to system widely bundle trusted CA) to avoid error message relates to SSL handshake when creating RemoteWebDriver.
Refer to sample: docker-compose-v3-full-grid-secure.yml
Different browsers have different ways to set the language and locale from binding.
Firefox can be configured to use a specific language and locale by setting the profile preference when create WebDriver from binding. In addition, language pack need to be installed as add-on for browser UI language to take effect. For example, to set the browser language and locale to vi-VN, you can use the following steps:
Get the latest Firefox language pack for the desired language e.g. https://download.mozilla.org/?product=firefox-langpack-latest-SSL&lang=vi. Then, you can install the language pack as an add-on when creating the RemoteWebDriver instance.
profile = webdriver.FirefoxProfile()
profile.set_preference('intl.accept_languages', 'vi-VN,vi')
profile.set_preference('intl.locale.requested', 'vi-VN,vi')
options = FirefoxOptions()
options.profile = profile
driver = webdriver.Remote(options=options, command_executor="http://selenium-hub:4444/wd/hub")
webdriver.Firefox.install_addon(driver, "/local/path/to/vi.xpi")
driver.get('https://google.com')
There is a script to get all available language packs for a given Firefox version. You can run the script to get the language packs to your source. For example:
FIREFOX_VERSION=$(docker run --rm --entrypoint="" selenium/node-firefox:latest firefox --version | awk '{print $3}') \
&& ./NodeFirefox/get_lang_package.sh ${FIREFOX_VERSION} /local/path/to/download
Or, you can mount the container directory $(readlink -f $(which firefox)))/distribution/extensions to host directory to access packs were pre-built in the container for using in your test script.
Supervisor is used to manage processes and logs in the container. Few configuration for supervisord can be set via environment variables as below:
| Environment variables | Default | supervisord config |
|---|---|---|
| SE_SU |
SeleniumHQ/docker-selenium is a public repo on GitHub by SeleniumHQ. Provides a simple way to run Selenium Grid with Chrome, Firefox, and Edge using Container Platform, making it easier to perform browser automation at scale.
It declares no license on GitHub. Public does not mean open source: without a license, nobody is granted the right to reuse it.
Its maker tagged it for macOS, Windows and Linux, or as Docker or cross-platform. That is declared by the maker; Take My Repo has not tested it.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.

A list of Free Software network services and web applications which can be hosted on your own servers

Its last change on GitHub was on 2026-11-22. GitHub counts 47 open issues and pull requests. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.
Stealth Chromium that passes every bot detection test. Drop-in Playwright replacement with source-level fingerprint patches. 50+ tests passed.
web scraping in parallel with Selenium Grid and Docker

Cross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
Open Source record and playback test automation for the web.
WebDriver compatible driver for HtmlUnit headless browser.
This page is also available as structured data, with the same sources and dates.
/api/v1/resources/gh/SeleniumHQ/docker-seleniumTake My Repo has not tested this on your machine. Requirements come from the project's own documentation.