undetected-chromedriver — Selenium ChromeDriver That Passes Bot Detection

Introduction

undetected-chromedriver is a drop-in replacement for selenium.webdriver.Chrome that patches the ChromeDriver binary at runtime to avoid detection by anti-bot services. It handles flag removal, navigator property masking, and runtime patching automatically.

What undetected-chromedriver Does

• Patches ChromeDriver to remove automation-indicating flags and properties
• Bypasses Cloudflare, Distil/Imperva, DataDome, and similar bot mitigation
• Auto-downloads the correct ChromeDriver version for your installed Chrome
• Provides the same Selenium WebDriver API with no code changes needed
• Supports headless mode, custom profiles, and proxy configuration

Architecture Overview

On initialization the library downloads the matching ChromeDriver binary, patches specific bytes that anti-bot scripts detect, and launches Chrome with a curated set of flags that suppress automation fingerprints. The navigator.webdriver property is overridden via CDP commands before any page JavaScript executes.

Self-Hosting & Configuration

• Install via pip; requires Google Chrome installed on the system
• Pass Chrome options through ChromeOptions just like standard Selenium
• Set headless mode with options.add_argument('--headless=new')
• Configure proxies via options or wire protocol
• Use version_main parameter to pin a specific Chrome major version

Key Features

• Zero-config setup: works out of the box for most anti-bot systems
• Automatic ChromeDriver version management and binary patching
• Full compatibility with existing Selenium scripts and page objects
• Context manager support for automatic cleanup
• Works on Linux, macOS, and Windows

Comparison with Similar Tools

• Selenium — Standard WebDriver; detected by most anti-bot services
• Playwright Stealth — Playwright-based; undetected-chromedriver stays in the Selenium ecosystem
• Puppeteer Extra Stealth — Node.js only; this library is Python-native
• DrissionPage — Alternative Python automation; undetected-chromedriver keeps full Selenium API compatibility
• Botasaurus — Higher-level scraping framework; this is a low-level driver drop-in

FAQ

Q: Is this legal to use? A: The library is a testing and research tool. Ensure your use case complies with the target website's terms of service.

Q: Does it work with headless Chrome? A: Yes. Use the new headless mode (--headless=new) for best detection avoidance.

Q: Why does it still get blocked sometimes? A: Some services use behavioral analysis beyond driver fingerprinting. Adding human-like delays and mouse movements can help.

Q: Can I use it with Selenium Grid? A: The patching happens on the local binary, so remote Grid setups require patching the remote ChromeDriver separately.

Sources

• https://github.com/ultrafunkamsterdam/undetected-chromedriver
• https://pypi.org/project/undetected-chromedriver/