How to Use Selenium Manager to Set Up Browser Drivers

Selenium Manager sets up browser drivers automatically when you create a local WebDriver session with a current Selenium binding. Install or upgrade Selenium to version 4.6 or later, make sure the browser is available, and use the binding’s normal browser constructor. If Selenium reports “Unable to locate driver,” this is the first setup to check.

You generally do not need to download a driver yourself, install a separate driver-manager package, or call Selenium Manager directly. It is a fallback: an existing driver on PATH or an explicitly configured driver path can take precedence. This guide covers the normal setup, configuration, CI and offline considerations, and fixes for common errors. For a browser-free alternative when the goal is to capture a webpage image or PDF, see ScreenshotNeo.

1. Install or upgrade Selenium

Selenium Manager is included with Selenium bindings starting in Selenium 4.6. Upgrade an older binding before relying on automatic driver resolution. Use your project’s normal dependency manager and keep the version pinned according to your project’s compatibility policy.

Python

python -m pip install -U selenium

A virtual environment helps keep the Selenium dependency isolated from other Python projects. The code below assumes Selenium is installed in the active environment.

JavaScript

npm install selenium-webdriver

For Java, .NET, Ruby, or another supported binding, install or update the official Selenium binding using that ecosystem’s package manager. The automatic driver setup is part of the binding workflow.

2. Create a local browser session

Install the browser you want to automate, then construct its WebDriver normally. When no driver is otherwise configured, the binding invokes Selenium Manager to locate a compatible driver.

Python: Chrome

from selenium import webdriver

# The binding invokes Selenium Manager when it needs to resolve a driver.
driver = webdriver.Chrome()
try:
    driver.get("https://www.selenium.dev")
    print(driver.title)
finally:
    driver.quit()

JavaScript: Chrome

const { Builder, Browser } = require('selenium-webdriver');

(async () => {
  const driver = await new Builder().forBrowser(Browser.CHROME).build();
  try {
    await driver.get('https://www.selenium.dev');
    console.log(await driver.getTitle());
  } finally {
    await driver.quit();
  }
})();

Use the equivalent browser constructor for Firefox or Edge in your binding. Avoid copying old examples that hard-code a driver executable path unless you have a reason to manage that executable yourself.

3. What Selenium Manager does on first launch

1. The Selenium binding checks whether a driver is already provided, such as through PATH or an explicit service path.
2. If it needs to resolve a driver, Selenium Manager identifies the browser and its version, then resolves a compatible driver using browser-vendor metadata.
3. It downloads and unpacks the driver, then stores it in its cache.
4. Later sessions can reuse the cached executable. Metadata used for version discovery has a documented default time-to-live of 3,600 seconds (one hour); this is not the driver’s expiration time.

The default cache directory is ~/.cache/selenium. First-time setup may need network access to resolve metadata and download the driver. Cached assets can be reused, but an empty cache in a network-restricted environment needs a proxy or pre-provisioned assets.

4. Driver management and browser management are different

Selenium Manager can resolve a driver for an installed browser. Downloading and installing the browser itself is a separate, version-dependent feature. Documented browser-management thresholds are:

Browser	Browser management available from	Notes
Chrome	Selenium 4.11.0	Uses Chrome for Testing.
Firefox	Selenium 4.12.0	Uses public Firefox releases.
Edge	Selenium 4.14.0	On Windows, automated installation requires administrator permissions because the installer is an MSI.

Depending on the binding, browser options can request a browser version such as stable, beta, dev, or canary; Firefox also documents esr. Exact support depends on the Selenium release, browser, and platform. Do not assume that a Selenium version that manages drivers can also install a missing browser. For predictable builds, specify and provision the browser version deliberately.

5. Configure Selenium Manager when defaults do not fit

Most local sessions need no Selenium Manager settings. When you need a proxy, a different cache, explicit versions, or offline operation, configuration can be supplied through CLI arguments, a se-config.toml file in the Selenium cache, or environment variables. The precedence is CLI arguments, then configuration file, then environment variables. Browser bindings can pass relevant arguments through browser options; consult your binding’s current Selenium Manager documentation for the exact option wiring.

Need	Documented setting	What it does
Use a network proxy	SE_PROXY or --proxy	Routes Selenium Manager’s network requests through the configured proxy.
Run without network requests	SE_OFFLINE=true or --offline	Disables network requests and downloads. Required assets must already be available.
Move the cache	SE_CACHE_PATH or --cache-path	Changes where Selenium Manager keeps assets and metadata.
Choose browser or driver versions	SE_BROWSER_VERSION, SE_DRIVER_VERSION and browser-specific variants	Requests version choices where supported by the binding and browser setup.
Specify a browser executable	SE_BROWSER_PATH or binding-specific browser options	Points Selenium at a non-default browser installation.
Opt out of usage statistics	SE_AVOID_STATS=true or avoid-stats = true	Disables the documented anonymized usage statistics.

Example: use a proxy in a shell

export SE_PROXY="http://proxy.example:8080"
python your_script.py

Replace the example proxy address with the endpoint provided by your network administrator. If credentials or a different proxy scheme are required, follow your proxy’s configuration requirements and avoid committing secrets to source control.

Example: offline execution

export SE_OFFLINE=true
python your_script.py

Use offline mode only after the required browser and driver assets are already present in the configured cache or provisioned by your environment. Offline mode does not supply missing files.

6. Choose between automatic and explicit driver management

Approach	Good fit	Trade-off
Selenium Manager defaults	Local development and environments where resolving a driver from the installed browser is convenient.	Initial resolution may require network access; an automatically selected driver follows the available browser.
Driver on PATH or explicit service path	Environments that deliberately provision and pin a driver or must use a particular executable.	You own compatibility and updates. A stale driver can prevent Selenium Manager’s fallback from running.
Remote WebDriver or Grid	Tests run on a separate node, container, or remote service.	The remote node or service owns browser and driver availability; local client setup alone does not install them remotely.

For a repeatable CI environment, make the browser version and the driver-resolution strategy part of the environment setup. Decide whether the job downloads assets during execution or uses assets provisioned in advance. Keep browser and driver changes coordinated so a preinstalled stale executable does not override automatic resolution.

7. Remote execution: configure the node, not the client

A local WebDriver starts a driver service on the machine running the script. A remote WebDriver client instead sends commands to a Grid or another remote WebDriver endpoint. The browser and driver must be available on the remote node or managed by that service. Configure the remote endpoint and browser capabilities in the client, and check the node’s browser and driver setup when session creation fails. Selenium Grid documentation describes enabling Selenium Manager on Grid nodes with --selenium-manager true.

8. Troubleshoot setup errors

Symptom	Likely cause	What to do
“Unable to locate driver” or driver executable not found	Old Selenium binding, blocked downloads, missing browser, or unsupported environment.	Check that the binding is Selenium 4.6 or later; confirm the browser is installed; check network or proxy access. If the environment is offline, provision the compatible assets and cache first.
Driver supports a different browser version	An old driver on PATH, an explicit service path, or third-party manager configuration takes precedence.	Inspect the resolved executable and remove or update stale explicit configuration if automatic resolution is intended. If pinning is intentional, align the browser and driver versions.
First run fails to download a driver	Network policy, proxy configuration, or vendor metadata access prevents resolution.	Verify outbound access or configure SE_PROXY. Alternatively, provision compatible assets and use offline mode only once they are available.
Browser is missing	Driver management was mistaken for browser installation, or the binding is below the browser-management threshold.	Install the browser yourself or use a Selenium release with documented browser management for that browser. On Windows, Edge installation requires administrator permissions.
Local code works, remote session fails	The remote Grid node lacks a compatible browser or driver, or the endpoint/capabilities are incorrect.	Check the remote endpoint, requested browser capabilities, and the node’s provisioning and Selenium Manager configuration.
New options or setup examples do not match the project	Legacy Selenium APIs or examples target a different binding release.	Use Selenium 4 browser options and the binding’s Service object for local service customization; check current official binding documentation for the API and Selenium Manager option names.

When the error is ambiguous, first establish which browser executable and driver executable the process actually sees. Check for explicit service paths and PATH entries before changing Selenium Manager settings, because its fallback only helps when another driver has not already been supplied.

9. Performance, reliability, and cost considerations

• Startup: the first uncached session can spend time resolving metadata and downloading a driver. Later sessions can reuse the cache. The documentation provides no benchmark, so actual startup time depends on the environment and network.
• Reliability: automatic matching avoids routine manual driver downloads, but it depends on browser detection and, when assets are missing, network access. A pre-provisioned cache or explicitly managed assets can suit restricted CI environments.
• Reproducibility: allowing the detected browser to determine the driver is convenient. For stable CI results, control browser versions and the assets available to the job.
• Cost: Selenium and Selenium Manager are part of the Selenium software setup; this workflow does not require buying a separate driver-manager dependency. Infrastructure, network access, and any remote browser service are separate considerations.

Or skip the browser setup

If your goal is a webpage screenshot or PDF rather than browser automation, ScreenshotNeo captures a URL through one API request. See the API documentation for the request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = require('node:fs');
fs.writeFileSync('shot.webp', Buffer.from(await res.arrayBuffer()));

• Cookie banners are accepted and removed before capture, along with supported newsletter popups and chat widgets; each cleanup step can be turned off.
• Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Response headers report the page verdict and billing status.
• An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.
• The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

FAQ

Do I install Selenium Manager separately?

No. It is included with Selenium bindings; update the binding if the project predates Selenium 4.6.

Does Selenium Manager install Chrome, Firefox, or Edge automatically?

Browser downloads are a separate feature with browser-specific Selenium version thresholds. Driver setup alone does not imply a missing browser will be installed.

Can I still pin a driver?

Yes. A driver on PATH or an explicit service path can be used. Keep it compatible with the browser, because that configuration can take precedence over Selenium Manager.

Does this setup configure a remote Grid browser?

No. A remote session uses the browser and driver available on the Grid node or remote service.