Automating browsers to scrape or test websites is routine for many developers, but sophisticated anti-bot services have made it increasingly tricky. These services detect automation by identifying telltale signs in the browser driver, blocking or throttling traffic. undetected-chromedriver tackles this problem head-on by patching Selenium’s Chromedriver to better mimic human browsing behavior and evade detection.
What undetected-chromedriver does and how it works
undetected-chromedriver is a Python library that modifies the standard Selenium Chromedriver to bypass anti-bot detection systems such as Distill Network, Imperva, and DataDome. It works by automatically downloading the appropriate driver binary for your installed Chrome version and applying patches to mask the automated nature of the driver.
The library supports not only stable Chrome versions but also beta releases and other Chromium-based browsers like Brave, with some configuration. This flexibility is valuable since many anti-bot measures look for signatures specific to the WebDriver or standard Chrome builds.
Under the hood, it patches the Chromedriver executable itself, altering behaviors and fingerprints that anti-bot systems look for. This includes removing or modifying JavaScript variables and WebDriver attributes that reveal automation. The package also enables advanced features like setting custom user profiles for persistent browser state and listening to Chrome DevTools Protocol (CDP) events for network inspection.
The core stack is Python leveraging Selenium for browser automation. The package wraps Selenium’s API, so the developer experience remains familiar while adding stealth capabilities.
Technical strengths and tradeoffs of the patching approach
The standout technical aspect of undetected-chromedriver is its direct patching of the Chromedriver binary to evade detection. This is more involved than typical Selenium usage, which relies on unmodified drivers. By altering the executable, the library hides WebDriver signatures that anti-bot services scan for.
This approach requires deep knowledge of Chrome’s internals and the WebDriver protocol. It must keep pace with frequent browser and driver updates, which can break patches. The repo actively maintains compatibility with current Chrome beta versions, signaling continuous effort to stay ahead.
The codebase is surprisingly clean for a project doing binary patching—most complexity is encapsulated in the patching logic and driver management. It offers both simple usage patterns out of the box and advanced options for custom profiles and CDP event listening.
Tradeoffs include:
- Maintenance burden: Patching is fragile and needs updates for new Chrome versions.
- Limited stealth: It masks WebDriver detection but does not anonymize IP addresses or hide other network-level signals.
- Browser support: Primarily Chrome and Chromium derivatives. Other browsers need separate tooling.
The library does not attempt to defeat CAPTCHAs or IP-based blocking; it focuses purely on the driver fingerprint layer. This focus keeps it lightweight but means additional measures are required for full stealth in scraping.
Quick start with undetected-chromedriver
Installation is straightforward via pip:
pip install undetected-chromedriver
For those wanting the latest development version:
pip install git+https://www.github.com/ultrafunkamsterdam/undetected-chromedriver@master
A minimal usage example in Python looks like this:
import undetected_chromedriver as uc
# Create a patched Chrome driver instance
driver = uc.Chrome()
# Navigate to a page
driver.get('https://example.com')
# Interact as usual with Selenium
print(driver.title)
driver.quit()
This simple snippet uses the patched driver transparently, so existing Selenium scripts can adapt with minimal changes.
Verdict: who should use undetected-chromedriver?
undetected-chromedriver is a practical tool for developers and researchers who need to automate Chromium-based browsers in environments guarded by sophisticated anti-bot systems. It shines when you want to maintain browser automation with Selenium but need to bypass driver fingerprinting.
The tradeoff is ongoing maintenance: the project must keep up with Chrome and driver updates, which can break patches. It also does not cover all stealth aspects—IP anonymization and CAPTCHA solving are outside its scope.
If your projects involve scraping or testing behind anti-bot defenses and you’re comfortable with Python and Selenium, this library can save significant effort. For full stealth setups, it should be combined with proxy rotation and CAPTCHA solutions.
Overall, undetected-chromedriver is a solid choice when you need a patched Selenium driver to blend in better with human browsers, with a clear focus and well-maintained codebase.
Related Articles
- Browser Harness: a self-healing LLM agent for browser automation via Chrome DevTools — Browser Harness enables LLMs to automate browsers by dynamically generating helper functions using the Chrome DevTools P
- PinchTab: Token-efficient Chrome automation for AI agents with Go — PinchTab is a Go HTTP server enabling AI agents to control Chrome instances efficiently by extracting structured text, c
- Syncthing: secure, decentralized continuous file synchronization in Go — Syncthing is an open-source Go tool for continuous, secure, decentralized file synchronization across devices, emphasizi
- Mercury Agent: A TypeScript AI assistant with persistent “Second Brain” memory and permission-hardened safety — Mercury Agent is a TypeScript AI assistant with a persistent SQLite-based memory system, permission-hardened tools, and
- Hugging Face Transformers: a unified API for state-of-the-art AI models across modalities — Hugging Face Transformers offers a unified Python API to access over 1 million pretrained AI models for text, vision, an
→ GitHub Repo: ultrafunkamsterdam/undetected-chromedriver ⭐ 12,564 · Python