Ask DeepWiki

Docker images for the Selenium Grid Server

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. - Hub: - Node-Chrome: - Standalone-Chrome:

Helm Chart enables the creation of a Selenium Grid Server in Kubernetes at

Community

Do you need help to use these Docker images? Talk to us at https://www.selenium.dev/support/

Contents

• Community
• Contents
• System Recommendations
• Quick start
• Try them out in a ready-to-use GitPod environment!
• Experimental Multi-Arch amd64/aarch64/armhf Images
• Nightly Images
• Dev and Beta Channel Browser Images
• Dev and Beta Standalone Mode
• Dev and Beta on the Grid
• Single Node/Standalone Image With All Browsers
• Environment Variables
• Execution modes
• Standalone
• Hub and Nodes
• Fully distributed mode - Router, Queue, Distributor, EventBus, SessionMap and Nodes
• Video recording
• Video recording with dynamic file name based on metadata in tests
• Video recording and uploading
• Retain recordings for failed sessions only
• Dynamic Grid
• Configuration example
• Share volumes config of Dynamic Grid container to node browser containers
• Execution with Hub & Node roles
• Execution with Standalone roles
• Using Dynamic Grid in different machines/VMs
• Execution with Docker Compose
• Configuring the child containers
• Video recording, screen resolution, and time zones in a Dynamic Grid
• Time zone configuration via env variable
• Deploying to Kubernetes
• Configuring the containers
• SE_OPTS Selenium Configuration Options
• SE_JAVA_OPTS Java Environment Options
• SE_BROWSER_ARGS_* Add arguments for launching browser
• Node configuration options
• Node configuration relay commands
• Setting Sub Path
• Setting Screen Resolution
• Grid Url and Session Timeout
• Session request timeout
• Increasing session concurrency per container
• Running in Headless mode
• Stopping the Node/Standalone after N sessions have been executed
• Automatic browser leftovers cleanup
• Mask sensitive information in console logs
• Secure Connection
• Browser language and locale
• Managing processes in container
• Building the images
• Build the images with specific versions
• Upgrade browser version in the images
• Upgrade browser and driver versions in the images
• Waiting for the Grid to be ready
• Adding a HEALTHCHECK to the Grid
• Using a bash script to wait for the Grid
• Install certificates for Chromium-based browsers
• Alternative method: Add certificates to existing Selenium based images for browsers
• Debugging
• Using a VNC client
• Using your browser (no VNC client is needed)
• Disabling VNC
• Tracing in Grid
• Troubleshooting
• --shm-size="2g"
• Headless
• Mounting volumes to retrieve downloaded files
• Mounting volumes to retrieve video files
• Stargazers over time

System Recommendations

• Docker Engine 26.1.4 or later
• Docker Compose v2.34.0 or later
• Docker Buildx v0.25.0 or later
• Kubernetes v1.26.15 or later

Quick start

1. Start a Docker container with Firefox

docker run -d -p 4444:4444 -p 7900:7900 --shm-size="2g" selenium/standalone-firefox:4.48.0-20260905

1. Point your WebDriver tests to http://localhost:4444

2. That's it!

3. (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.

Try them out in a ready-to-use GitPod environment!

Open in Gitpod

Experimental Multi-Arch amd64/aarch64/armhf Images

From image tag based 4.21.0 onwards, the architectures supported by this project are as below:

Browser images in multi-arch

The following browsers are available in multi-arch images:

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

• Mozilla Firefox now is available for Linux/ARM64 via APT stable channel from v136+. The Firefox (node and standalone) images are available in multi-arch.

~~Multi-arch images are tested on CircleCI with resource class Linux/ARM64. See the status below.~~ (Moved to GitHub Actions)

History of the multi-arch images

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.

Build the multi-arch images locally

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

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

Dev and Beta Channel Browser Images

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.

Dev and Beta Standalone Mode

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

Dev and Beta on the Grid

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.

Single Node/Standalone Image With All Browsers

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: - Prefer a single container with "all-in-one" includes Selenium Grid and popular browsers. - Don't care about the image size, prefer the convenience. - Lightweight workload, able to figure out for yourself the resource consumption.

According to multi-arch support, browsers are available in images selenium/node-all-browsers and selenium/standalone-all-browsers would be different per architecture.

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

Environment Variables

Checkout full list of environment variables here.

How to update or contribute to list of environment variables? Follow below steps:

1. Refresh the list to pick up new environment variables or default value

   bash make update_list_env_vars

   The script can be updated in scripts/generate_list_env_vars/extract_env.py.

2. Update the description for each environment variable in the file scripts/generate_list_env_vars/description.yaml.

3. Run the command in step (1) one more time to update the list of environment variables with new descriptions.

Execution modes

Standalone

Firefox Firefox

docker run -d -p 4444:4444 --shm-size="2g" selenium/standalone-firefox:4.48.0-20260905

Chrome Chrome

docker run -d -p 4444:4444 --shm-size="2g" selenium/standalone-chrome:4.48.0-20260905

Edge Edge

docker run -d -p 4444:4444 --shm-size="2g" selenium/standalone-edge:4.48.0-20260905

All browsers in single container

docker run -d -p 4444:4444 --shm-size="3g" selenium/standalone-all-browsers:4.48.0-20260905

Note: Only one Standalone container can run on port 4444 at the same time.

Hub and Nodes

There are different ways to run the images and create a Grid with a Hub and Nodes, check the following options.

Docker networking

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.

macOS/Linux

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.48.0-20260905
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \
    --shm-size="2g" \
    selenium/node-chrome:4.48.0-20260905
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \
    --shm-size="2g" \
    selenium/node-edge:4.48.0-20260905
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \
    --shm-size="2g" \
    selenium/node-firefox:4.48.0-20260905

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.48.0-20260905
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub \
    --shm-size="3g" \
    selenium/node-all-browsers:4.48.0-20260905

Windows PowerShell

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.48.0-20260905
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub `
    --shm-size="2g" `
    selenium/node-chrome:4.48.0-20260905
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub `
    --shm-size="2g" `
    selenium/node-edge:4.48.0-20260905
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub `
    --shm-size="2g" `
    selenium/node-firefox:4.48.0-20260905

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.48.0-20260905
$ docker run -d --net grid -e SE_EVENT_BUS_HOST=selenium-hub `
    --shm-size="3g" `
    selenium/node-all-browsers:4.48.0-20260905

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

Using different machines/VMs

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.

Hub - Machine/VM 1

$ docker run -d -p 4442-4444:4442-4444 --name selenium-hub selenium/hub:4.48.0-20260905

Node Chrome - Machine/VM 2

macOS/Linux

$ 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.48.0-20260905

Windows PowerShell

$ 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.48.0-20260905

Node Edge - Machine/VM 3

macOS/Linux

$ 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.48.0-20260905

Windows PowerShell

$ 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.48.0-20260905

Node Firefox - Machine/VM 4

macOS/Linux

$ 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.48.0-20260905

Windows PowerShell

$ 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.48.0-20260905

Node Chrome - Machine/VM 4

macOS/Linux

$ 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.48.0-20260905

Windows PowerShell

$ 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.48.0-20260905

Docker Compose

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.

Version 2

docker-compose-v2.yml

Version 3

docker-compose-v3.yml

To stop the Grid and cleanup the created containers, run docker compose down.

Version 3 with Swarm support

docker-compose-v3-swarm.yml

Fully distributed mode - Router, Queue, Distributor, EventBus, SessionMap and Nodes

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

Distributor configuration

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.

Video recording

Tests execution can be recorded by using the selenium/video:ffmpeg-8.1-20260905 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: - If you have questions or feedback, please use the community contact points shown here. - Please report any bugs through GitHub issues, and provide all the information requested on the template. - Video recording for headless browsers is not supported. - Video recording tends to use considerable amounts of CPU. Normally you should estimate 1CPU per video container, and 1 CPU per browser container. - Videos are stored in the /videos directory inside the video container. Map a local directory to get the videos. - If you are running more than one video container, be sure to overwrite the video file name through the 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.48.0-20260905
$ docker run -d --net grid --name video -v /tmp/videos:/videos selenium/video:ffmpeg-8.1-20260905
# 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:

docker-compose-v3-video.yml

Video recording with dynamic file name based on metadata in tests

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: - Event-driven mode (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. - Shell/polling mode (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.

Video recording and uploading

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-20260905
    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.

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.

Reference

• 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 variables and default values for upload feature

Retain recordings for failed sessions only

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:

1. The test code fires a session event whose eventType contains a substring from SE_FAILURE_SESSION_EVENTS (default: :failed,:failure,:error,:aborted).
2. The session closes with an abnormal reason — TIMEOUT, NODE_REMOVED, or NODE_RESTARTED — instead of the normal QUIT_COMMAND.

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)

Firing session events from test code

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 is QUIT_COMMAND (not abnormal). In that case, firing a failure event before quit() 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.

Video recordings manager

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.48.0-20260905
    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

Dynamic Grid

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.

Configuration example

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.48.0-20260905", '{"browserName": "firefox"}',
    "selenium/standalone-chrome:4.48.0-20260905", '{"browserName": "chrome"}',
    "selenium/standalone-edge:4.48.0-20260905", '{"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-20260905"

# 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.

Share volumes config of Dynamic Grid container to node browser containers

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

Execution with Hub & Node roles

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.

macOS/Linux

$ docker network create grid
$ docker run -d -p 4442-4444:4442-4444 --net grid --name selenium-hub selenium/hub:4.48.0-20260905
$ 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.48.0-20260905

Windows PowerShell

$ docker network create grid
$ docker run -d -p 4442-4444:4442-4444 --net grid --name selenium-hub selenium/hub:4.48.0-20260905
$ 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.48.0-20260905

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:

``` bash

README 内容较长，此处已截断，完整内容请查看 GitHub 仓库。