webdriver-manager 4.1.0

Add your description here

Webdriver Manager for Python

webdriver-manager is a Python library for explicit browser driver management.

It helps download, resolve, cache, and reuse driver binaries for browser automation with Selenium. Instead of downloading a driver manually, unpacking it, and hardcoding a path, you can install the required driver directly from Python code.

Note

For most modern Selenium 4.6+ projects, Selenium Manager is the recommended default. It is built into Selenium and can manage drivers automatically for standard Chrome, Firefox, and Edge setups.

Use webdriver-manager when you need explicit control over driver versions, driver paths, cache behavior, download sources, or compatibility with older Selenium versions.

When should I use webdriver-manager?

Use webdriver-manager when Selenium Manager is not enough or when you want to manage drivers explicitly from Python code.

Typical use cases include:

• supporting Selenium 3 or older Selenium 4 projects;
• getting the driver binary path directly;
• pinning or resolving a specific driver version;
• pre-downloading drivers in CI or Docker images;
• customizing cache location or cache invalidation;
• using custom download URLs or mirrors;
• working around corporate proxy, SSL, or restricted network environments;
• using alternative Chromium-based browsers such as Chromium or Brave;
• customizing OS or architecture detection;
• debugging driver resolution and download behavior explicitly.

If your code works with plain Selenium:

from selenium import webdriver

driver = webdriver.Chrome()

you probably do not need webdriver-manager.

If you need more control over how drivers are resolved, downloaded, cached, or reused, webdriver-manager can still be useful.

Selenium Manager vs webdriver-manager

Selenium Manager is automatic and integrated into Selenium. It is usually the best choice for new Selenium 4.6+ projects with standard browser setups.

webdriver-manager is explicit and configurable. It is useful when you want to manage driver resolution yourself, integrate driver installation into your own Python code, or support environments where Selenium Manager is not enough or not desired.

In short:

• use Selenium Manager by default;
• use webdriver-manager when you need explicit control.

Supported drivers

webdriver-manager currently supports:

• ChromeDriver
• EdgeChromiumDriver
• GeckoDriver
• IEDriver
• OperaDriver

The library is compatible with Selenium 4.x and older Selenium versions.

Installation

pip install webdriver-manager

Package name:

webdriver-manager

Import name:

import webdriver_manager

Environment scope

webdriver-manager manages desktop browser drivers for Windows, macOS, and Linux desktop runtimes.

It is not intended for Android or PyDroid local browser automation. For Android automation, use Appium with UiAutomator2 and Chrome/WebView on a device or emulator.

Usage

Use with Chrome

Selenium 4

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

service = ChromeService(ChromeDriverManager().install())
driver = webdriver.Chrome(service=service)

Selenium 3

from selenium import webdriver
from webdriver_manager.chrome import ChromeDriverManager

driver = webdriver.Chrome(ChromeDriverManager().install())

Use with Chromium

Selenium 4

from selenium import webdriver
from selenium.webdriver.chrome.service import Service as ChromiumService
from webdriver_manager.chrome import ChromeDriverManager
from webdriver_manager.core.os_manager import ChromeType

options = webdriver.ChromeOptions()
options.binary_location = "/usr/bin/chromium"

service = ChromiumService(
    ChromeDriverManager(chrome_type=ChromeType.CHROMIUM).install()
)

driver = webdriver.Chrome(service=service, options=options)

Selenium 3

from selenium import webdriver
from webdriver_manager.chrome import ChromeDriverManager
from webdriver_manager.core.os_manager import ChromeType

options = webdriver.ChromeOptions()
options.binary_location = "/usr/bin/chromium"

driver = webdriver.Chrome(
    ChromeDriverManager(chrome_type=ChromeType.CHROMIUM).install(),
    options=options,
)

On macOS, the Chromium binary path may look like this:

/Applications/Chromium.app/Contents/MacOS/Chromium

Use with Brave

Selenium 4

from selenium import webdriver
from selenium.webdriver.chrome.service import Service as BraveService
from webdriver_manager.chrome import ChromeDriverManager
from webdriver_manager.core.os_manager import ChromeType

service = BraveService(
    ChromeDriverManager(chrome_type=ChromeType.BRAVE).install()
)

driver = webdriver.Chrome(service=service)

Selenium 3

from selenium import webdriver
from webdriver_manager.chrome import ChromeDriverManager
from webdriver_manager.core.os_manager import ChromeType

driver = webdriver.Chrome(
    ChromeDriverManager(chrome_type=ChromeType.BRAVE).install()
)

Use with Edge

Selenium 4

from selenium import webdriver
from selenium.webdriver.edge.service import Service as EdgeService
from webdriver_manager.microsoft import EdgeChromiumDriverManager

service = EdgeService(EdgeChromiumDriverManager().install())
driver = webdriver.Edge(service=service)

Selenium 3

from selenium import webdriver
from webdriver_manager.microsoft import EdgeChromiumDriverManager

driver = webdriver.Edge(EdgeChromiumDriverManager().install())

Use with Firefox

Selenium 4

from selenium import webdriver
from selenium.webdriver.firefox.service import Service as FirefoxService
from webdriver_manager.firefox import GeckoDriverManager

service = FirefoxService(GeckoDriverManager().install())
driver = webdriver.Firefox(service=service)

Selenium 3

from selenium import webdriver
from webdriver_manager.firefox import GeckoDriverManager

driver = webdriver.Firefox(executable_path=GeckoDriverManager().install())

Use with Internet Explorer

Note

Internet Explorer support is provided for legacy environments.

Selenium 4

from selenium import webdriver
from selenium.webdriver.ie.service import Service as IEService
from webdriver_manager.microsoft import IEDriverManager

service = IEService(IEDriverManager().install())
driver = webdriver.Ie(service=service)

Selenium 3

from selenium import webdriver
from webdriver_manager.microsoft import IEDriverManager

driver = webdriver.Ie(IEDriverManager().install())

Use with Opera

Note

OperaDriver support is provided for compatibility with existing setups.

Selenium 4

from selenium import webdriver
from selenium.webdriver.chrome import service
from webdriver_manager.opera import OperaDriverManager

webdriver_service = service.Service(OperaDriverManager().install())
webdriver_service.start()

options = webdriver.ChromeOptions()
options.add_experimental_option("w3c", True)

driver = webdriver.Remote(webdriver_service.service_url, options=options)

Selenium 3

from selenium import webdriver
from selenium.webdriver.chrome import service
from webdriver_manager.opera import OperaDriverManager

webdriver_service = service.Service(OperaDriverManager().install())
webdriver_service.start()

driver = webdriver.Remote(
    webdriver_service.service_url,
    webdriver.DesiredCapabilities.OPERA,
)

If Opera is installed in a non-standard location, specify the browser binary path:

options = webdriver.ChromeOptions()
options.binary_location = "path/to/opera"

driver = webdriver.Remote(webdriver_service.service_url, options=options)

Configuration

webdriver-manager can be configured with environment variables, constructor arguments, or custom manager classes.

GH_TOKEN

Some drivers are downloaded from official GitHub repositories. GitHub limits unauthenticated API requests, so you may need a GitHub token to avoid rate-limit errors.

Set the token as an environment variable:

export GH_TOKEN="your_token"

Or set it from Python:

import os

os.environ["GH_TOKEN"] = "your_token"

WDM_LOG

Disable webdriver-manager logs:

import logging
import os

os.environ["WDM_LOG"] = str(logging.NOTSET)

WDM_LOCAL

By default, driver binaries are saved to the user-level .wdm cache directory.

You can store binaries in the project root instead:

import os

os.environ["WDM_LOCAL"] = "1"

This is often useful in Docker and CI environments where home-directory permissions are restricted.

You can also pass a custom writable cache location through DriverCacheManager(root_dir=...).

WDM_SSL_VERIFY

SSL verification can be disabled when downloading driver binaries:

import os

os.environ["WDM_SSL_VERIFY"] = "0"

Use this only when required by your environment, for example with corporate SSL inspection or custom certificate chains.

Driver version

You can request a specific driver version:

from webdriver_manager.chrome import ChromeDriverManager

ChromeDriverManager(driver_version="2.26").install()

Cache validity

By default, the driver cache is valid for 1 day.

You can change the cache validity range:

from webdriver_manager.chrome import ChromeDriverManager
from webdriver_manager.core.driver_cache import DriverCacheManager

cache_manager = DriverCacheManager(valid_range=7)

ChromeDriverManager(cache_manager=cache_manager).install()

Custom OS or architecture

You can override OS or architecture detection:

from webdriver_manager.chrome import ChromeDriverManager
from webdriver_manager.core.os_manager import OperationSystemManager

os_manager = OperationSystemManager(os_type="linux-mips64")

ChromeDriverManager(os_system_manager=os_manager).install()

Custom download URL

You can use a custom driver repository or mirror:

from webdriver_manager.chrome import ChromeDriverManager

ChromeDriverManager(
    url="https://custom-repo.example.com",
    latest_release_url="https://custom-repo.example.com/LATEST",
).install()

Get browser version from path

You can detect a browser version from its executable and use that version to resolve a driver:

from webdriver_manager.chrome import ChromeDriverManager
from webdriver_manager.core.os_manager import PATTERN
from webdriver_manager.core.utils import read_version_from_cmd

browser_version = read_version_from_cmd(
    "/usr/bin/google-chrome --version",
    PATTERN["chrome"],
)

driver_path = ChromeDriverManager(driver_version=browser_version).install()

Custom cache, file manager, and OS manager

You can customize cache, file, and OS behavior:

from webdriver_manager.chrome import ChromeDriverManager
from webdriver_manager.core.driver_cache import DriverCacheManager
from webdriver_manager.core.file_manager import FileManager
from webdriver_manager.core.os_manager import OperationSystemManager

os_manager = OperationSystemManager(os_type="win64")
file_manager = FileManager(os_system_manager=os_manager)
cache_manager = DriverCacheManager(file_manager=file_manager)

manager = ChromeDriverManager(cache_manager=cache_manager)
driver_path = manager.install()

Custom logger

You can configure a custom logger with set_logger():

import logging

from webdriver_manager.core.logger import set_logger

logger = logging.getLogger("webdriver_manager")
logger.setLevel(logging.DEBUG)

logger.addHandler(logging.StreamHandler())
logger.addHandler(logging.FileHandler("webdriver_manager.log"))

set_logger(logger)

Custom HTTP client

You can provide a custom HTTP client for advanced network behavior such as custom sessions, proxies, authentication, or retries.

import os

import requests
from requests import Response

from webdriver_manager.chrome import ChromeDriverManager
from webdriver_manager.core.download_manager import WDMDownloadManager
from webdriver_manager.core.http import HttpClient
from webdriver_manager.core.logger import log


class CustomHttpClient(HttpClient):
    def get(self, url, params=None, **kwargs) -> Response:
        log("Downloading driver with a custom HTTP client")
        return requests.get(url, params=params, **kwargs)


http_client = CustomHttpClient()
download_manager = WDMDownloadManager(http_client)

driver_path = ChromeDriverManager(download_manager=download_manager).install()

assert os.path.exists(driver_path)

CI and Docker recommendations

For CI and Docker environments:

• prefer a writable cache directory;
• use WDM_LOCAL=1 when project-local caching is easier than user-level caching;
• set GH_TOKEN if your workflow may hit GitHub API rate limits;
• consider pre-downloading drivers during the image build or CI setup phase;
• pin driver or browser versions when reproducibility is more important than automatic updates.

Example:

export WDM_LOCAL=1
export GH_TOKEN="your_token"

Reporting issues

When reporting a bug, include:

• operating system and architecture;
• Python version;
• Selenium version;
• webdriver-manager version;
• browser name and version;
• full traceback;
• minimal reproducible example;
• whether the issue happens locally, in CI, or in Docker.

Clear reproduction steps make driver-resolution and cache-related issues much easier to investigate.

Contributing

Bug fixes, compatibility fixes, CI improvements, documentation updates, and regression tests are welcome.

For larger changes, please open an issue first to discuss the proposed approach.

Maintenance status

The project accepts maintenance contributions focused on:

• browser and driver compatibility;
• cache and download reliability;
• CI stability;
• documentation quality;
• regression tests;
• compatibility with supported Selenium versions.

Large feature changes should be discussed before implementation.

License

See the repository license for details.