Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →If Selenium reports that it cannot locate chromedriver or another browser driver in an Alpine Docker container, first check that the driver is installed and discoverable inside the final container. For Chromium on Alpine, install chromium and chromium-chromedriver from the same Alpine release and architecture, verify their paths and versions, then either let Selenium Manager locate the driver or pass its absolute path through Selenium’s browser-specific Service object. If Selenium finds the driver but it exits or cannot start the browser, investigate startup compatibility rather than treating it as a path problem.
First identify whether this is a detection error
Selenium uses a browser-specific driver executable to send commands to a browser. For Chrome or Chromium, that driver is chromedriver; Firefox uses geckodriver. Selenium’s driver troubleshooting guide gives examples such as “Unable to locate the chromedriver executable” and “The file geckodriver does not exist.” Those messages point to driver discovery: Selenium cannot find the executable at a path it knows about.
A different failure occurs when Selenium starts the driver process but the process exits, or the driver cannot launch the browser. In that case, the driver may already be found. Check the full exception and driver logs before changing paths; a missing executable and a browser startup failure need different fixes.
Verify the driver from inside the final container
Run these commands in the same image and user context that runs your tests, not just on the Docker host or in a temporary build stage:
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitches#1 Best Overall
command -v chromium
command -v chromedriver
chromium --version
chromedriver --version- If
command -v chromedriverprints nothing, inspect the package installation and the container’sPATH. - If it prints a path but
chromedriver --versionfails, the file may not be executable, may be for a different architecture, or may be missing runtime libraries. - If both version commands succeed, record the paths and versions. Then check that Selenium uses this driver and the intended browser binary.
The final-image check matters because the application runs in the container that starts the test. A package installed only on the host, or in a Docker build stage that is not carried into the final image, is unavailable to Selenium at runtime.
Install Chromium and its driver from the same Alpine release
For an Alpine image using Alpine’s Chromium packages, install chromium and chromium-chromedriver together. The Alpine package metadata identifies chromium-chromedriver as the Chromium WebDriver package, provides the chromedriver command, and lists Chromium as a dependency. Use packages from the same Alpine branch and target architecture so the distribution’s package metadata can manage their relationship.
RUN apk add --no-cache chromium chromium-chromedriverThis is a package-name example, not a promise that every Alpine release and architecture has the same packages or versions. Check the package index for your image’s actual release and platform: the Alpine v3.23 community x86_64 package page and Alpine v3.22 Chromium package page describe different branch-specific metadata. Do not mix a Chromium package from one branch with a driver package from another just because both package names exist.
After building the image, repeat the four verification commands in the running final image. Confirm that the paths and versions are present there; do not assume the paths shown in an example match every Alpine image.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Choose how Selenium should locate the driver
Option 1: Selenium Manager
Selenium Manager is included with Selenium releases as of version 4.6 and is used as a fallback when you have not provided a driver. The Selenium Project’s guide says, “As of Selenium 4.6, Selenium downloads the correct driver for you.” That describes the general behavior, not guaranteed success in every Alpine image. The container still needs a usable browser and an environment in which Manager can perform any required driver management.
If you are on an older Selenium release, upgrade the binding before relying on Selenium Manager. When it does not resolve the driver, enable Selenium Manager logging and inspect whether it can detect or download the required driver under the container’s network and filesystem conditions. The Selenium Client Driver API documentation provides the client API reference.
Option 2: Put the driver on PATH
If the driver is installed in a directory already on PATH, Selenium can discover it through the environment. Verify the actual runtime environment with command -v chromedriver; do not infer PATH from a Dockerfile line or from an interactive shell on the host. If your container starts with a restricted PATH or a different user, correct that runtime configuration or use an explicit path instead.
Option 3: Set an explicit Service path
Selenium supports specifying a driver executable with the browser-specific Service object. In Python, the following example uses paths that must be checked in your image:
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
options = webdriver.ChromeOptions()
options.binary_location = "/usr/bin/chromium" # Use only if this is the actual path in your image.
service = Service(executable_path="/usr/bin/chromedriver")
driver = webdriver.Chrome(service=service, options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()Replace the example paths with the output of command -v chromium and command -v chromedriver. Set binary_location only when Selenium needs help finding the browser binary. For another language binding or browser, use that binding’s corresponding browser-specific Service class and the paths that exist in that container. Selenium documents explicit Service configuration as an alternative to environment-variable discovery in its driver guide.
When the driver is found but the browser will not start
A successful command -v proves only that a path resolves; it does not prove the driver can launch the browser. If the exception says the driver process exited, or the browser never starts, check these separately:
- Browser installation and binary path: confirm the browser is installed in the final image and that any configured binary path points to it.
- Browser-driver compatibility: inspect both version commands and use a compatible browser and driver pair. Installing them from the same Alpine branch helps keep the package relationship coherent.
- Executable permissions and runtime libraries: confirm the driver can execute in the image and has the shared libraries it needs.
- CPU architecture: ensure the browser and driver binaries match the container’s target architecture. A binary for another architecture will not run as expected.
- Logs: capture the complete Selenium exception and driver output. A startup or process error provides different evidence from a “not found” message.
The SeleniumHQ docker-selenium project documents browser and driver availability across architectures and discourages AMD64 emulation on ARM64 for performance and stability. If assembling and maintaining a custom Alpine browser stack is repeatedly producing environment mismatches, consider a maintained Selenium image instead. Choose a fully tagged image so the Selenium/Grid and browser version are explicit, and confirm that the selected tag supports your target architecture.
Pick the approach that fits your container
| Approach | Best fit | Checks to make |
|---|---|---|
| Selenium Manager | A current Selenium binding and supported browser, with network and cache conditions that permit driver management. | Selenium 4.6 or newer; Manager logs; browser availability; container access to required downloads. |
| Alpine repository packages | A custom Alpine image using Alpine Chromium. | Same Alpine branch and architecture; package availability; PATH; executable versions; browser-driver pair. |
| Explicit Service path | The driver is installed, but discovery does not select it. | Absolute path verified inside the final container; correct browser-specific Service class. |
| Official Selenium Docker image | You prefer maintained browser/Grid images to assembling the operating-system, browser, and driver stack yourself. | Full image tag and support for the target CPU architecture. |
Common errors and fixes
“Unable to locate the chromedriver executable”
Selenium cannot find the driver. Check command -v chromedriver in the final container. Install the driver package if it is absent, fix PATH if it is present but not discoverable, or pass the verified absolute path to the Chrome Service object.
“The file geckodriver does not exist”
This is the analogous discovery problem for Firefox. Verify that the Firefox driver is installed in the image and use the Firefox binding’s Service object with the actual driver path. Do not substitute Chromium package instructions for a Firefox container.
The driver command exists but cannot execute
Check the output of chromedriver --version, executable permissions, required runtime libraries, and CPU architecture. A resolved path alone does not show that the binary can run in the image.
The driver starts and then exits, or the browser fails to launch
Stop changing PATH until you have checked browser installation, browser binary location, driver/browser compatibility, runtime libraries, permissions, and architecture. Save the full Selenium exception and driver logs to identify which startup step fails.
Selenium Manager does not resolve the driver
Confirm the binding is version 4.6 or newer, enable Manager logging, and check the container’s ability to access whatever downloads and filesystem locations driver management requires. If the environment cannot support that route, install the driver package and use PATH or an explicit Service path.
The build succeeds but tests still cannot find the executable
Run the verification commands in the final image, using the same user and startup environment as the test process. Check that the package-install step is part of the final stage and that the runtime PATH is not different from the build shell’s PATH.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your task is to capture a website screenshot rather than automate browser interactions, ScreenshotNeo provides a website screenshot API and MCP server. A GET request returns an image or PDF; it avoids installing and maintaining a browser and driver in your own container. The API accepts parameters used by other screenshot APIs, which can make switching straightforward. See the ScreenshotNeo API documentation for the available options.
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://example.com
-o shot.webpScreenshotNeo accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses report the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents using Claude, Cursor, or another MCP client. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up free for 1,000 screenshots a month, with no card required.
What to include if the error persists
The correct fix depends on the Selenium language and version, browser, Alpine release, target architecture, Dockerfile stages, full exception, and whether the test runs the browser locally or connects to a remote Grid. If the checks above do not isolate the failure, collect those details along with the command outputs and driver logs; they distinguish a missing executable from a binary, compatibility, or startup problem.
Frequently Asked Questions
Does Selenium require a separate driver executable?
Yes. Selenium uses a browser-specific driver to communicate with the selected browser, unless a remote WebDriver service provides that browser session.
Does the Alpine package named chromium-chromedriver install Chromium too?
The Alpine package metadata lists Chromium as a dependency of chromium-chromedriver; check the package index for your release and architecture.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
