Undetected ChromeDriver

3.5.5 · active · verified Sun Apr 12

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.

Warnings

breaking Version 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.
gotcha While 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.
gotcha This 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.
gotcha A 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.
gotcha While `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.
gotcha The 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.

Install

pip install undetected-chromedriver Install via pip

Imports

Chrome
```
import undetected_chromedriver as uc
driver = uc.Chrome()
```
`undetected_chromedriver.v2` was an older beta import path and has since been aliased or removed. The direct import `import undetected_chromedriver as uc` is the current and recommended approach.

Quickstart

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.")

view raw JSON →