How to Fix Selenium "cannot find Chrome binary"

TL;DR

Locate Chrome on the machine or container that runs ChromeDriver. Install it if absent, or set ChromeOptions.binary_location to its executable; then run a minimal WebDriver session to confirm startup.

Key Takeaways

• Confirm Chrome exists where ChromeDriver runs, not just on the host machine.
• Use ChromeOptions.binary_location for a custom browser executable path.
• Separate the Chrome browser path from the ChromeDriver service path.
• Install Chrome in the CI job or use a Selenium browser container.
• Use Selenium Manager only when downloads or a prepared cache are available.
• Verify the repair with a real WebDriver session against a data URL.

To fix Selenium cannot find Chrome binary, first check whether the error appears as a Chrome session starts, before your test reaches a page. ChromeDriver needs an actual Chrome or Chromium executable on the machine that launches the browser; a ChromeDriver executable alone is insufficient.

selenium.common.exceptions.WebDriverException: Message: unknown error: cannot find Chrome binary

The exact exception wrapper varies by language and Selenium setup, but the useful diagnostic is unknown error: cannot find Chrome binary. Work from the machine or container that runs ChromeDriver. A laptop's Chrome installation does not help a remote CI runner or Selenium Grid node.

TL;DR

Check for a browser executable, then run a minimal session. On macOS or Linux, command -v google-chrome || command -v chromium || command -v chromium-browser finds common command names. On Windows, use where.exe chrome and inspect the installed application's path if that command returns nothing. If the browser is absent, install it or let a current Selenium installation manage Chrome for Testing where downloads are permitted. If it exists in a custom location, set Selenium's Chrome binary_location to the absolute executable path. In Docker, either install Chrome inside the test container or use a Selenium standalone Chrome container through webdriver.Remote.

Do not confuse this message with ChromeDriver version mismatch or Chrome not reachable. Those failures happen at different stages of session startup.

What the Error Actually Means

Selenium's client sends a new-session request to ChromeDriver. ChromeDriver then launches Chrome. The message indicates that this launch process could not find the browser executable it was told to use, or could not find one through its normal discovery locations. Your test selectors, page URL, waits, and assertions have not yet run. Changing a CSS selector cannot repair this failure.

Three components matter: the Selenium language binding, ChromeDriver, and the Chrome or Chromium browser. Selenium Manager can discover and provision compatible browser and driver binaries in supported setups, but an explicitly configured driver, offline policy, stale cache, or inaccessible download can alter that path. Service(executable_path=...) in Python points to ChromeDriver, while options.binary_location points to Chrome. In Java, ChromeOptions.setBinary(...) performs the browser-side configuration. Google's ChromeOptions documentation calls the capability binary and requires the executable, not merely the containing directory.

On macOS, the executable is inside the .app bundle, for example /Applications/Google Chrome.app/Contents/MacOS/Google Chrome. On Windows it is chrome.exe inside the installed application's directory. On Linux it might be google-chrome, google-chrome-stable, or chromium, depending on the installation. Treat these as candidates to inspect, not paths to copy without checking.

Root-Cause Decision Table

The table identifies the first check, not a license to try every fix at once. Follow the matching numbered section and run its verification command before changing another variable.

1. Fix Selenium Cannot Find Chrome Binary When Chrome Is Missing

Start with the environment that executes the test. On Linux or macOS, run the following. An empty result means none of these command names is on PATH; it does not prove every possible custom installation is absent.

command -v google-chrome || command -v google-chrome-stable || command -v chromium || command -v chromium-browser

On Windows PowerShell, inspect common command discovery and the standard application locations. where.exe can be empty even when Chrome is installed through an application installer, so test the executable you actually find in File Explorer.

where.exe chrome
Test-Path 'C:\Program Files\Google\Chrome\Application\chrome.exe'
Test-Path "$env:LOCALAPPDATA\Google\Chrome\Application\chrome.exe"

If no browser exists, install Chrome or Chromium using your organization's approved package source. A current Selenium binding can also manage Chrome for Testing automatically when the runner has network access and policy permits downloads. Selenium documents this in Selenium Manager. The command below updates the binding in the active Python environment; do not run it in a different virtual environment from the test.

python -m pip install --upgrade selenium
python -c "import selenium; print(selenium.__version__)"

Create smoke.py as the smallest reproducible session. It uses a data URL, so page navigation needs no internet access. Browser or driver acquisition may still need internet access on a first run. The finally block releases the session even if the assertion fails.

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

options = Options()
options.add_argument("--headless")
driver = webdriver.Chrome(options=options)
try:
    driver.get("data:text/html,<title>Chrome ready</title><h1>ok</h1>")
    assert driver.title == "Chrome ready"
    print(driver.capabilities["browserVersion"])
finally:
    driver.quit()

Verify this root cause with python smoke.py. A printed browser version and exit code zero prove that a browser was found and a session started. If the command still reports the same binary error, inspect the next sections. If it instead reports a version mismatch, use the dedicated ChromeDriver compatibility guide; the new error is valuable evidence that discovery is now working.

2. Fix Selenium Cannot Find Chrome Binary With a Custom Install Path

A portable browser archive, enterprise installation, or Chrome for Testing download often lives outside ChromeDriver's default discovery paths. Locate the executable file, not the download directory, .app directory, or ChromeDriver program. On macOS, use the executable inside the app bundle. On Linux, resolve symlinks with readlink -f if you need to audit the final file. On Windows, open the installed application's directory and confirm chrome.exe exists.

Keep the path in CHROME_BINARY so developers and CI can use different installations without editing the test. Replace the smoke script from section 1 with this complete version. Path.is_file() catches typos before ChromeDriver receives them; it does not claim the binary can launch successfully.

import os
from pathlib import Path
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

options = Options()
options.add_argument("--headless")
configured = os.environ.get("CHROME_BINARY")
if configured:
    browser = Path(configured).expanduser().resolve()
    if not browser.is_file():
        raise FileNotFoundError(f"Chrome executable not found: {browser}")
    options.binary_location = str(browser)

driver = webdriver.Chrome(options=options)
try:
    driver.get("data:text/html,<title>Chrome ready</title>")
    assert driver.title == "Chrome ready"
    print(driver.capabilities["browserVersion"])
finally:
    driver.quit()

For a Linux installation discoverable as chromium, verify with CHROME_BINARY="$(command -v chromium)" python smoke.py. For macOS, run CHROME_BINARY='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' python smoke.py only after confirming that file exists. In PowerShell, set $env:CHROME_BINARY to the actual chrome.exe path and run python .\smoke.py; do not paste a Linux path into Windows configuration.

If your suite is Java based, the equivalent browser option is ChromeOptions options = new ChromeOptions(); options.setBinary(browserPath); new ChromeDriver(options);. This is distinct from setting the driver executable with ChromeDriverService. For a broader setup walkthrough, see Selenium with Java or Selenium with Python.

3. Correct an Invalid, Stale, or Inaccessible Browser Path

An explicit binary_location overrides discovery. A path copied from another operating system, an old Chrome for Testing extraction, or a directory instead of an executable can create the very failure it was intended to cure. Read the final CHROME_BINARY value in the same shell or job that runs the suite. Look for trailing quotes, shell expansion that did not occur, and environment variables inherited from another job.

Run this preflight before starting WebDriver. It prints an unambiguous path and exits nonzero if the file is absent. On Unix systems, it additionally checks execute permission; Windows uses its own executable rules, so the permission test is skipped there.

import os
from pathlib import Path

raw = os.environ.get("CHROME_BINARY")
if not raw:
    raise SystemExit("CHROME_BINARY is not set")
path = Path(raw).expanduser().resolve()
print(f"Browser path: {path}")
if not path.is_file():
    raise SystemExit("Browser path is not a file")
if os.name != "nt" and not os.access(path, os.X_OK):
    raise SystemExit("Browser file is not executable")

Save that as check_browser.py, then run python check_browser.py && python smoke.py in the same environment. If a path is stale, correct CHROME_BINARY to the file you found or remove the override to restore discovery. On POSIX shells, env -u CHROME_BINARY python smoke.py tests the latter without altering your shell permanently. In PowerShell, run Remove-Item Env:CHROME_BINARY and then python .\smoke.py.

On Linux, an executable can exist yet fail to start because a shared library is missing. That produces a different launch error after the path check, not proof that binary discovery is still broken. Run ldd /absolute/path/to/chrome on the selected Linux executable to inspect missing dependencies. On macOS, an app bundle path ending at .app fails the file check because it is a directory; append /Contents/MacOS/Google Chrome for the standard Chrome app.

4. Remove Forced Driver Configuration That Bypasses the Expected Setup

Older projects sometimes install ChromeDriver manually and pass its location into Service(...). That is legitimate when infrastructure deliberately pins a driver, but it does not install Chrome. It can also hide a change in the local browser installation or prevent the setup you expected from being chosen. Search the test configuration for executable_path, ChromeDriverManager, webdriver.chrome.driver, binary_location, and SE_BROWSER_PATH. Check which of those values are still required.

For a Python project using modern Selenium management, simplify the startup to the webdriver.Chrome(options=options) pattern in smoke.py. Avoid a manually downloaded driver unless a policy requires one. Confirm the active interpreter and Selenium binding before attributing behavior to a package you installed in another environment.

python -c "import sys, selenium; print(sys.executable); print(selenium.__version__)"
command -v chromedriver || true
command -v google-chrome || command -v chromium || true

The verification command is python smoke.py. If it starts a session, print driver.capabilities["browserVersion"] as the script does and inspect driver.service.path in a local Python session if you need to identify the selected ChromeDriver. If the error changes to session not created: This version of ChromeDriver only supports Chrome version ..., you have reached a separate driver/browser compatibility problem; match the installed browser and driver through Selenium Manager or your approved package pair.

Selenium Manager's SE_BROWSER_PATH is an absolute browser path for version detection. It is not a substitute for a missing executable. Prefer the ChromeOptions browser path for a specific session, especially when tests select among multiple Chromium builds. The official Selenium Manager configuration documents its environment variables; set one only when you know which process reads it.

5. Install Chrome in the CI Job That Runs Selenium

Hosted and self-hosted runners differ from developer laptops. A browser may be present on a personal machine but absent from a fresh job image, or a preinstalled path may move when the image is updated. Put browser setup and the smoke check in the same job as the test. On GitHub Actions, the maintained browser-actions/setup-chrome action exposes the installed executable as chrome-path. Use that output rather than guessing where the action placed Chrome for Testing.

name: selenium-smoke
on: [push]
jobs:
  chrome:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - uses: browser-actions/setup-chrome@v2
        id: chrome
      - run: python -m pip install --upgrade selenium
      - run: python smoke.py
        env:
          CHROME_BINARY: ${{ steps.chrome.outputs.chrome-path }}

Save this example under .github/workflows/selenium-smoke.yml in your own project alongside the section 2 smoke.py. The setup action's documented chrome-path output is passed to the Python process, where binary_location selects it. These action tags are real published major tags; if your organization pins actions by commit, substitute the approved commits. Do not pin an invented Chrome version: use the installed stable channel or match the browser release your test matrix requires.

Verify by opening the job log and finding the printed browser version from python smoke.py. If the setup step succeeds but the test cannot find Chrome, log the CHROME_BINARY value and run python check_browser.py from section 3 in the test step. If a later error says Chrome crashed, inspect headless mode, shared memory, and system libraries; that is a launch failure after discovery. The test automation CI/CD guide covers keeping these setup checks close to the tests.

6. Run Chrome Inside Docker or Connect to a Browser Container

A Docker container has its own filesystem. Mounting test code into a Python image does not bring the host's Chrome installation with it. Run docker exec <test-container> sh -lc 'command -v google-chrome || command -v chromium' against the actual test container. If nothing prints, choose one of two architectures: build a test image that contains Chrome, or send WebDriver requests to a Selenium container that already contains a browser. Do not set binary_location to a host path inside a container; that path must exist where ChromeDriver runs.

The following standalone Chrome example avoids browser installation in the Python process. Set SELENIUM_IMAGE_TAG to a published tag that matches your approved Selenium image, for example <your-selenium-image-tag> in your deployment configuration. The --shm-size setting gives Chrome room for shared memory. On ARM machines, check image architecture first; Selenium's Chromium image may be the appropriate published alternative.

: "${SELENIUM_IMAGE_TAG:?Set SELENIUM_IMAGE_TAG to your published Selenium image tag}"
docker run -d --rm --name qa-chrome -p 4444:4444 --shm-size=2g "selenium/standalone-chrome:${SELENIUM_IMAGE_TAG}"
curl -fsS http://localhost:4444/status

Save this independent remote smoke as remote_smoke.py. The session uses the browser inside qa-chrome; it does not inspect the test process for Chrome. If your test process is another container on the same Docker network, replace localhost with the browser service name in SELENIUM_URL.

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

options = Options()
options.add_argument("--headless")
url = os.environ.get("SELENIUM_URL", "http://localhost:4444")
driver = webdriver.Remote(command_executor=url, options=options)
try:
    driver.get("data:text/html,<title>Remote Chrome ready</title>")
    assert driver.title == "Remote Chrome ready"
    print(driver.capabilities["browserVersion"])
finally:
    driver.quit()

Verify with python remote_smoke.py. A browser version proves the remote node launched Chrome. curl success only proves Grid is listening, not that a browser session is usable. If the test runs in a second container, localhost refers to that second container, so use a Docker network and http://qa-chrome:4444. For details on node images and networking, see Docker for Selenium Grid and the official docker-selenium repository.

7. Handle Offline Networks and Empty Selenium Manager Caches

Selenium Manager can acquire a missing browser, but first use on a clean machine requires access to its download sources unless your infrastructure has already cached the required artifacts. A proxy, blocked egress, or an explicitly offline setting can stop that process. Read the complete exception chain: a download or proxy error before the ChromeDriver message is evidence of provisioning failure. Check the Selenium cache under the account running tests, commonly ~/.cache/selenium on Unix-like systems, but do not assume a developer's cache is mounted into CI.

In a locked-down runner, supply an organization-approved browser and driver pair as part of the image. Set CHROME_BINARY to the installed browser executable and use the section 2 script. The preflight should run as the same user as the tests, because permissions and mounted paths can differ. Keep browser and driver versions aligned; a browser version check alone cannot certify the pair.

python check_browser.py
"$CHROME_BINARY" --version
python smoke.py

That verification sequence establishes file presence, executable launch, and a real WebDriver session in order. On Windows PowerShell, invoke & $env:CHROME_BINARY --version between python .\check_browser.py and python .\smoke.py. If the browser version command fails because system libraries are unavailable, repair the image before touching Selenium code. If it succeeds but the session fails with a driver mismatch, use your approved driver matching process.

If you choose to prepopulate Selenium Manager's cache instead of preinstalling Chrome, populate it during an image build or an online preparation job with the same architecture and runtime account as the offline runner. Document the cache path and invalidation policy. A cache copied from a different operating system will not provide a runnable executable. Selenium Manager's official browser management guide explains its download and cache behavior.

How to Verify the Fix

A successful command -v or Test-Path result is only the first gate. Verify four things in order: the exact browser file exists in the test environment, it runs with --version, WebDriver creates a Chrome session, and the session can load a simple document. The smoke.py scripts above cover the final two checks without depending on your application, credentials, or external pages. Keep this smoke separate from the full suite so failures stay easy to classify.

On Linux or macOS, the following commands show the two local gates when CHROME_BINARY is configured. The final command uses the script from section 2. For default discovery, omit the variable and run python smoke.py directly.

python check_browser.py
"$CHROME_BINARY" --version
python smoke.py

Expected success is an executable version string, a printed browserVersion, and a zero exit code. For a remote Grid, use curl -fsS http://localhost:4444/status followed by python remote_smoke.py; the second command is the decisive check. In an application test, add a page assertion after this infrastructure smoke passes. A missing binary happens before browser navigation, so a later HTTP or selector failure should be investigated on its own terms.

If you need an interactive browser to confirm UI behavior after startup, use the Selenium headed-mode guide. The --headless argument changes display behavior but cannot manufacture a missing browser executable. Capture the full exception, selected browser path, python interpreter, OS, architecture, and container image tag when escalating a persistent failure; those details let another engineer reproduce the environment rather than guess from one error line.

Prevent It From Coming Back

Treat the browser as a test dependency. Keep one explicit owner for provisioning it: a managed CI action, a built image, Selenium Manager, or an approved local install. Declare the chosen path in the repository's test setup documentation and validate it in a preflight. When your team updates a runner image or a Chrome for Testing archive, run the browser smoke before the full regression suite. That catches a path change in seconds and avoids obscuring it with unrelated test failures.

Use binary_location only when you truly have a nonstandard browser location. Centralize the value in configuration instead of copying absolute paths across test files. A Windows path committed into a cross-platform suite is almost guaranteed to fail on Linux CI. For portable code, read CHROME_BINARY when set and otherwise allow normal discovery, as section 2 does. Do not store a ChromeDriver path in a variable named CHROME_BINARY; keep the two roles visibly separate.

For Docker, pin a published image tag selected from your approved release, and update browser and driver together. A floating tag can change underneath a long-lived pipeline. In CI, print browser and driver details in the setup log, while avoiding secrets and personal filesystem paths. Retain the data-URL smoke as a fast infrastructure check. Only start diagnosing Selenium page failures after the browser session has started.

Interview Questions and Answers

Q: What does cannot find Chrome binary identify? It identifies a browser executable discovery failure during session creation. ChromeDriver could start yet still lack Chrome. Ask which machine runs ChromeDriver before inspecting the path.

Q: Why does installing ChromeDriver alone not fix it? ChromeDriver is the WebDriver server that controls a browser process. It is not the browser process itself, so the Chrome or Chromium executable must also be available to that server.

Q: Which Python option points to a custom Chrome executable? Set options.binary_location on selenium.webdriver.chrome.options.Options before calling webdriver.Chrome(options=options). Use an absolute path to the executable file.

Q: How is Java configured? Call ChromeOptions.setBinary(browserPath) and pass that options object to new ChromeDriver(options). Keep the browser path separate from any ChromeDriver service path.

Q: Why can the test pass locally and fail in Docker? The host and container have separate filesystems. Chrome installed on the host is unavailable in the container unless the container image includes it or WebDriver connects to a browser service.

Q: Does --headless solve a missing Chrome binary? No. It changes how an installed browser runs after ChromeDriver finds it. It can solve display-server issues, which are later launch failures with different evidence.

Q: When should Selenium Manager download a browser? A supported current Selenium binding can manage Chrome for Testing when browser management is enabled and download access or cache is available. Offline runners need a preinstalled browser or prepared cache.

Q: What is the strongest verification? Create a fresh WebDriver session and load a data URL. A version command checks only the executable; a real session checks discovery, driver startup, browser startup, and basic navigation together.

Common Mistakes

• Pointing binary_location at chromedriver instead of Chrome. The names are similar but the programs have different jobs.
• Passing a macOS .app directory or a Chrome for Testing extraction folder instead of the executable within it.
• Installing Chrome on the CI host while tests and ChromeDriver run inside a separate Docker container.
• Using localhost:4444 from a test container to reach a Selenium container; within that container, localhost is itself.
• Assuming --headless, --no-sandbox, or another Chrome flag installs a browser. Flags are passed only after a browser executable is found.
• Treating a new session not created version error as unchanged evidence. It indicates discovery progressed and compatibility is now the next issue.
• Copying a browser path from a coworker's machine without checking that the CI user can execute the same file.
• Letting an unpinned Docker latest tag drift in a production pipeline after the diagnostic session is complete.

Conclusion

Fix Selenium cannot find Chrome binary by locating or installing the browser in the environment where ChromeDriver runs, then pointing ChromeOptions to its executable only when discovery needs help. Use a small data-URL WebDriver session to prove the repair. Once that passes, move back to your real test suite and investigate any new error at its own stage of browser startup or page interaction.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• How to Fix "Cannot find module '@playwright/test'" in Playwright
• How to Fix "Cypress failed to start" and cypress verify Errors
• How to Fix "Playwright Test did not expect test() to be called here"
• How to Fix Appium "Could not find a connected Android device"
• How to Fix Appium WebDriverAgent Failed to Start on iOS
• How to Fix Cypress "cy.visit() failed trying to load"