# docker-selenium: running Selenium Grid in containers

> The official Docker images for Selenium Grid, published by the Selenium project. They package the Hub, the Nodes and the browser binaries so you can start a Grid with one command, and they scale to Kubernetes through a Helm chart.

**SeleniumHQ/docker-selenium** — 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

- Repository: https://github.com/SeleniumHQ/docker-selenium
- Website: http://www.selenium.dev/docker-selenium/
- Stars: 8,656 · Forks: 2,547
- Language: Go
- License: NOASSERTION
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/seleniumhq-docker-selenium

## The problem docker-selenium solves for browser automation

Running a browser test suite on a developer laptop works until the suite has to run somewhere else. The browser version differs, the display server is missing, the driver binary does not match, and the failure looks like a test failure rather than an environment failure. docker-selenium addresses that by publishing container images that already contain the Selenium Grid server and the browser, so the environment travels with the image instead of being reconstructed on each machine.

The audience is narrow and identifiable. It is teams that already write tests against Selenium WebDriver and want a Grid they can start, throw away and start again. It is also teams that need several browsers in one run and do not want to maintain three virtual machines. The README frames the project as a way to run Selenium Grid with Chrome, Firefox and Edge using a container platform, which is exactly the scope: it is infrastructure for WebDriver sessions, not a test framework and not a browser farm product.

## Standalone, Hub and Nodes, and the fully distributed topology

The README describes three execution modes, and the difference between them is how many processes are involved and whether they live in one container.

Standalone mode puts the Grid server and one browser in a single container. A test connects to that container and gets a session. This is the smallest useful unit and the one the quick start uses.

Hub and Nodes mode splits the roles. The Hub image receives session requests and routes them; the Node images register with the Hub and each one offers a browser. You run one Hub container and one or more Node containers, and the Grid decides which Node takes the session. This is the mode that lets you grow capacity by starting more Node containers rather than by making one container larger.

Fully distributed mode goes further and separates Router, Queue, Distributor, EventBus, SessionMap and Nodes. The repository layout reflects this: there are top-level directories named Distributor, EventBus, Router, SessionQueue, Sessions and NodeBase, alongside Hub, Standalone and the per-browser Node directories. That structure is the clearest signal of how the project is organised. The Grid server components are their own images, and the browser-specific Node images build on a shared base. If you are debugging a routing problem, the component you need to look at has its own directory and its own image.

There is a fourth arrangement worth naming because it behaves differently from the others. Dynamic Grid, covered in its own README section, starts node browser containers on demand from a single container. The README gives separate subsections for configuration, for sharing volumes from the Dynamic Grid container to node browser containers, for Hub and Node roles, for Standalone roles, for running it across different machines or VMs, for Docker Compose, for configuring the child containers, and for video recording, screen resolution and time zones. The volume-sharing subsection is the one to read carefully: child containers are separate containers, so anything the browser must see has to be mounted into them explicitly.

## Installing the images and running a first session

The images are published to Docker Hub under the selenium organisation. The README names three of them directly: selenium/hub, selenium/node-chrome and selenium/standalone-chrome. There is no package manager step. You pull the image and run it, and the README's quick start uses standalone mode.

The README's system recommendations section is worth reading before the first run, because the default shared memory size in a container is small and Chrome will fail with it. The README does not state a required value for the shared memory flag, so the value you choose is a starting point to adjust if sessions fail.

The README's quick start section is the place to copy the exact run command from, including the published ports for the Grid and for noVNC. The Grid endpoint is what a WebDriver client connects to; the noVNC port lets you watch the browser session in a browser tab instead of guessing what went wrong. Copy the command as written rather than reconstructing it, since the flags and the port numbers are part of what the README is asserting.

Once the container is up, point a WebDriver client at the Grid endpoint. If the session starts and the page title comes back, the Grid and the browser are working. If it does not, check the container logs before touching the test code, because in this setup a connection error usually means the container is not healthy rather than that the test is wrong.

For Hub and Nodes, the repository ships Docker Compose files at the top level. docker-compose-v3.yml is the basic Grid composition, and the README's execution modes section is where the mode choices are explained. The Compose files are the fastest way to see a working multi-container configuration, because they encode the port and environment variable wiring that is tedious to get right by hand. There is also a docker-compose-v3-full-grid.yml for the fully distributed components, plus variants for tracing, monitoring, video, authentication and Swarm. Reading one of these files is more informative than reading prose about it.

## Configuration through environment variables, and where the README stops

Almost everything you would want to change is an environment variable. The README's configuring the containers section lists the families: SE_OPTS for Selenium configuration options, SE_JAVA_OPTS for JVM options, SE_BROWSER_ARGS_* for arguments passed when launching the browser, node configuration options, node relay commands, sub path, screen resolution, grid URL and session timeout, session request timeout, concurrency per container, headless mode, stopping a Node or Standalone after N sessions, automatic browser leftovers cleanup, masking sensitive information in console logs, secure connection, and browser language and locale.

That list is long, and the README does not document every variable inline. It points to ENV_VARIABLES.md at the repository root. This is the practical constraint to plan around: the README is an index of capabilities, and the actual key names and accepted values live in that separate file. Before you write a Compose file, open ENV_VARIABLES.md.

A few of these deserve a note. Stopping a Node or Standalone after N sessions is a deliberate hedge against state leaking between sessions; if you enable it, you are accepting container restarts as normal operation, which means your orchestration has to restart them. Automatic browser leftovers cleanup addresses the same class of problem from the other direction. Masking sensitive information in console logs is a small setting with a large consequence: without it, credentials passed through the session can end up in logs you collect centrally.

## Kubernetes and Dynamic Grid are the scaling paths, with different costs

The README states that a Helm chart enables the creation of a Selenium Grid Server in Kubernetes, and links to Artifact Hub under the selenium-grid repository. The repository has a charts directory and a NodeKubernetes directory, and the topics list includes helm-chart, kubernetes, kubernetes-selenium-grid and keda. KEDA appears in the topics and there is a .keda directory and a .keda-external-scaler directory, which indicates event-driven autoscaling of Grid nodes is part of the project's scope.

This is the path for teams that already run Kubernetes. The trade-off is that you inherit Kubernetes as a dependency for your test infrastructure. A Grid that fits in one Compose file on a build agent becomes a set of deployments, services and scaling rules. For a test suite that runs for a few minutes per pull request, that is usually more machinery than the problem needs.

Dynamic Grid is the other scaling path and it does not require Kubernetes. It runs on a Docker host and creates browser containers as sessions arrive. The README documents its configuration, volume sharing, role variants, cross-machine use and Docker Compose usage. The cost here is different: because the browser runs in a child container, the Dynamic Grid container needs access to the Docker daemon, and any file the browser must read or write has to be mounted into the child. The README's dedicated subsection on sharing volumes exists because this is the part people get wrong. Neither path is a free upgrade from standalone mode; both add a component that can fail independently of your tests.

## Where docker-selenium is the wrong tool

The images are general-purpose. That is the design, and it is also the limit. If your suite depends on a browser extension loaded at startup, a specific font set, a corporate proxy configured at the OS level, or a browser build that is not Chrome, Firefox, Chromium or Edge, you are working against the image rather than with it. The per-browser Node directories in the repository (NodeChrome, NodeChromium, NodeEdge, NodeFirefox, and NodeAllBrowsers for a single image with all of them) show the browsers the project builds for. Anything outside that list is your own image to maintain.

Video recording is documented, including dynamic file names based on test metadata, uploading recordings, and retaining recordings for failed sessions only. The Video directory and the several docker-compose-v3-video-* files show this is a maintained capability rather than an afterthought. Still, recording adds a process to the container and produces files you must store and eventually delete. Teams that enable it by default tend to discover the storage cost later.

Finally, this is not a tool for running tests. It provides the Grid and the browsers; the test code, the test runner and the reporting are yours. If you are looking for a service that executes a suite and returns a report, this is one layer below that.

## How docker-selenium compares with running your own Grid

The direct alternative is installing Selenium Grid yourself: download the Selenium server, install a browser and a matching driver on each machine, start the server, and register the nodes. That gives you complete control over the browser build, the OS packages and the machine's lifetime. It also means you own the version matrix. When the server, the driver and the browser drift apart, you debug it.

docker-selenium moves that work into image builds. You pin a tag, and the server, drivers and browsers inside that tag were assembled together. The trade-off is the reverse of the DIY approach: you get consistency but you give up the ability to change what is inside without building a derived image. The repository's Makefile shows how the images are assembled, with build arguments for the Selenium version, the author and the tag, and it is the file to read if you decide to build your own variant rather than pull one.

A second alternative is a commercial browser testing cloud. That removes the infrastructure entirely and adds per-session cost and a network hop to every command. docker-selenium keeps the browser on your own hardware, which matters when the application under test is only reachable from inside your network.

## Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-18. Releases are frequent and follow the Selenium version: 4.49.0-20260909 was published on 2026-09-17, 4.48.0-20260905 on 2026-09-05, and a nightly build was published on 2026-09-21. The tag format carries both the Selenium version and a build date, which means you can pin to an exact build rather than tracking latest. That is the upgrade strategy the tags invite: pin a dated tag, and move it deliberately.

The README also documents nightly images and dev and beta channel browser images, with separate sections for standalone mode and for running them on the Grid. These track browsers ahead of their stable release. They are useful for finding out early that an upcoming browser version breaks your application, and they are a poor default for a release pipeline, because the browser underneath you changes without a corresponding change in your repository. The README's advice to watch releases is consistent with that: it asks readers to add themselves as a releases-only watcher to get notifications.

The README states the source is available under the Apache License 2.0 and links to LICENSE.md. The repository metadata reports the licence as NOASSERTION, which is a machine classification of the repository rather than a statement about the licence text. If the licence matters to your organisation, read LICENSE.md and the licences of the browsers and drivers bundled in the image, since those are separate works with their own terms. That is not legal advice, and it is the reason the two sources disagree.

## Conclusion

Adopt docker-selenium if you need a disposable, reproducible Grid for CI or for a small internal test fleet, and start with the standalone-chrome image before adding Hub and Nodes. Do not adopt it if your tests depend on a browser profile, extension or OS-level setting that the image does not expose, because the container is the boundary. Verify first that the tag you intend to pin exists in the Selenium Docker Hub registry and that the environment variables you need are listed in ENV_VARIABLES.md, since the README defers to that file rather than documenting every key inline.

## FAQ

### What is docker-selenium used for?

It packages Selenium Grid and browsers into container images so you can run WebDriver sessions without installing a browser and a matching driver on each machine. The README describes running Grid with Chrome, Firefox and Edge on a container platform.

### How is Docker used in automation testing?

In this project Docker is the delivery mechanism for the Grid: the Hub image routes sessions and the Node images each offer a browser, so capacity is added by starting more containers. The README also documents a Dynamic Grid mode that creates browser containers on demand.

### What is Selenium used for?

Selenium is the browser automation tool whose Grid server these images package. The README's scope is running that Grid in containers with Chrome, Firefox and Edge; the tests themselves are written by you against the WebDriver API.

## Sources

- [Issues](https://github.com/SeleniumHQ/docker-selenium/issues)
- [Project website](http://www.selenium.dev/docker-selenium/)
- [README](https://github.com/SeleniumHQ/docker-selenium/blob/trunk/README.md)
- [Releases](https://github.com/SeleniumHQ/docker-selenium/releases)
- [SeleniumHQ/docker-selenium on GitHub](https://github.com/SeleniumHQ/docker-selenium)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/seleniumhq-docker-selenium