Selenium has become one of the most popular browser automation and testing frameworks over the past decade. However, as a Java library, Selenium cannot directly control the browser itself. It needs a browser-specific driver executable to bridge that gap. For Google Chrome, the required driver is called chromedriver. Failing to set up chromedriver properly is a common stumbling block for anyone new to Selenium.
In this guide, we'll cover everything you need to know to fix the infamous “chromedriver executable needs to be in PATH” error, and seamlessly integrate chromedriver with your Selenium scripts.
Why Selenium Needs Chromedriver
Selenium is designed to support multiple browsers through a simple, unified API. Under the hood, it sends JSON commands to a browser-specific driver, which translates them into native browser instructions. This allows you to write tests and scripts once, and run them across different browsers by just changing the driver.
For Chrome, the required driver is chromedriver. Without it installed and configured properly, Selenium will be unable to launch or control Chrome:
selenium.common.exceptions.WebDriverException: Message: 'chromedriver' executable needs to be in PATH.
What is the PATH variable?
When you run a command like
chromedriver on the command line, your operating system searches a list of directories to find the executable. This list is stored in an environment variable called
PATH. So when Selenium tries to launch chromedriver and gets a “not in PATH” error, it simply means your OS can't find the chromedriver executable.
There are two ways to fix this:
- Add the chromedriver location to your system's PATH
- Specify the chromedriver path directly in your Selenium code
Adding Chromedriver to PATH
This is the recommended approach, as it means you don't have to hardcode the path in every script. Here's how to add chromedriver to PATH on different operating systems:
- Locate where chromedriver.exe is installed on your system. For example C:\Selenium\chromedriver.exe
- Press Windows + R to open the “Run” dialog
- Type in
systempropertiesadvancedand hit Enter
- In the Advanced tab, click “Environment Variables”
- Under “System Variables” find the PATH variable and click Edit
- Click New and add the chromedriver folder path on a new line
7. Click OK to close all windows
8. Open a new command prompt and verify chromedriver is now in PATH by running:
- Locate chromedriver inside the filesystem. For example /usr/local/bin/chromedriver
- Edit your shell profile script and export the chromedriver path:
For Bash, this is ~/.bash_profile or ~/.profile
For ZSH, this is ~/.zshrc
3. Reload the shell or open a new terminal
chromedriver --version to verify it's in PATH
Now Selenium will be able to find and launch chromedriver automatically.
Specifying Chromedriver Path in Code
The alternative is to pass the chromedriver path directly when creating the Selenium webdriver instance:
from selenium import webdriver driver = webdriver.Chrome(executable_path="C:/Selenium/chromedriver.exe")
This is useful for one-off scripts. But for larger projects, managing the PATH variable centrally is cleaner. The path can be relative or absolute. On Linux/MacOS, don't forget to prepend “./” for a relative path.
driver = webdriver.Chrome(executable_path="./chromedriver")
Finding the Chromedriver Binary
If you installed chromedriver through a package manager like NPM or Homebrew, you'll need to locate where it ended up on your filesystem before adding it to PATH. Here are some common default locations to check:
- C:\Program Files (x86)\chromedriver.exe
You can also search for
chromedriver.exe from your file explorer. Once you find it, use the steps above to add that specific path to the PATH variable.
Matching Chromedriver and Browser Versions
Chrome updates very frequently, sometimes even multiple times per month. Chromedriver needs to be the right version to control a given release of Chrome. If the versions are incompatible, you'll see errors like:
unknown error: DevToolsActivePort file doesn't exist
When installing chromedriver:
- For stable Chrome, download the LATEST chromedriver release
- For Chrome beta or canary, download the SAME MAJOR version as Chrome
You can lookup the Chrome version from
chrome://version/ in the browser. Ideally, automate installing the Chrome driver version using a Selenium setup script. The
webdriver_manager Python package is a popular choice.
Troubleshooting Chromedriver Issues
Here are some other common chromedriver-related issues and how to fix them:
- SessionNotCreatedException: Message: session not created: This means chromedriver crashed on startup. Try upgrading chromedriver to match your Chrome version.
- WebDriverException: unknown error: cannot find Chrome binary: Selenium can't locate the Chrome browser installation. Add the Chrome binary location to PATH, or specify the path in Selenium code via
- Timeout errors when running scripts: Check that Chrome and chromedriver are upto-date. Restart the Selenium server and make sure you don't have multiple old sessions running.
- Chrome is being controlled by automated test software: Chrome has detected Selenium automation. You may need to addowebsite annimize detection by passing special arguments.
For detailed troubleshooting tips, see the ChromeDriver Selenium wiki page.
Automating Chromedriver in CI/CD Pipelines
For automating browser tests on servers like GitHub Actions, install and run the required Chrome and chromedriver versions in your workflow:
steps: - uses: nanasess/setup-chromedriver@master with: chromedriver-version: '101.0.4951' - run: | python -m pip install selenium python tests.py
nanasess/setup-chromedriver action downloads and configures the specified chromedriver version.
Chromedriver is required for controlling Chrome with Selenium, but can be tricky to set up initially. By adding it to your system PATH or specifying the path in code, you can avoid the infamous “chromedriver executable needs to be in PATH” error. Properly configuring chromedriver and keeping it synchronized with your Chrome version will save you hours of debugging frustrating browser automation issues down the road.