Platform

Solutions

Resources

Platform

Solutions

Resources

Platform

Solutions

Resources

Blog

Selenium ChromeDriver Setup: Install, Configure & Run Chrome Tests

Rishabh Kumar

Published on

ChromeDriver Setup

Table of contents

Lorem ipsum

Lorem ipsum

Lorem ipsum

Lorem ipsum

Lorem ipsum

ChromeDriver is the program that lets Selenium control Google Chrome. With Selenium 4.6 or later, you usually don’t need to install it at all, because Selenium Manager finds or downloads the right version for you. You only need a manual set-up for locked-down networks, pinned versions or older Selenium projects.

Chrome is the most widely used browser in the world, so for most teams, Chrome is the first browser they automate. And for years, getting ChromeDriver working meant matching versions by hand, editing your PATH and fixing everything again every time Chrome updated itself overnight.

That’s mostly behind us now, but not completely. This guide covers the easy way first, then manual installation on Windows, macOS and Linux, set-up in Java and Python, headless mode and profiles, the errors you’ll actually hit, and what driver management costs once you’re running at scale.



What is ChromeDriver in Selenium?

ChromeDriver is a small standalone program that implements the W3C WebDriver standard for Google Chrome and other Chromium browsers. It sits between your Selenium test and Chrome, and turns WebDriver commands into real actions in the browser.

How ChromeDriver Works

When you run a Selenium test against Chrome, four things happen in turn. Your test sends a command to ChromeDriver, like “open this URL” or “click this button”. ChromeDriver translates it into instructions Chrome understands, using the Chrome DevTools Protocol. Chrome carries out the action. Then ChromeDriver sends the result back to your test, so it can check what happened.

Without ChromeDriver, Selenium has no way to control Chrome.

Selenium Chromedrive Bridge

Why ChromeDriver Matters

  • Chrome is where most of your users are. Automating Chrome is usually the first step in any web testing plan.

  • It’s part of a family. Firefox has GeckoDriver, Safari has SafariDriver and Edge has EdgeDriver, so the same Selenium test can run across browsers.

  • It follows a standard. ChromeDriver implements the W3C WebDriver standard, so the commands are the same across browsers.

  • It’s free and open source, maintained by the Chromium project alongside Chrome itself.

If Chrome is only your first browser, our guide to cross-browser testing explains which others to add, and why the same page can behave differently in each.



The Easy Way: Let Selenium Manager Handle It

Since Selenium 4.6, Selenium has included a tool called Selenium Manager. When you start a Chrome session without telling Selenium where ChromeDriver is, Selenium Manager checks your Chrome version, downloads the matching ChromeDriver if you don’t already have it, and caches it for next time.

If Chrome isn’t installed, it can download a Chrome for Testing browser too.

For most people, that means the whole set-up is this.

Java (Selenium 4.6+)

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

public class FirstTest {
    public static void main(String[] args) {
        WebDriver driver = new ChromeDriver();   // Selenium Manager finds or downloads ChromeDriver
        driver.get("https://www.example.com");
        System.out.println(driver.getTitle());
        driver.quit();
    }
}
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

public class FirstTest {
    public static void main(String[] args) {
        WebDriver driver = new ChromeDriver();   // Selenium Manager finds or downloads ChromeDriver
        driver.get("https://www.example.com");
        System.out.println(driver.getTitle());
        driver.quit();
    }
}
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

public class FirstTest {
    public static void main(String[] args) {
        WebDriver driver = new ChromeDriver();   // Selenium Manager finds or downloads ChromeDriver
        driver.get("https://www.example.com");
        System.out.println(driver.getTitle());
        driver.quit();
    }
}
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

public class FirstTest {
    public static void main(String[] args) {
        WebDriver driver = new ChromeDriver();   // Selenium Manager finds or downloads ChromeDriver
        driver.get("https://www.example.com");
        System.out.println(driver.getTitle());
        driver.quit();
    }
}

Python (Selenium 4.6+)

from selenium import webdriver

driver = webdriver.Chrome()   # Selenium Manager finds or downloads ChromeDriver
driver.get("https://www.example.com")
print(driver.title)
driver.quit()
from selenium import webdriver

driver = webdriver.Chrome()   # Selenium Manager finds or downloads ChromeDriver
driver.get("https://www.example.com")
print(driver.title)
driver.quit()
from selenium import webdriver

driver = webdriver.Chrome()   # Selenium Manager finds or downloads ChromeDriver
driver.get("https://www.example.com")
print(driver.title)
driver.quit()
from selenium import webdriver

driver = webdriver.Chrome()   # Selenium Manager finds or downloads ChromeDriver
driver.get("https://www.example.com")
print(driver.title)
driver.quit()

You can also ask Selenium Manager for a specific browser version, which is useful for keeping CI runs stable.

Java (Selenium 4.6+)

ChromeOptions options = new ChromeOptions();
options.setBrowserVersion("stable");   // or "beta", or a major version such as "142"

ChromeOptions options = new ChromeOptions();
options.setBrowserVersion("stable");   // or "beta", or a major version such as "142"

ChromeOptions options = new ChromeOptions();
options.setBrowserVersion("stable");   // or "beta", or a major version such as "142"

ChromeOptions options = new ChromeOptions();
options.setBrowserVersion("stable");   // or "beta", or a major version such as "142"

In my experience, if you’re starting a project today, this is the right default. Only reach for the manual methods below when you have a reason to.

When you still need a manual set-up:

  • Your build machines can’t reach the internet, so Selenium Manager can’t download anything.

  • Your security team needs every binary to come from an approved, internal source.

  • You’re stuck on Selenium 4.5 or older, and can’t upgrade yet.

  • You need very precise control over which driver version runs where.



Prerequisites Before Installing ChromeDriver Manually

Check Your Chrome Version

ChromeDriver’s major version must match your installed Chrome’s major version. A mismatch causes a SessionNotCreatedException, and your tests won’t start.

Method 1: Chrome Settings

  1. Open Google Chrome.

  2. Type chrome://settings/help into the address bar.

  3. Note the version number, for example 142.0.7444.59. The first number is the major version.

Method 2: Command Line

Windows (Command Prompt)

reg query "HKEY_CURRENT_USER\Software\Google\Chrome\BLBeacon"
reg query "HKEY_CURRENT_USER\Software\Google\Chrome\BLBeacon"
reg query "HKEY_CURRENT_USER\Software\Google\Chrome\BLBeacon"
reg query "HKEY_CURRENT_USER\Software\Google\Chrome\BLBeacon"

macOS (Terminal)

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --version
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --version
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --version
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --version

Linux (Terminal)

google-chrome --version
google-chrome --version
google-chrome --version
google-chrome --version

Watch out: Chrome updates itself in the background, and ships a new major version roughly every four weeks. A ChromeDriver that worked yesterday can stop working after an overnight update, which is exactly the problem Selenium Manager solves.

Required Tools

For Java projects, you’ll need JDK 11 or later (current Selenium 4 releases no longer support Java 8), Maven or Gradle, and the Selenium Java bindings from Maven Central.

For Python projects, you’ll need a currently supported Python 3 version (3.9 or later for recent Selenium releases), pip, and the selenium package.



Step-by-Step ChromeDriver Installation

For Chrome 115 and Later

From Chrome 115, Google moved ChromeDriver downloads to the Chrome for Testing (CfT) site, which publishes matching versions of Chrome and ChromeDriver together.

Step 1: Open the Chrome for Testing Dashboard

Go to https://googlechromelabs.github.io/chrome-for-testing/. It lists the current Stable, Beta, Dev and Canary versions, with download links for every platform.

Step 2: Find the Matching Version

Find the ChromeDriver version that matches your Chrome major version. If you’d rather script it, the same data is available as JSON.

Bash

# Download URL for the latest Stable ChromeDriver on 64-bit Linux
curl -s https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json \
  | jq -r '.channels.Stable.downloads.chromedriver[] | select(.platform=="linux64") | .url'
# Download URL for the latest Stable ChromeDriver on 64-bit Linux
curl -s https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json \
  | jq -r '.channels.Stable.downloads.chromedriver[] | select(.platform=="linux64") | .url'
# Download URL for the latest Stable ChromeDriver on 64-bit Linux
curl -s https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json \
  | jq -r '.channels.Stable.downloads.chromedriver[] | select(.platform=="linux64") | .url'
# Download URL for the latest Stable ChromeDriver on 64-bit Linux
curl -s https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json \
  | jq -r '.channels.Stable.downloads.chromedriver[] | select(.platform=="linux64") | .url'

You can also install a matching ChromeDriver with one command, if you have Node.js.

Bash

Step 3: Download the File for Your Platform

Download the ZIP for your operating system, such as win64, mac-arm64 for Apple silicon, mac-x64 for Intel Macs, or linux64.

For Chrome 114 and Earlier (Legacy)

Older ChromeDriver versions are still listed on the legacy page at https://chromedriver.chromium.org/downloads. Pick the version that matches your Chrome major version, for example ChromeDriver 114 for Chrome 114, and download the file for your platform. You should only need this for old, pinned environments.



Installation Instructions by Platform

Windows

Step 1: Extract ChromeDriver

Unzip the download and find chromedriver.exe inside the chromedriver-win64 folder.

Step 2: Choose Where to Put It

Option A, recommended. Add it to your system PATH. Create a folder such as C:\webdriver\ and move chromedriver.exe into it. Then open System Properties, go to Environment Variables, edit the Path variable, add C:\webdriver\ and click OK.

Option B. Keep it inside your project, and point to its exact path in your test code.

Step 3: Check It Works

Windows (Command Prompt)

chromedriver --version
chromedriver --version
chromedriver --version
chromedriver --version

You should see something like ChromeDriver 142.0.7444.59.

macOS

macOS (Terminal)

# Step 1: Extract (use chromedriver-mac-x64.zip on Intel Macs)
unzip chromedriver-mac-arm64.zip

# Step 2: Make it executable
chmod +x chromedriver-mac-arm64/chromedriver

# Step 3: Move it somewhere on your PATH
sudo mv chromedriver-mac-arm64/chromedriver /usr/local/bin/

# Step 4: Remove the quarantine flag so Gatekeeper doesn't block it
xattr -d com.apple.quarantine /usr/local/bin/chromedriver

# Step 5: Check it works
chromedriver --version
# Step 1: Extract (use chromedriver-mac-x64.zip on Intel Macs)
unzip chromedriver-mac-arm64.zip

# Step 2: Make it executable
chmod +x chromedriver-mac-arm64/chromedriver

# Step 3: Move it somewhere on your PATH
sudo mv chromedriver-mac-arm64/chromedriver /usr/local/bin/

# Step 4: Remove the quarantine flag so Gatekeeper doesn't block it
xattr -d com.apple.quarantine /usr/local/bin/chromedriver

# Step 5: Check it works
chromedriver --version
# Step 1: Extract (use chromedriver-mac-x64.zip on Intel Macs)
unzip chromedriver-mac-arm64.zip

# Step 2: Make it executable
chmod +x chromedriver-mac-arm64/chromedriver

# Step 3: Move it somewhere on your PATH
sudo mv chromedriver-mac-arm64/chromedriver /usr/local/bin/

# Step 4: Remove the quarantine flag so Gatekeeper doesn't block it
xattr -d com.apple.quarantine /usr/local/bin/chromedriver

# Step 5: Check it works
chromedriver --version
# Step 1: Extract (use chromedriver-mac-x64.zip on Intel Macs)
unzip chromedriver-mac-arm64.zip

# Step 2: Make it executable
chmod +x chromedriver-mac-arm64/chromedriver

# Step 3: Move it somewhere on your PATH
sudo mv chromedriver-mac-arm64/chromedriver /usr/local/bin/

# Step 4: Remove the quarantine flag so Gatekeeper doesn't block it
xattr -d com.apple.quarantine /usr/local/bin/chromedriver

# Step 5: Check it works
chromedriver --version

Step 4 matters. The first time you run a downloaded ChromeDriver, macOS Gatekeeper blocks it, because the file came from the internet. Removing the quarantine flag tells macOS you trust it.

Linux

Linux (Terminal)

# Step 1: Extract
unzip chromedriver-linux64.zip

# Step 2: Make it executable
chmod +x chromedriver-linux64/chromedriver

# Step 3: Move it somewhere on your PATH
sudo mv chromedriver-linux64/chromedriver /usr/local/bin/

# Step 4: Check it works
chromedriver --version
# Step 1: Extract
unzip chromedriver-linux64.zip

# Step 2: Make it executable
chmod +x chromedriver-linux64/chromedriver

# Step 3: Move it somewhere on your PATH
sudo mv chromedriver-linux64/chromedriver /usr/local/bin/

# Step 4: Check it works
chromedriver --version
# Step 1: Extract
unzip chromedriver-linux64.zip

# Step 2: Make it executable
chmod +x chromedriver-linux64/chromedriver

# Step 3: Move it somewhere on your PATH
sudo mv chromedriver-linux64/chromedriver /usr/local/bin/

# Step 4: Check it works
chromedriver --version
# Step 1: Extract
unzip chromedriver-linux64.zip

# Step 2: Make it executable
chmod +x chromedriver-linux64/chromedriver

# Step 3: Move it somewhere on your PATH
sudo mv chromedriver-linux64/chromedriver /usr/local/bin/

# Step 4: Check it works
chromedriver --version

Any folder on your PATH works, such as /usr/local/bin/ or /usr/bin/.



Configuring ChromeDriver in Selenium Projects

Java

Method 1: Selenium Manager (Recommended)

As shown above, just create a ChromeDriver with no driver path, and Selenium Manager does the rest.

Method 2: System Property

Use this when you’ve installed ChromeDriver yourself, and want Selenium to use that exact file.

Java

System.setProperty("webdriver.chrome.driver", "C:\\webdriver\\chromedriver.exe");   // or /usr/local/bin/chromedriver

WebDriver driver = new ChromeDriver();
driver.get("https://www.example.com");
driver.quit();
System.setProperty("webdriver.chrome.driver", "C:\\webdriver\\chromedriver.exe");   // or /usr/local/bin/chromedriver

WebDriver driver = new ChromeDriver();
driver.get("https://www.example.com");
driver.quit();
System.setProperty("webdriver.chrome.driver", "C:\\webdriver\\chromedriver.exe");   // or /usr/local/bin/chromedriver

WebDriver driver = new ChromeDriver();
driver.get("https://www.example.com");
driver.quit();
System.setProperty("webdriver.chrome.driver", "C:\\webdriver\\chromedriver.exe");   // or /usr/local/bin/chromedriver

WebDriver driver = new ChromeDriver();
driver.get("https://www.example.com");
driver.quit();

Method 3: WebDriverManager

WebDriverManager is an open-source library that downloads and sets up drivers for you. It was the go-to choice before Selenium Manager existed, and many existing projects still use it.

XML (Maven pom.xml)

<dependency>
    <groupId>io.github.bonigarcia</groupId>
    <artifactId>webdrivermanager</artifactId>
    <version>6.1.0</version>   <!-- check Maven Central for the latest version --

<dependency>
    <groupId>io.github.bonigarcia</groupId>
    <artifactId>webdrivermanager</artifactId>
    <version>6.1.0</version>   <!-- check Maven Central for the latest version --

<dependency>
    <groupId>io.github.bonigarcia</groupId>
    <artifactId>webdrivermanager</artifactId>
    <version>6.1.0</version>   <!-- check Maven Central for the latest version --

<dependency>
    <groupId>io.github.bonigarcia</groupId>
    <artifactId>webdrivermanager</artifactId>
    <version>6.1.0</version>   <!-- check Maven Central for the latest version --

Java

import io.github.bonigarcia.wdm.WebDriverManager;

WebDriverManager.chromedriver().setup();
WebDriver driver = new ChromeDriver();
import io.github.bonigarcia.wdm.WebDriverManager;

WebDriverManager.chromedriver().setup();
WebDriver driver = new ChromeDriver();
import io.github.bonigarcia.wdm.WebDriverManager;

WebDriverManager.chromedriver().setup();
WebDriver driver = new ChromeDriver();
import io.github.bonigarcia.wdm.WebDriverManager;

WebDriverManager.chromedriver().setup();
WebDriver driver = new ChromeDriver();

Method 4: ChromeDriverService

Use this when you need control over how the ChromeDriver process starts, such as a fixed port or a log file for debugging.

Java

import java.io.File;
import org.openqa.selenium.chrome.ChromeDriverService;
import org.openqa.selenium.chrome.ChromeOptions;

ChromeDriverService service = new ChromeDriverService.Builder()
    .usingDriverExecutable(new File("/usr/local/bin/chromedriver"))
    .usingPort(9515)
    .withLogFile(new File("chromedriver.log"))
    .build();

WebDriver driver = new ChromeDriver(service, new ChromeOptions());
import java.io.File;
import org.openqa.selenium.chrome.ChromeDriverService;
import org.openqa.selenium.chrome.ChromeOptions;

ChromeDriverService service = new ChromeDriverService.Builder()
    .usingDriverExecutable(new File("/usr/local/bin/chromedriver"))
    .usingPort(9515)
    .withLogFile(new File("chromedriver.log"))
    .build();

WebDriver driver = new ChromeDriver(service, new ChromeOptions());
import java.io.File;
import org.openqa.selenium.chrome.ChromeDriverService;
import org.openqa.selenium.chrome.ChromeOptions;

ChromeDriverService service = new ChromeDriverService.Builder()
    .usingDriverExecutable(new File("/usr/local/bin/chromedriver"))
    .usingPort(9515)
    .withLogFile(new File("chromedriver.log"))
    .build();

WebDriver driver = new ChromeDriver(service, new ChromeOptions());
import java.io.File;
import org.openqa.selenium.chrome.ChromeDriverService;
import org.openqa.selenium.chrome.ChromeOptions;

ChromeDriverService service = new ChromeDriverService.Builder()
    .usingDriverExecutable(new File("/usr/local/bin/chromedriver"))
    .usingPort(9515)
    .withLogFile(new File("chromedriver.log"))
    .build();

WebDriver driver = new ChromeDriver(service, new ChromeOptions());

Python

Method 1: Selenium Manager (Recommended)

Call webdriver.Chrome() with no path, and Selenium Manager handles the driver.

Method 2: An Explicit Path

Python

from selenium import webdriver
from selenium.webdriver.chrome.service import Service

service = Service(executable_path="/usr/local/bin/chromedriver", log_output="chromedriver.log")
driver = webdriver.Chrome(service=service)
driver.get("https://www.example.com")
driver.quit()
from selenium import webdriver
from selenium.webdriver.chrome.service import Service

service = Service(executable_path="/usr/local/bin/chromedriver", log_output="chromedriver.log")
driver = webdriver.Chrome(service=service)
driver.get("https://www.example.com")
driver.quit()
from selenium import webdriver
from selenium.webdriver.chrome.service import Service

service = Service(executable_path="/usr/local/bin/chromedriver", log_output="chromedriver.log")
driver = webdriver.Chrome(service=service)
driver.get("https://www.example.com")
driver.quit()
from selenium import webdriver
from selenium.webdriver.chrome.service import Service

service = Service(executable_path="/usr/local/bin/chromedriver", log_output="chromedriver.log")
driver = webdriver.Chrome(service=service)
driver.get("https://www.example.com")
driver.quit()

Method 3: ChromeDriver on Your PATH

If ChromeDriver is on your PATH and you’re on an older Selenium version, you can start Chrome without a path. On Selenium 4.6 and later, this is also how Selenium Manager is triggered.

Python

from selenium import webdriver

driver = webdriver.Chrome()
from selenium import webdriver

driver = webdriver.Chrome()
from selenium import webdriver

driver = webdriver.Chrome()
from selenium import webdriver

driver = webdriver.Chrome()

Method 4: webdriver-manager for Python

Bash

Python

from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

driver = webdriver.Chrome(service=Service(ChromeDriverManager().install()))
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

driver = webdriver.Chrome(service=Service(ChromeDriverManager().install()))
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

driver = webdriver.Chrome(service=Service(ChromeDriverManager().install()))
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

driver = webdriver.Chrome(service=Service(ChromeDriverManager().install()))
Three ways to get the right driver



Advanced ChromeDriver Configuration


  1. ChromeOptions for Customisation

ChromeOptions lets you control how Chrome starts, from window size and language to download folders and certificate handling.

Java

import java.util.Map;
import org.openqa.selenium.chrome.ChromeOptions;

ChromeOptions options = new ChromeOptions();
options.addArguments("--start-maximized", "--disable-notifications", "--lang=en-GB");
options.setAcceptInsecureCerts(true);   // test environments with self-signed certificates
options.setExperimentalOption("prefs", Map.of("download.default_directory", "/tmp/downloads"));

WebDriver driver = new ChromeDriver(options);
import java.util.Map;
import org.openqa.selenium.chrome.ChromeOptions;

ChromeOptions options = new ChromeOptions();
options.addArguments("--start-maximized", "--disable-notifications", "--lang=en-GB");
options.setAcceptInsecureCerts(true);   // test environments with self-signed certificates
options.setExperimentalOption("prefs", Map.of("download.default_directory", "/tmp/downloads"));

WebDriver driver = new ChromeDriver(options);
import java.util.Map;
import org.openqa.selenium.chrome.ChromeOptions;

ChromeOptions options = new ChromeOptions();
options.addArguments("--start-maximized", "--disable-notifications", "--lang=en-GB");
options.setAcceptInsecureCerts(true);   // test environments with self-signed certificates
options.setExperimentalOption("prefs", Map.of("download.default_directory", "/tmp/downloads"));

WebDriver driver = new ChromeDriver(options);
import java.util.Map;
import org.openqa.selenium.chrome.ChromeOptions;

ChromeOptions options = new ChromeOptions();
options.addArguments("--start-maximized", "--disable-notifications", "--lang=en-GB");
options.setAcceptInsecureCerts(true);   // test environments with self-signed certificates
options.setExperimentalOption("prefs", Map.of("download.default_directory", "/tmp/downloads"));

WebDriver driver = new ChromeDriver(options);

Python

from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument("--start-maximized")
options.add_argument("--disable-notifications")
options.add_argument("--lang=en-GB")
options.accept_insecure_certs = True
options.add_experimental_option("prefs", {"download.default_directory": "/tmp/downloads"})

driver = webdriver.Chrome(options=options)
from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument("--start-maximized")
options.add_argument("--disable-notifications")
options.add_argument("--lang=en-GB")
options.accept_insecure_certs = True
options.add_experimental_option("prefs", {"download.default_directory": "/tmp/downloads"})

driver = webdriver.Chrome(options=options)
from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument("--start-maximized")
options.add_argument("--disable-notifications")
options.add_argument("--lang=en-GB")
options.accept_insecure_certs = True
options.add_experimental_option("prefs", {"download.default_directory": "/tmp/downloads"})

driver = webdriver.Chrome(options=options)
from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument("--start-maximized")
options.add_argument("--disable-notifications")
options.add_argument("--lang=en-GB")
options.accept_insecure_certs = True
options.add_experimental_option("prefs", {"download.default_directory": "/tmp/downloads"})

driver = webdriver.Chrome(options=options)


  1. Running Tests in Headless Mode

Headless Chrome runs without a visible window, which suits CI/CD pipelines and servers without a screen. Use the new headless mode, which behaves like the real browser. From Chrome 132, --headless uses the new mode by default, and the old one now lives in a separate chrome-headless-shell binary.

Python

options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
options.add_argument("--window-size=1920,1080")   # headless defaults to a small window
driver = webdriver.Chrome(options=options)
options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
options.add_argument("--window-size=1920,1080")   # headless defaults to a small window
driver = webdriver.Chrome(options=options)
options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
options.add_argument("--window-size=1920,1080")   # headless defaults to a small window
driver = webdriver.Chrome(options=options)
options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
options.add_argument("--window-size=1920,1080")   # headless defaults to a small window
driver = webdriver.Chrome(options=options)

Java

ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new", "--window-size=1920,1080");
WebDriver driver = new ChromeDriver(options);
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new", "--window-size=1920,1080");
WebDriver driver = new ChromeDriver(options);
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new", "--window-size=1920,1080");
WebDriver driver = new ChromeDriver(options);
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new", "--window-size=1920,1080");
WebDriver driver = new ChromeDriver(options);

Headless runs are usually a little faster, work on servers with no display, and fit naturally into Jenkins, Azure DevOps and GitHub Actions.

Headless runs bring their own surprises, like small default windows and missing fonts, and our guide to headless browser testing with Selenium covers how to handle them.


  1. Managing User Profiles and Sessions

You can point Chrome at a profile folder to keep cookies, local storage and settings between runs. Use a dedicated folder for testing, never your everyday Chrome profile, because recent Chrome versions restrict automation of the default profile for security.

Python

options = webdriver.ChromeOptions()
options.add_argument("--user-data-dir=/tmp/selenium-chrome-profile")
options.add_argument("--profile-directory=Default")
driver = webdriver.Chrome(options=options)
options = webdriver.ChromeOptions()
options.add_argument("--user-data-dir=/tmp/selenium-chrome-profile")
options.add_argument("--profile-directory=Default")
driver = webdriver.Chrome(options=options)
options = webdriver.ChromeOptions()
options.add_argument("--user-data-dir=/tmp/selenium-chrome-profile")
options.add_argument("--profile-directory=Default")
driver = webdriver.Chrome(options=options)
options = webdriver.ChromeOptions()
options.add_argument("--user-data-dir=/tmp/selenium-chrome-profile")
options.add_argument("--profile-directory=Default")
driver = webdriver.Chrome(options=options)

This is useful for testing signed-in sessions, starting tests from a known application state and checking user-specific settings. Remember that shared profiles can make tests depend on each other, so keep them out of parallel runs.



Common ChromeDriver Errors and How to Fix Them


  1. SessionNotCreatedException: Version Mismatch

Error message

org.openqa.selenium.SessionNotCreatedException: Could not start a new session.
Response code 500. Message: session not created: This version of ChromeDriver only supports Chrome version 141
Current browser version is 142

org.openqa.selenium.SessionNotCreatedException: Could not start a new session.
Response code 500. Message: session not created: This version of ChromeDriver only supports Chrome version 141
Current browser version is 142

org.openqa.selenium.SessionNotCreatedException: Could not start a new session.
Response code 500. Message: session not created: This version of ChromeDriver only supports Chrome version 141
Current browser version is 142

org.openqa.selenium.SessionNotCreatedException: Could not start a new session.
Response code 500. Message: session not created: This version of ChromeDriver only supports Chrome version 141
Current browser version is 142

Cause. ChromeDriver’s major version doesn’t match Chrome’s, usually because Chrome updated itself.

Fix. The simplest fix is to remove the hard-coded driver path and let Selenium Manager pick the right version. Otherwise, check your Chrome version, download the matching ChromeDriver from Chrome for Testing and replace the old file.


  1. Driver Not Found

Error message (Java, older Selenium)

java.lang.IllegalStateException: The path to the driver executable must be set
java.lang.IllegalStateException: The path to the driver executable must be set
java.lang.IllegalStateException: The path to the driver executable must be set
java.lang.IllegalStateException: The path to the driver executable must be set

Error message (Python, Selenium 4)

selenium.common.exceptions.NoSuchDriverException: Message: Unable to obtain driver for
selenium.common.exceptions.NoSuchDriverException: Message: Unable to obtain driver for
selenium.common.exceptions.NoSuchDriverException: Message: Unable to obtain driver for
selenium.common.exceptions.NoSuchDriverException: Message: Unable to obtain driver for

Cause. Selenium can’t find ChromeDriver on your PATH or at the path you gave, and Selenium Manager couldn’t download one, often because of a firewall or proxy.

Fix. Check the path, add ChromeDriver’s folder to your PATH, or allow Selenium Manager to reach the Chrome for Testing download site.

Windows (Command Prompt)

macOS and Linux (Terminal)

which chromedriver
echo $PATH
which chromedriver
echo $PATH
which chromedriver
echo $PATH
which chromedriver
echo $PATH


  1. Permission Denied (macOS and Linux)

Error message

PermissionError: [Errno 13] Permission denied: '/usr/local/bin/chromedriver'
PermissionError: [Errno 13] Permission denied: '/usr/local/bin/chromedriver'
PermissionError: [Errno 13] Permission denied: '/usr/local/bin/chromedriver'
PermissionError: [Errno 13] Permission denied: '/usr/local/bin/chromedriver'

Cause. The file isn’t marked as executable.

Fix (Terminal)

chmod
chmod
chmod
chmod


  1. Gatekeeper Block (macOS)

Error message

"chromedriver"
"chromedriver"
"chromedriver"
"chromedriver"

Cause. macOS Gatekeeper blocks programs downloaded from the internet until you approve them.

Fix (Terminal)

xattr -d
xattr -d
xattr -d
xattr -d

Or open System Settings, go to Privacy and Security, and choose “Allow Anyway”.


  1. Connection Refused

Error message (Python)

urllib3.exceptions.MaxRetryError: HTTPConnectionPool(host='localhost', port=9515):
Max retries exceeded ... [Errno 61

urllib3.exceptions.MaxRetryError: HTTPConnectionPool(host='localhost', port=9515):
Max retries exceeded ... [Errno 61

urllib3.exceptions.MaxRetryError: HTTPConnectionPool(host='localhost', port=9515):
Max retries exceeded ... [Errno 61

urllib3.exceptions.MaxRetryError: HTTPConnectionPool(host='localhost', port=9515):
Max retries exceeded ... [Errno 61

Cause. The ChromeDriver process didn’t start, or crashed.

Fix. Check that nothing else is using the port, that ChromeDriver has permission to run and that Chrome itself is installed properly. Then kill any stuck ChromeDriver processes.

Windows (Command Prompt)

macOS and Linux (Terminal)

pkill -f
pkill -f
pkill -f
pkill -f


  1. Element Not Interactable

Error message

Cause. The element exists, but isn’t ready yet. It might still be loading, hidden or covered by an overlay. This isn’t really a ChromeDriver problem, but it’s one of the first errors people hit after set-up.

Fix (Java)

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.elementToBeClickable(By.id("submit"

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.elementToBeClickable(By.id("submit"

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.elementToBeClickable(By.id("submit"

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.elementToBeClickable(By.id("submit"

Overlays, animations and hidden elements cause most of these failures, and the full set of causes and fixes is in our guide to ElementNotInteractableException in Selenium.



The Hidden Cost of ChromeDriver Management


  1. Keeping Versions in Step

Chrome ships a new major version roughly every four weeks, and ChromeDriver has to keep up. Selenium Manager removes most of the pain on developer machines, but at scale someone still has to watch which Chrome version runs in each environment, keep CI images current, retest after browser updates, and manage different versions for different test environments.


  1. Differences Between Platforms

Windows brings PATH settings and antivirus software that quarantines unknown executables. macOS brings Gatekeeper and separate Apple silicon and Intel builds. Linux brings package conflicts, missing system libraries in slim containers and permission issues. Running the same suite everywhere means keeping all three healthy.


  1. CI/CD Complications

Build pipelines add another layer. Docker images need Chrome and ChromeDriver installed and kept current, locked-down build agents may block Selenium Manager’s downloads, and a local machine on one Chrome version with CI on another is a classic source of tests that pass for you and fail in the pipeline. Many teams end up writing their own scripts just to keep versions aligned.


  1. Time Spent Keeping Tests Running

Driver management is only part of the upkeep of a Selenium suite. Locators break when the UI changes, timing issues cause flaky tests, and every fix takes an engineer’s time. Each hour spent there is an hour not spent on new coverage.

Tests that fail one run and pass the next are often a symptom of version drift or timing, and our guide to flaky tests shows how to track them down.



The Alternative: Cloud-Based Browser Testing


  1. No Infrastructure to Maintain

Cloud testing platforms remove driver management entirely. Browsers and drivers are set up and kept current for you, there’s nothing to install locally, and you never match versions by hand.


  1. Cross-Browser Testing at Scale

Instead of one browser on one machine, you get current and older versions of Chrome, Firefox, Safari and Edge, run in parallel. A team testing five browsers across several versions would otherwise be maintaining dozens of local configurations.


  1. From Infrastructure to Test Strategy

AI-native platforms go a step further, and change what your team spends its time on.

  • Plain English tests: testers write steps in everyday language, with no driver code at all.

  • Proposed fixes, not broken runs: when the UI changes, the platform proposes an updated step for your team to accept or reject.

  • Tests drafted from requirements: AI agents turn user stories and specs into draft tests, which a person approves.

  • Smarter element finding: elements are found using several clues, like label, position and context, rather than one fragile locator.



ChromeDriver Best Practices

If You’re Staying with Selenium and ChromeDriver

  • Use Selenium Manager. Upgrade to Selenium 4.6 or later, and remove hard-coded driver paths.

  • Pin browser versions in CI. Use setBrowserVersion() or a fixed Docker image, so an overnight Chrome update doesn’t break the build.

  • Use headless mode properly. Use --headless=new and set a window size.

  • Keep driver config in version control, alongside your test code.

  • Watch Chrome’s release schedule, and test against Chrome Beta to see changes coming.

  • Prefer explicit waits, using WebDriverWait with expected conditions, rather than sleeps.

Choosing between implicit, explicit and fluent waits makes a bigger difference to stability than most driver settings, as our guide to Selenium timeouts explains.

When It’s Time to Move On

It’s worth looking at a platform when driver and environment upkeep keeps interrupting releases, when CI failures are more often about versions than about your application, when coverage has stalled because the team spends its time on maintenance, or when you need cross-browser coverage without building and running your own grid.



Leave Driver Management Behind with Virtuoso QA

ChromeDriver set-up is a solved problem for one machine. It’s an ongoing job across a team, a pipeline and every browser your users have.

Virtuoso QA takes that whole layer away. Tests are written in plain English and run in the cloud across 2,000+ browser and OS combinations, with no drivers to install, match or update.

Existing Selenium suites come across through GENerator, which converts them into plain English journeys, so your coverage carries over. And when the UI changes, Virtuoso QA proposes a fix for your team to approve, instead of leaving a broken locator for someone to find.



Related Reads

ChromeDriver FAQs

Do I still need to download ChromeDriver for Selenium?

How do I fix a ChromeDriver version mismatch?

Where do I download ChromeDriver for Chrome 115 and later?

What's the difference between Selenium Manager and WebDriverManager?

How do I run ChromeDriver in headless mode?

Why does macOS block ChromeDriver?

Written by

Rishabh Kumar

AI Testing & Quality Engineering Contributor

Rishabh leads business development and marketing at Virtuoso QA. He writes about AI-powered test automation, end-to-end testing, self-healing tests, and quality engineering, exploring how these capabilities can improve test coverage, reduce test maintenance, and support reliable software releases.

See what your next release looks like with Virtuoso

Book a walkthrough on your applications and your workflows. Bring a requirement, a user journey, or a brittle Selenium script, and watch the loop run on something you recognise.

See what your next release looks like with Virtuoso

Book a walkthrough on your applications and your workflows. Bring a requirement, a user journey, or a brittle Selenium script, and watch the loop run on something you recognise.

See what your next release looks like with Virtuoso

Book a walkthrough on your applications and your workflows. Bring a requirement, a user journey, or a brittle Selenium script, and watch the loop run on something you recognise.

Virtuoso QA is establishing the standard of proof for software releases. Its governed QA loop turns business requirements into tests for any browser-based application: AI proposes, a deterministic engine executes, a person approves what matters, and every decision leaves evidence.

Trust Center

AICPA

SOC

WAVE STRONG PERFORMER

@ Copyright 2026 SpotQA, Creators of Virtuoso QA

Virtuoso QA is establishing the standard of proof for software releases. Its governed QA loop turns business requirements into tests for any browser-based application: AI proposes, a deterministic engine executes, a person approves what matters, and every decision leaves evidence.

Trust Center

AICPA

SOC

WAVE STRONG PERFORMER

@ Copyright 2026 SpotQA, Creators of Virtuoso QA

Virtuoso QA is establishing the standard of proof for software releases. Its governed QA loop turns business requirements into tests for any browser-based application: AI proposes, a deterministic engine executes, a person approves what matters, and every decision leaves evidence.

Trust Center

AICPA

SOC

WAVE STRONG PERFORMER

@ Copyright 2026 SpotQA, Creators of Virtuoso QA