Registry / testing / undetected-chromedriver

undetected-chromedriver

library3.5.5pypypi✓ verified 24d ago

Undetected ChromeDriver is a Python library that serves as a `selenium.webdriver.Chrome` replacement, optimized to bypass anti-bot detection systems like Cloudflare, Imperva, and DataDome. It automatically downloads and patches the appropriate ChromeDriver binary for the installed Chrome version. The library is actively maintained, with version 3.5.5 being the latest stable release, and it offers ongoing efforts to understand and counter detection algorithms.

testing http-networking

pip install undetected-chromedriver

github ↗package ↗

INSTALL

IMPORT

SIG · UNDETECTED-CHROMED

undetected-chromedriver

testingpythonv3.5.5

Install

5.2s avg

Import

950ms

Disk

58MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.5.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.624s · 58.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.2s · import 0.516s · 59MB

58MB installed

● package 58MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Chrome

✓ from undetected_chromedriver import Chrome

✗ from undetected_chromedriver import Chrome

This quickstart demonstrates how to initialize `undetected-chromedriver`, navigate to a website that performs bot detection, and verify successful access by printing the page title and saving a screenshot. It includes best practices for resource cleanup and stability.

import undetected_chromedriver as uc import time import os # Create an undetected Chrome instance # use_subprocess=True is often recommended for stability # and to avoid issues with ChromeDriver matching. driver = uc.Chrome(use_subprocess=True) try: # Navigate to a website known for bot detection checks driver.get("https://nowsecure.nl") # Give it some time to load and for anti-bot measures to potentially resolve time.sleep(5) # Print the page title to verify print(f"Page title: {driver.title}") # Optionally take a screenshot screenshot_path = "nowsecure_screenshot.png" driver.save_screenshot(screenshot_path) print(f"Screenshot saved to {screenshot_path}") except Exception as e: print(f"An error occurred: {e}") finally: # Always ensure the driver is quit to clean up resources driver.quit() print("Browser closed.")

Debug

Known issues

breakingVersion 3.4.0 introduced significant changes to the anti-detection mechanism and file naming, potentially breaking existing code. Version 3.5.0 further removed `service_args`, `service_creationflags`, and `service_log_path` from the constructor. Users upgrading from older versions (especially pre-3.4.0) should review their code and migration guides.

fix

Review release notes for versions 3.4.0 and 3.5.0 on GitHub for necessary code adjustments. Avoid using removed constructor arguments.

affects: >=3.4.0

gotchaWhile technically possible (`headless=True`), headless mode is officially unsupported and generally less undetectable than running Chrome with a visible UI. Websites can employ various techniques to detect headless browsers, increasing the likelihood of being blocked.

fix

Run Chrome in non-headless mode if possible for better anti-detection results. If headless is essential, be prepared for increased detection rates and consider additional stealth techniques.

affects: All

gotchaThis library *does not* hide your IP address. Running scripts from data centers or with low IP reputation will still likely result in detection and blocking, regardless of `undetected-chromedriver`.

fix

Integrate a robust proxy solution (e.g., rotating proxies) with `undetected-chromedriver` to mask your IP address, especially when operating from data centers or at scale.

affects: All

gotchaA common issue arises when Chrome auto-updates, leading to a version mismatch with the `chromedriver` binary downloaded by the library. This can cause `WebDriverException` errors (e.g., 'This version of ChromeDriver only supports Chrome version X, Current browser version is Y').

fix

Ensure your local Chrome browser is up-to-date. If issues persist, try initializing `uc.Chrome(version_main=YOUR_CHROME_MAJOR_VERSION)` to force a specific ChromeDriver version, or `uc.Chrome(use_subprocess=True)` for better auto-handling.

affects: All

gotchaWhile `ChromeOptions` allow customization, sticking to default settings is generally recommended. Overly customizing options can introduce unique browser fingerprints that anti-bot systems might detect, reducing the effectiveness of `undetected-chromedriver`.

fix

Use `ChromeOptions` sparingly. Only add arguments or preferences if absolutely necessary, and be aware that they might increase detectability. Test thoroughly with and without custom options.

affects: All

gotchaThe initial run of `undetected-chromedriver` will automatically download and patch the necessary `chromedriver` binary. This process can take 10-30 seconds, leading to a delayed startup for the first session.

fix

Account for this initial delay in your automation scripts, especially for time-sensitive operations. Subsequent runs will be faster due to caching.

affects: All

Upgrade

Version history

3.5.5latest on PyPI · released Feb 17, 2024

Audit

Dependencies

pythonrequiredRequired Python version. While >=3.6 is supported, 3.10+ is recommended by some documentation.

seleniumrequiredCore WebDriver functionality. Automatically installed.

requestsrequiredHTTP library for downloading ChromeDriver. Automatically installed.

websocketsrequiredWebSocket support for CDP communication. Automatically installed.

packagingrequiredVersion parsing utilities. Automatically installed.

Agent activity

83 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ultrafunkamsterdam/undetected-chromedriver ↗

packagehttps://pypi.org/project/undetected-chromedriver/ ↗