How to Use Multi-Architecture Docker Selenium Images

Use a Selenium image tag that publishes your host architecture and includes the browser you need. Docker selects the matching platform variant when it pulls a multi-architecture image. Selenium’s current image documentation lists Firefox and Chromium for AMD64 and ARM64; Chrome on ARM64 is available from version 150 onward, while Edge and Chrome for Testing are listed for AMD64 only. Check the exact tag’s browser matrix before relying on a combination.

For a local Firefox Grid, start with a version-pinned image and connect RemoteWebDriver to http://localhost:4444:

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

The example tag is the one documented in Selenium’s README at research time; verify that it remains available and supports your host architecture before use. Port 7900 is optional browser visualization. Selenium’s docker-selenium README documents image tags, browser support, and Grid configuration.

1. Understand how Docker selects an architecture

A multi-platform image reference points to a manifest list with platform-specific image manifests. When you pull it, Docker chooses the variant matching the host architecture. You usually do not need a separate image name for ARM64 and AMD64, but the requested browser and exact tag still need to support that platform. See Docker’s multi-platform builds documentation.

Selenium announced AMD64 and ARM64 image support beginning with image tag 4.21.0. That is a historical project threshold, not a guarantee that every browser is available on both architectures for every later tag. The current browser matrix is the relevant compatibility reference.

2. Choose the image for your host and browser

Host	Browser requirement	Guidance
AMD64	Chrome, Firefox, Edge, Chromium, or Chrome for Testing	Use the matching Selenium image and pin a full version tag.
ARM64	Firefox or Chromium	These browser families are listed for both architectures. Confirm support for the precise tag.
ARM64	Google Chrome	The current README describes Chrome via stable APT from v150 onward. Older Chrome versions may be AMD64-only; verify the tag’s CHROME_PLATFORMS and browser matrix.
ARM64	Edge or Chrome for Testing	These are listed as unavailable on ARM64. Use a supported browser or run that test on AMD64.

Selenium discourages running AMD64 browser images through emulation on ARM64. Browser emulation can have performance and stability problems, including browser launch failures. Prefer a native image and browser combination when available.

3. Start a standalone browser container

Standalone is the simplest choice for local development and a single browser endpoint. The default WebDriver endpoint is port 4444. The optional 7900 mapping makes browser activity viewable, and Selenium recommends allocating 2 GB of shared memory for browser containers.

Firefox

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

Chromium

This follows Selenium’s documented invocation pattern. For repeatable runs, replace latest with a full tag confirmed to support your platform.

docker run --rm -it \
  -p 4444:4444 -p 5900:5900 -p 7900:7900 \
  --shm-size="2g" \
  selenium/standalone-chromium:latest

Port 5900 is an optional visualization port in this invocation. Publish only the ports your workflow needs. To see container status and browser options for the exact image, consult the Selenium README.

4. Connect a test with RemoteWebDriver

Install the Selenium client library for your test language and use the remote endpoint at http://localhost:4444. The following Python example is runnable with the Selenium Python package installed:

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

options = Options()
# For selenium/standalone-chromium. Use Firefox Options with a Firefox image.
driver = webdriver.Remote(
    command_executor="http://localhost:4444",
    options=options,
)
try:
    driver.get("https://example.com")
    print(driver.title)
finally:
    driver.quit()

For Firefox, change the import and options class to selenium.webdriver.firefox.options.Options. The browser requested by the client must exist in the Selenium image; an architecture-compatible container alone does not make an absent browser available.

5. Use a distributed Hub and browser Nodes

Use a Hub with separate browser Nodes when tests need multiple browser containers or distributed capacity. Put the containers on one Docker network, use the same explicit Selenium version tag for Hub and Nodes, and set each Node’s event bus host to the Hub’s network name. Each node image must support the architecture of the machine running that node.

docker network create selenium-grid

docker run -d --name selenium-hub --network selenium-grid \
  -p 4442:4442 -p 4443:4443 -p 4444:4444 \
  selenium/hub:4.48.0

docker run -d --name firefox-node --network selenium-grid \
  --shm-size="2g" \
  -e SE_EVENT_BUS_HOST=selenium-hub \
  selenium/node-firefox:4.48.0

Use a release tag verified against Selenium’s current documentation; the version above illustrates keeping Hub and Node versions aligned. Connect clients to http://localhost:4444. Add other browser Nodes using the same pattern and the matching image, after confirming platform support.

6. Pin tags and make architecture explicit when needed

A full Selenium tag pins the Grid and browser image release more predictably than latest or a moving channel tag. Confirm that the chosen tag exists and has the required platform variant; browser availability can differ by release.

To inspect the host architecture and the image’s published platforms, use Docker’s standard inspection commands:

docker version --format '{{.Server.Arch}}'
docker buildx imagetools inspect selenium/standalone-firefox:4.48.0-20260905

When a workflow needs to request a specific platform explicitly, Docker accepts --platform, for example --platform linux/arm64. This selects a platform variant if the image publishes one; it does not add browser support to a tag that lacks that variant. Avoid forcing linux/amd64 on ARM64 for browser workloads unless you have a specific reason and have accounted for Selenium’s emulation warning.

7. Performance, reliability, and resource use

• Prefer native execution: Use an image/browser variant for the host architecture. Selenium warns that AMD64 emulation on ARM64 can be slow or unstable and can prevent browser startup.
• Allocate shared memory: Keep --shm-size="2g" for browser containers as in Selenium’s quick-start examples. This is a container resource setting, not a browser version or architecture selector.
• Choose standalone or Grid deliberately: Standalone has fewer moving parts for one local browser. Hub and Nodes add network and version coordination but allow browser containers to be distributed across hosts.
• Keep versions aligned: Pin full tags for reproducible runs and use a consistent Selenium release across Hub and Nodes.
• Check architecture per node: A mixed-architecture Grid can use separate native nodes, but each node’s browser image must publish the platform of that node’s host.
• Account for image size and browser count: An all-browsers image is convenient, while separate browser images can limit each container to the browser needed. Browser images consume meaningful memory and shared memory; provision the runner for the actual concurrent sessions.

8. Troubleshooting

Symptom	Likely cause	Fix
no matching manifest for linux/arm64	The tag does not publish an ARM64 variant.	Inspect the image platforms and choose a tag/browser supported on ARM64, or run it on AMD64.
Browser fails to launch on ARM64	The browser is unavailable for that architecture/version, or an AMD64 image is being emulated.	Verify the current Selenium browser matrix for the exact tag and select a native supported browser image.
Chrome is missing on ARM64	The selected tag predates ARM64 Chrome availability or does not configure it.	Check the README’s Chrome platform setting and use a supported v150+ configuration, or choose Chromium/Firefox.
Remote client cannot connect	Port 4444 is not published, the container is not ready, or the client uses the wrong host.	Check docker ps and container logs, publish -p 4444:4444, wait for Grid readiness, and use the reachable host address.
Hub Node does not register	Node cannot resolve/reach the Hub or has a mismatched event bus host or release.	Put both on the same Docker network, set SE_EVENT_BUS_HOST to the Hub name, and align version tags.
Browser crashes or tabs exit under load	Insufficient container shared memory or host resources.	Set the documented --shm-size="2g" and reduce concurrent sessions or provision more resources.
Unexpected browser or Grid behavior after an update	A floating tag resolved to a newer image.	Pin a full version tag, then upgrade intentionally after checking platform and browser support.

9. Or skip the browser setup

If the task is to capture a website screenshot rather than exercise browser interactions, ScreenshotNeo provides a one-request screenshot API and an MCP server. It accepts a URL and returns PNG, JPEG, WebP, or PDF. See the API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', new Uint8Array(await res.arrayBuffer()));

Cookie banners are accepted and removed before capture, along with supported newsletter popups and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. AI agents can use the MCP server’s take_screenshot, get_page_info, and capture_pdf tools. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

10. Frequently asked questions

Do I need separate Selenium image names for Apple Silicon and Intel?

Not necessarily. A multi-platform tag can let Docker select the host variant automatically. Confirm the exact tag includes your requested browser for that architecture.

Does ARM64 support mean every browser works on ARM64?

No. Selenium’s browser and platform matrix varies by browser and version. Firefox and Chromium are listed on both architectures; Edge and Chrome for Testing are AMD64-only in the current README, and Chrome on ARM64 requires the newer supported configuration.

Can I use Selenium Grid and ScreenshotNeo for the same project?

Yes. Selenium is suited to interactive browser automation and WebDriver tests; a screenshot API can handle URL-to-image capture tasks without maintaining browser containers.

Sources

• SeleniumHQ docker-selenium README (image matrix, tags, ports, Grid and shared-memory examples)
• Docker multi-platform builds (manifest lists and platform selection)