Selenium (Python) "WebDriverException: driver not found" / browser missing in CI

Selenium couldn’t start a browser session because the driver (chromedriver/geckodriver) or the browser itself isn’t available. Modern Selenium can auto-provision the driver, but it still needs a real browser installed on the runner.

What this error means

A Selenium test fails at webdriver.Chrome() with WebDriverException - either the driver "needs to be in PATH", a version mismatch between driver and browser, or the browser binary can’t be located. It passes locally where Chrome and chromedriver are installed.

Python traceback

selenium.common.exceptions.WebDriverException: Message: 'chromedriver'
executable needs to be in PATH.
# or version skew
session not created: This version of ChromeDriver only supports Chrome version 124

Common causes

Driver not on PATH (older Selenium)

Selenium <4.6 needs chromedriver/geckodriver on PATH. If it isn’t installed, the session can’t start.

Browser missing or version-mismatched

Selenium Manager (4.6+) downloads a matching driver automatically, but only if a browser is installed. No Chrome/Firefox on the runner, or a driver pinned to a different browser version, still fails.

How to fix it

Let Selenium Manager handle the driver

On Selenium 4.6+ you don’t manage the driver yourself - just install a browser and Selenium fetches a matching driver.

Terminal

pip install --upgrade selenium   # 4.6+ includes Selenium Manager
# Debian/Ubuntu: install a browser
apt-get update && apt-get install -y chromium chromium-driver

Run headless in CI

Python

from selenium import webdriver
opts = webdriver.ChromeOptions()
opts.add_argument("--headless=new")
opts.add_argument("--no-sandbox")
driver = webdriver.Chrome(options=opts)

How to prevent it

Use Selenium 4.6+ and let Selenium Manager resolve the driver.
Install a real browser in the runner image and run headless.
If pinning the driver, keep its version in lockstep with the browser.