undetected_chromedriver: Guide to Avoid Detection Online

TL;DR

The undetected_chromedriver library patches ChromeDriver so you can replace webdriver.Chrome() with uc.Chrome() – the rest of your Selenium code stays the same.

• Your IP address is not masked. Pair with residential proxies for protected sites
• Randomized delays, varied viewports, and mouse movements reduce pattern-based detection beyond what the browser patches cover
• Chrome DevTools Protocol and behavioral detection are not patched. If your target uses advanced Cloudflare or DataDome, consider Nodriver, SeleniumBase UC Mode, or Camoufox as alternatives

What is undetected_chromedriver and how does it work

The undetected_chromedriver library is an open-source Python package built on top of Selenium. It automatically downloads, patches, and launches a ChromeDriver binary with modifications that reduce detection by anti-bot services.

How anti-bot systems detect standard Selenium

The navigator.webdriver property returns true in automated Chrome sessions. Anti-bot scripts typically read this property on page load and may flag the session.

Chrome DevTools Protocol (CDP) flags appear when ChromeDriver connects to Chrome. Services like Cloudflare and DataDome detect the Runtime.Enable CDP call, which automation libraries trigger during initialization.

ChromeDriver injects cdc_ prefixed variables into the browser's window scope (for example, cdc_adoQpoasnfa76pfcZLmcfl_Array). Many anti-bot scripts scan for variable names containing cdc to identify automated sessions.

Browser fingerprint gaps can also trigger detection. Automated Chrome sessions may report unusual screen dimensions, missing GPU renderer info, or inconsistent timezone/language settings compared to the IP address location.

Behavioral analysis adds another detection layer. Modern anti-bot systems analyze mouse movement patterns, click timing, scroll speed, and navigation flow. Cloudflare deploys machine learning (ML) models trained on each website's real visitor behavior. Our guide on anti-bot systems covers each detection method in more detail.

What undetected_chromedriver patches

The library applies several patches to the ChromeDriver binary before launching Chrome.

It renames and removes the cdc_ prefixed strings inside the ChromeDriver binary so the injected window variables no longer match known patterns. Anti-bot scripts that scan for cdc in variable names should find no matches after patching.

It modifies the ChromeDriver binary to remove automation indicators from Chrome's launch flags. The --enable-automation flag and the AutomationControlled feature flag are both stripped before Chrome starts.

It sets a standard user agent string and manages browser profile settings to resemble a regular browsing session. And it auto-downloads the correct ChromeDriver version for your installed Chrome, so you avoid manual version matching.

These patches cover API-level and binary-level detection signals. CDP protocol detection and behavioral analysis require different approaches – covered in the limitations section.

Set up Python and install undetected_chromedriver

Verify these requirements, then install.

System requirements

• Python 3.8 to 3.11 – the PyPI release (v3.5.5) depends on distutils, which Python removed in version 3.12. If you run Python 3.12 or higher, install from the GitHub master branch instead (see below)
• Google Chrome browser – install the latest stable version
• Operating system – Windows, macOS, or Linux all work. Linux servers require additional dependencies for headless Chrome (xvfb, libgconf, libnss3)

No manual ChromeDriver download is needed. The library automates the download and patching.

Set up a virtual environment

Create a virtual environment:

python -m venv scraper_env

python -m venv scraper_env

Activate the environment based on your operating system:

# macOS / Linux
source scraper_env/bin/activate

# Windows
scraper_env\Scripts\activate

# macOS / Linux
source scraper_env/bin/activate

# Windows
scraper_env\Scripts\activate

Install the package

Check your Python version first – the install command depends on it:

python --version

python --version

Python 3.8-3.11 – install from PyPI:

pip install undetected-chromedriver

pip install undetected-chromedriver

Python 3.12 or higher – the PyPI release fails with ModuleNotFoundError: No module named 'distutils'. Install from the GitHub master branch instead:

pip install git+https://github.com/ultrafunkamsterdam/undetected-chromedriver@master

pip install git+https://github.com/ultrafunkamsterdam/undetected-chromedriver@master

Both commands install Selenium as a dependency.

Verify the installation:

pip show undetected-chromedriver

pip show undetected-chromedriver

Expected output:

Name: undetected-chromedriver
Version: 3.5.5
Requires: requests, selenium, websockets

Name: undetected-chromedriver
Version: 3.5.5
Requires: requests, selenium, websockets

Organize your scraper files

Organize your scraping code into separate files for maintainability:

my_scraper/
├── scraper.py        # Main scraping logic
├── config.py         # Proxy credentials, target URLs
├── .env              # API keys (add to .gitignore)
└── output/           # Scraped data exports

my_scraper/
├── scraper.py        # Main scraping logic
├── config.py         # Proxy credentials, target URLs
├── .env              # API keys (add to .gitignore)
└── output/           # Scraped data exports

For Selenium scraping fundamentals, see the guide on web scraping with Selenium and Python.

Verify the installation against a real anti-bot test

With the environment ready, verify against an actual detection test. This script visits a headless Chrome detection test page and checks whether undetected_chromedriver passes each signal:

import undetected_chromedriver as uc
import time

with uc.Chrome() as driver:
    driver.get(
        "https://intoli.com/blog/not-possible-to-block-chrome-headless"
        "/chrome-headless-test.html"
    )
    time.sleep(3)

    # Extract test results from the page's HTML table
    results = driver.execute_script("""
        var rows = document.querySelectorAll('tr');
        var data = [];
        rows.forEach(function(row) {
            var cells = row.querySelectorAll('td');
            if (cells.length >= 2) {
                data.push(
                    cells[0].textContent.trim() + ': '
                    + cells[1].textContent.trim()
                );
            }
        });
        return data;
    """)

    for r in results:
        print(r)

import undetected_chromedriver as uc
import time

with uc.Chrome() as driver:
    driver.get(
        "https://intoli.com/blog/not-possible-to-block-chrome-headless"
        "/chrome-headless-test.html"
    )
    time.sleep(3)

    # Extract test results from the page's HTML table
    results = driver.execute_script("""
        var rows = document.querySelectorAll('tr');
        var data = [];
        rows.forEach(function(row) {
            var cells = row.querySelectorAll('td');
            if (cells.length >= 2) {
                data.push(
                    cells[0].textContent.trim() + ': '
                    + cells[1].textContent.trim()
                );
            }
        });
        return data;
    """)

    for r in results:
        print(r)

Expected output:

User Agent (Old): Mozilla/5.0 ... Chrome/XXX.0.0.0 ... [passed]
WebDriver (New): missing (passed)
Chrome (New): present (passed)
Permissions (New): prompt
Plugins Length (Old): 5
Languages (Old): en-GB,en-US,en

User Agent (Old): Mozilla/5.0 ... Chrome/XXX.0.0.0 ... [passed]
WebDriver (New): missing (passed)
Chrome (New): present (passed)
Permissions (New): prompt
Plugins Length (Old): 5
Languages (Old): en-GB,en-US,en

Most lines should show "passed" or a non-suspicious value. WebDriver: missing (passed) indicates the library patched navigator.webdriver to return undefined instead of true. Plugins Length: 5 indicates Chrome is reporting browser plugins (the exact count depends on your Chrome installation).

If you see a SessionNotCreatedException, your Chrome version and ChromeDriver version don't match – see the troubleshooting section below.

The fingerprint test above verifies browser properties. For a real-world Cloudflare bypass test with data extraction, see the combined example in the proxy section – it scrapes Trustpilot (a protected review site) through a residential proxy.

Build your first undetected scraper

Now use it for actual data extraction. Books to Scrape (https://books.toscrape.com) is a scraping sandbox. The following code demonstrates CSS selectors, pagination, and JSON export patterns that apply to any target site.

Initialize the browser

The uc.Chrome() constructor works identically to Selenium's webdriver.Chrome() after initialization:

import undetected_chromedriver as uc

driver = uc.Chrome()
driver.get("https://books.toscrape.com")
print(f"Loaded: {driver.title}")

import undetected_chromedriver as uc

driver = uc.Chrome()
driver.get("https://books.toscrape.com")
print(f"Loaded: {driver.title}")

Expected output:

Loaded: All products | Books to Scrape - Sandbox

Loaded: All products | Books to Scrape - Sandbox

You use the same Selenium API (driver.get(), find_element(), find_elements()) after initialization.

Extract data with CSS selectors and XPath

WebDriverWait waits for elements to load before extracting – required for any page with dynamic content:

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
import json
import os

results = []

with uc.Chrome() as driver:
    driver.get("https://books.toscrape.com")

    # Wait for product containers to load (max 10 seconds)
    WebDriverWait(driver, 10).until(
        EC.presence_of_element_located(
            (By.CSS_SELECTOR, "article.product_pod")
        )
    )

    books = driver.find_elements(By.CSS_SELECTOR, "article.product_pod")

    for book in books:
        title = book.find_element(
            By.CSS_SELECTOR, "h3 a"
        ).get_attribute("title")
        price = book.find_element(
            By.CSS_SELECTOR, ".price_color"
        ).text
        # Rating is encoded in CSS class: "star-rating Three" → "Three"
        rating = book.find_element(
            By.CSS_SELECTOR, "p.star-rating"
        ).get_attribute("class")
        rating = rating.replace("star-rating ", "")

        results.append({
            "title": title,
            "price": price,
            "rating": rating
        })

# Export to JSON
os.makedirs("output", exist_ok=True)
with open("output/books.json", "w") as f:
    json.dump(results, f, indent=2)

print(f"Scraped {len(results)} books")
print(json.dumps(results[0], indent=2))

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
import json
import os

results = []

with uc.Chrome() as driver:
    driver.get("https://books.toscrape.com")

    # Wait for product containers to load (max 10 seconds)
    WebDriverWait(driver, 10).until(
        EC.presence_of_element_located(
            (By.CSS_SELECTOR, "article.product_pod")
        )
    )

    books = driver.find_elements(By.CSS_SELECTOR, "article.product_pod")

    for book in books:
        title = book.find_element(
            By.CSS_SELECTOR, "h3 a"
        ).get_attribute("title")
        price = book.find_element(
            By.CSS_SELECTOR, ".price_color"
        ).text
        # Rating is encoded in CSS class: "star-rating Three" → "Three"
        rating = book.find_element(
            By.CSS_SELECTOR, "p.star-rating"
        ).get_attribute("class")
        rating = rating.replace("star-rating ", "")

        results.append({
            "title": title,
            "price": price,
            "rating": rating
        })

# Export to JSON
os.makedirs("output", exist_ok=True)
with open("output/books.json", "w") as f:
    json.dump(results, f, indent=2)

print(f"Scraped {len(results)} books")
print(json.dumps(results[0], indent=2))

Expected output:

Scraped 20 books
{
  "title": "A Light in the Attic",
  "price": "£51.77",
  "rating": "Three"
}

Scraped 20 books
{
  "title": "A Light in the Attic",
  "price": "£51.77",
  "rating": "Three"
}

Handle pagination

Most scraping tasks require collecting data across multiple pages. Add a loop that follows the "next" button:

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
import json
import time
import random
import os

all_books = []
max_pages = 3  # Limit for this example

with uc.Chrome() as driver:
    page = 1
    while page <= max_pages:
        url = f"https://books.toscrape.com/catalogue/page-{page}.html"
        driver.get(url)

        WebDriverWait(driver, 10).until(
            EC.presence_of_element_located(
                (By.CSS_SELECTOR, "article.product_pod")
            )
        )

        books = driver.find_elements(
            By.CSS_SELECTOR, "article.product_pod"
        )
        for book in books:
            title = book.find_element(
                By.CSS_SELECTOR, "h3 a"
            ).get_attribute("title")
            price = book.find_element(
                By.CSS_SELECTOR, ".price_color"
            ).text

            all_books.append({"title": title, "price": price})

        print(f"Page {page}: scraped {len(books)} books")
        page += 1
        # Randomized delay between page loads
        time.sleep(random.uniform(2, 5))

os.makedirs("output", exist_ok=True)
with open("output/books_multi_page.json", "w") as f:
    json.dump(all_books, f, indent=2)

print(f"Total: {len(all_books)} books across {max_pages} pages")

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
import json
import time
import random
import os

all_books = []
max_pages = 3  # Limit for this example

with uc.Chrome() as driver:
    page = 1
    while page <= max_pages:
        url = f"https://books.toscrape.com/catalogue/page-{page}.html"
        driver.get(url)

        WebDriverWait(driver, 10).until(
            EC.presence_of_element_located(
                (By.CSS_SELECTOR, "article.product_pod")
            )
        )

        books = driver.find_elements(
            By.CSS_SELECTOR, "article.product_pod"
        )
        for book in books:
            title = book.find_element(
                By.CSS_SELECTOR, "h3 a"
            ).get_attribute("title")
            price = book.find_element(
                By.CSS_SELECTOR, ".price_color"
            ).text

            all_books.append({"title": title, "price": price})

        print(f"Page {page}: scraped {len(books)} books")
        page += 1
        # Randomized delay between page loads
        time.sleep(random.uniform(2, 5))

os.makedirs("output", exist_ok=True)
with open("output/books_multi_page.json", "w") as f:
    json.dump(all_books, f, indent=2)

print(f"Total: {len(all_books)} books across {max_pages} pages")

Expected output:

Page 1: scraped 20 books
Page 2: scraped 20 books
Page 3: scraped 20 books
Total: 60 books across 3 pages

Page 1: scraped 20 books
Page 2: scraped 20 books
Page 3: scraped 20 books
Total: 60 books across 3 pages

The extraction and pagination examples above use with uc.Chrome() as driver: – this ensures Chrome closes even on errors, preventing orphaned processes.

For CSS vs XPath comparison, see how to choose the right selector.

These extraction patterns work on any site. For protected targets, the next sections cover proxy integration and behavioral techniques that reduce block rates.

Advanced configuration and customization

Targeting specific Chrome versions, configuring headless mode, and customizing browser options gives you more control when the defaults aren't enough.

Target a specific Chrome version

If your production environment runs a specific Chrome version, pin undetected_chromedriver to match. This reduces the risk of breakage when Chrome auto-updates:

import undetected_chromedriver as uc

driver = uc.Chrome(version_main=147)
driver.get("https://abrahamjuliot.github.io/creepjs/")
print(f"Title: {driver.title}")
driver.quit()

import undetected_chromedriver as uc

driver = uc.Chrome(version_main=147)
driver.get("https://abrahamjuliot.github.io/creepjs/")
print(f"Title: {driver.title}")
driver.quit()

Expected output:

Title: CreepJS

Title: CreepJS

Find your installed Chrome version at chrome://version in the address bar, or run google-chrome --version on Linux. Version pinning is useful when testing compatibility before upgrading Chrome across your scraping infrastructure.

Customize Chrome options

Pass a uc.ChromeOptions() object to configure the browser window, language, GPU rendering, and other flags:

import undetected_chromedriver as uc

options = uc.ChromeOptions()
options.add_argument("--window-size=1920,1080")
options.add_argument("--lang=en-US")
options.add_argument("--disable-gpu")

driver = uc.Chrome(options=options)
driver.get("https://books.toscrape.com")
print(f"Window size: {driver.get_window_size()}")
driver.quit()

import undetected_chromedriver as uc

options = uc.ChromeOptions()
options.add_argument("--window-size=1920,1080")
options.add_argument("--lang=en-US")
options.add_argument("--disable-gpu")

driver = uc.Chrome(options=options)
driver.get("https://books.toscrape.com")
print(f"Window size: {driver.get_window_size()}")
driver.quit()

Expected output (exact values depend on your display resolution and OS):

Window size: {'width': 1920, 'height': 1080}

Window size: {'width': 1920, 'height': 1080}

On macOS with Retina displays, the OS may constrain the window to fit the screen, returning smaller values like {'width': 1470, 'height': 847}.

Useful arguments for scraping:

• --window-size=1920,1080 – sets a realistic desktop viewport
• --lang=en-US – matches your proxy's geographic location
• --disable-notifications – suppresses browser notification popups
• --disable-popup-blocking – prevents popup-related errors

Specify a custom browser executable

If you have multiple Chrome installations (stable, beta, canary), point undetected_chromedriver to a specific binary:

import undetected_chromedriver as uc

# macOS example path
driver = uc.Chrome(
    browser_executable_path=(
        "/Applications/Google Chrome Beta.app"
        "/Contents/MacOS/Google Chrome Beta"
    )
)
driver.get("https://books.toscrape.com")
print(f"Title: {driver.title}")
driver.quit()

import undetected_chromedriver as uc

# macOS example path
driver = uc.Chrome(
    browser_executable_path=(
        "/Applications/Google Chrome Beta.app"
        "/Contents/MacOS/Google Chrome Beta"
    )
)
driver.get("https://books.toscrape.com")
print(f"Title: {driver.title}")
driver.quit()

On Linux, the path is typically /usr/bin/google-chrome-beta or /usr/bin/google-chrome-unstable for Canary builds.

Configure headless mode

Headless mode runs Chrome without a visible window, which reduces resource usage on servers. But headless mode increases detection risk because some anti-bot systems check for headless-specific browser properties:

import undetected_chromedriver as uc

driver = uc.Chrome(headless=True)
driver.get("https://books.toscrape.com")
print(f"Title: {driver.title}")
driver.save_screenshot("headless_test.png")
driver.quit()

import undetected_chromedriver as uc

driver = uc.Chrome(headless=True)
driver.get("https://books.toscrape.com")
print(f"Title: {driver.title}")
driver.save_screenshot("headless_test.png")
driver.quit()

Expected output:

Title: All products | Books to Scrape - Sandbox

Title: All products | Books to Scrape - Sandbox

The library patches headless mode but the library's maintainer marks it "unsupported". It may work for sites with moderate protection, but sites running advanced Cloudflare or DataDome configurations can still detect the headless environment. Use headed mode (the default) when stealth is the priority, and headless mode when running on servers where a display isn't available.

On Linux servers, run your script with xvfb-run python scraper.py to create a virtual display for headed Chrome without a physical monitor. This approach can reduce detection risk while maintaining server compatibility.

Persist sessions with custom user data directories

By default, undetected_chromedriver creates a fresh profile each run. To persist cookies, login sessions, and localStorage across runs, specify a user data directory:

import undetected_chromedriver as uc

options = uc.ChromeOptions()
options.add_argument("--user-data-dir=/tmp/uc_profile")

driver = uc.Chrome(options=options)
driver.get("https://books.toscrape.com")
# Cookies and session data persist in /tmp/uc_profile
print("Session data saved to /tmp/uc_profile")
driver.quit()

import undetected_chromedriver as uc

options = uc.ChromeOptions()
options.add_argument("--user-data-dir=/tmp/uc_profile")

driver = uc.Chrome(options=options)
driver.get("https://books.toscrape.com")
# Cookies and session data persist in /tmp/uc_profile
print("Session data saved to /tmp/uc_profile")
driver.quit()

Reusing the same profile across many scraping runs may accumulate tracking cookies that increase detection risk. Clear the profile directory periodically for clean sessions. On Windows, use a compatible path like C:\temp\uc_profile instead of /tmp/.

Use extended API methods

The library adds 2 methods beyond the standard Selenium API. Both are available on any element returned by find_element() when using uc.Chrome():

• element.click_safe() – briefly disconnects the driver before clicking to avoid detection, then reconnects automatically. Useful when standard .click() triggers anti-bot checks or fails on overlapping elements
• parent.children() – returns child elements without writing a separate CSS or XPath selector

Both methods are UC-specific – they don't exist in standard Selenium.

Reduce detection with proxies, user agents, and behavioral techniques

The undetected_chromedriver library patches browser-level signals. But it doesn't hide your IP address, rotate user agents, or add human-like behavior. For sites with moderate to strong protection, you need all 3 layers working together.

Why proxies are required for protected sites

The library's README states clearly: "THIS PACKAGE DOES NOT hide your IP address". Many anti-bot services maintain blocklists of known datacenter IP ranges. Even residential IPs with poor reputation scores can trigger blocks on some sites. Rate limiting and IP-based blocking typically remain active regardless of browser fingerprint quality.

At Decodo, we offer residential proxies with a high success rate (99.86%), automatic rotation, a rapid response time (<0.6s), and extensive geo-targeting options (195+ worldwide locations). Here's how easy it is to get a plan and your proxy credentials:

1. Create your account. Sign up at the Decodo dashboard.
2. Select a proxy plan. Choose a subscription that suits your needs or start with a 3-day free trial.
3. Configure proxy settings. Set up your proxies with rotating sessions for maximum effectiveness.
4. Select locations. Target specific regions based on your data requirements or keep it set to Random.
5. Copy your credentials. You'll need your proxy username, password, and server endpoint to integrate into your scraping script.

Configure a proxy with undetected_chromedriver

Pass the proxy address through Chrome's --proxy-server argument:

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By

options = uc.ChromeOptions()
options.add_argument(
    "--proxy-server=http://PROXY_IP:PROXY_PORT"
)

driver = uc.Chrome(options=options)
driver.set_page_load_timeout(30)
driver.get("https://httpbin.org/ip")
print(driver.find_element(By.TAG_NAME, "pre").text)
driver.quit()

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By

options = uc.ChromeOptions()
options.add_argument(
    "--proxy-server=http://PROXY_IP:PROXY_PORT"
)

driver = uc.Chrome(options=options)
driver.set_page_load_timeout(30)
driver.get("https://httpbin.org/ip")
print(driver.find_element(By.TAG_NAME, "pre").text)
driver.quit()

Expected output (with proxy active):

{
  "origin": "171.49.158.263"
}

{
  "origin": "171.49.158.263"
}

Replace PROXY_IP:PROXY_PORT with your actual proxy address. The --proxy-server flag works for IP-allowlisted proxies but doesn't support username:password authentication directly. Most proxy providers use authenticated access, so the next section covers that.

Use authenticated Decodo proxies with a Chrome extension

Chrome's --proxy-server flag doesn't accept a username:password@host:port format. The authentication limitation is a frequent obstacle developers encounter with proxy integration. One solution is a temporary Chrome extension that intercepts authentication requests and injects your credentials automatically. This approach works with any proxy provider that uses username:password auth:

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
import zipfile
import json
import os
import tempfile
import shutil

def create_proxy_auth_extension(
    proxy_host, proxy_port, proxy_user, proxy_pass
):
    """Create a Chrome extension for proxy authentication."""
    manifest_json = """{
        "version": "1.0.0",
        "manifest_version": 2,
        "name": "Proxy Auth",
        "permissions": [
            "proxy", "tabs", "unlimitedStorage",
            "storage", "<all_urls>",
            "webRequest", "webRequestBlocking"
        ],
        "background": { "scripts": ["background.js"] }
    }"""

    # json.dumps escapes quotes, backslashes, and special
    # characters so credentials don't break the JavaScript
    background_js = """var config = {
        mode: "fixed_servers",
        rules: {
            singleProxy: {
                scheme: "http",
                host: %s,
                port: %s
            },
            bypassList: ["localhost"]
        }
    };
    chrome.proxy.settings.set(
        {value: config, scope: "regular"},
        function() {}
    );
    function callbackFn(details) {
        return {
            authCredentials: {
                username: %s,
                password: %s
            }
        };
    }
    chrome.webRequest.onAuthRequired.addListener(
        callbackFn,
        {urls: ["<all_urls>"]},
        ["blocking"]
    );""" % (
        json.dumps(proxy_host),
        json.dumps(int(proxy_port)),
        json.dumps(proxy_user),
        json.dumps(proxy_pass),
    )

    ext_dir = tempfile.mkdtemp()
    ext_path = os.path.join(ext_dir, "proxy_auth.zip")

    with zipfile.ZipFile(ext_path, "w") as zp:
        zp.writestr("manifest.json", manifest_json)
        zp.writestr("background.js", background_js)

    return ext_path, ext_dir

# Replace with your Decodo credentials from the dashboard
# (requires a Decodo account).
# Use your raw proxy username here, NOT the "user-" prefixed
# format. The "user-" prefix is only for curl and endpoint
# parameter strings.
proxy_ext, ext_dir = create_proxy_auth_extension(
    proxy_host="gate.decodo.com",
    proxy_port="7000",
    proxy_user="YOUR_USERNAME",
    proxy_pass="YOUR_PASSWORD"
)

options = uc.ChromeOptions()
options.add_extension(proxy_ext)

driver = uc.Chrome(options=options)
driver.set_page_load_timeout(30)
try:
    driver.get("https://ip.decodo.com/json")
    print(driver.find_element(By.TAG_NAME, "pre").text[:200])
finally:
    driver.quit()
    shutil.rmtree(ext_dir)

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
import zipfile
import json
import os
import tempfile
import shutil

def create_proxy_auth_extension(
    proxy_host, proxy_port, proxy_user, proxy_pass
):
    """Create a Chrome extension for proxy authentication."""
    manifest_json = """{
        "version": "1.0.0",
        "manifest_version": 2,
        "name": "Proxy Auth",
        "permissions": [
            "proxy", "tabs", "unlimitedStorage",
            "storage", "<all_urls>",
            "webRequest", "webRequestBlocking"
        ],
        "background": { "scripts": ["background.js"] }
    }"""

    # json.dumps escapes quotes, backslashes, and special
    # characters so credentials don't break the JavaScript
    background_js = """var config = {
        mode: "fixed_servers",
        rules: {
            singleProxy: {
                scheme: "http",
                host: %s,
                port: %s
            },
            bypassList: ["localhost"]
        }
    };
    chrome.proxy.settings.set(
        {value: config, scope: "regular"},
        function() {}
    );
    function callbackFn(details) {
        return {
            authCredentials: {
                username: %s,
                password: %s
            }
        };
    }
    chrome.webRequest.onAuthRequired.addListener(
        callbackFn,
        {urls: ["<all_urls>"]},
        ["blocking"]
    );""" % (
        json.dumps(proxy_host),
        json.dumps(int(proxy_port)),
        json.dumps(proxy_user),
        json.dumps(proxy_pass),
    )

    ext_dir = tempfile.mkdtemp()
    ext_path = os.path.join(ext_dir, "proxy_auth.zip")

    with zipfile.ZipFile(ext_path, "w") as zp:
        zp.writestr("manifest.json", manifest_json)
        zp.writestr("background.js", background_js)

    return ext_path, ext_dir

# Replace with your Decodo credentials from the dashboard
# (requires a Decodo account).
# Use your raw proxy username here, NOT the "user-" prefixed
# format. The "user-" prefix is only for curl and endpoint
# parameter strings.
proxy_ext, ext_dir = create_proxy_auth_extension(
    proxy_host="gate.decodo.com",
    proxy_port="7000",
    proxy_user="YOUR_USERNAME",
    proxy_pass="YOUR_PASSWORD"
)

options = uc.ChromeOptions()
options.add_extension(proxy_ext)

driver = uc.Chrome(options=options)
driver.set_page_load_timeout(30)
try:
    driver.get("https://ip.decodo.com/json")
    print(driver.find_element(By.TAG_NAME, "pre").text[:200])
finally:
    driver.quit()
    shutil.rmtree(ext_dir)

The extension uses Manifest V2, which Chrome has been deprecating since 2024. As of early 2026, MV2 extensions loaded via ChromeDriver still work. If Chrome stops loading the extension in a future version, use IP allowlisting as a fallback.

The code above works with any proxy provider. Decodo residential proxies are one option – see the product page for pricing and account setup.

All requests go through port 7000 on gate.decodo.com. By default, each request is assigned a different IP from the pool. To keep the same IP across multiple requests (a sticky session), add a -session-XXXX parameter to the username string.

Sticky sessions last 10 minutes by default, configurable up to 1,440 minutes with the -sessionduration- parameter. For details, see the sticky session documentation.

Expected output (IP and ISP vary based on the proxy endpoint):

{
    "browser": {
        "name": "Chrome",
        "version": "XXX.0.0.0"
    },
    "ip": "185.xx.xx.xx",
    ...
}

{
    "browser": {
        "name": "Chrome",
        "version": "XXX.0.0.0"
    },
    "ip": "185.xx.xx.xx",
    ...
}

The Chrome version and IP address in the output depend on your installed Chrome and the proxy endpoint.

The session and geo-targeting parameters below use the user- prefix format (for curl and endpoint strings). The Chrome extension code above uses your raw username because it authenticates at a different level.

For sticky sessions, add -session-XXXX to the username (for example, user-YOUR_USERNAME-session-scraper1). For location-specific scraping, append -country-us-city-new_york. Combine both: user-YOUR_USERNAME-country-us-session-scraper1-sessionduration-90.

The password stays unchanged. For the full parameter reference, see the username authentication documentation.

To verify your proxy credentials before integrating, test with curl:

curl -U "user-YOUR_USERNAME:YOUR_PASSWORD" \
    -x "gate.decodo.com:7000" \
    "https://ip.decodo.com/json"

curl -U "user-YOUR_USERNAME:YOUR_PASSWORD" \
    -x "gate.decodo.com:7000" \
    "https://ip.decodo.com/json"

If the proxy is working, the response shows a JSON object with browser, ISP, and location data from the proxy IP, not your real IP.

Combined example: proxy + Cloudflare bypass + data extraction

The previous subsections covered proxy auth and detection bypass separately. This example combines them into one script using the create_proxy_auth_extension function from above:

Copy the create_proxy_auth_extension function from the previous section into your script, then add:

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
import json
import shutil
import time

# ... paste create_proxy_auth_extension function here ...

proxy_ext, ext_dir = create_proxy_auth_extension(
    "gate.decodo.com", "7000",
    "YOUR_USERNAME", "YOUR_PASSWORD"
)
options = uc.ChromeOptions()
options.add_extension(proxy_ext)

driver = uc.Chrome(options=options)
driver.set_page_load_timeout(30)

try:
    # Step 1: Verify proxy is active
    driver.get("https://httpbin.org/ip")
    proxy_ip = json.loads(
        driver.find_element(By.TAG_NAME, "pre").text
    )["origin"]
    print(f"Proxy IP: {proxy_ip}")

    # Step 2: Scrape a protected review page
    driver.get(
        "https://www.trustpilot.com/review/amazon.com"
    )
    time.sleep(6)

    # Extract structured review data
    score = driver.find_elements(
        By.CSS_SELECTOR, "[data-rating-typography]"
    )
    reviews = driver.find_elements(
        By.CSS_SELECTOR,
        "article[data-service-review-card-paper]"
    )

    print(f"Title: {driver.title[:60]}")
    print(f"Rating: {score[0].text if score else 'n/a'}")
    print(f"Reviews on page: {len(reviews)}")

    for review in reviews[:3]:
        paras = review.find_elements(By.CSS_SELECTOR, "p")
        text = paras[0].text[:80] if paras else ""
        print(f"  - {text}")

finally:
    driver.quit()
    shutil.rmtree(ext_dir)

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
import json
import shutil
import time

# ... paste create_proxy_auth_extension function here ...

proxy_ext, ext_dir = create_proxy_auth_extension(
    "gate.decodo.com", "7000",
    "YOUR_USERNAME", "YOUR_PASSWORD"
)
options = uc.ChromeOptions()
options.add_extension(proxy_ext)

driver = uc.Chrome(options=options)
driver.set_page_load_timeout(30)

try:
    # Step 1: Verify proxy is active
    driver.get("https://httpbin.org/ip")
    proxy_ip = json.loads(
        driver.find_element(By.TAG_NAME, "pre").text
    )["origin"]
    print(f"Proxy IP: {proxy_ip}")

    # Step 2: Scrape a protected review page
    driver.get(
        "https://www.trustpilot.com/review/amazon.com"
    )
    time.sleep(6)

    # Extract structured review data
    score = driver.find_elements(
        By.CSS_SELECTOR, "[data-rating-typography]"
    )
    reviews = driver.find_elements(
        By.CSS_SELECTOR,
        "article[data-service-review-card-paper]"
    )

    print(f"Title: {driver.title[:60]}")
    print(f"Rating: {score[0].text if score else 'n/a'}")
    print(f"Reviews on page: {len(reviews)}")

    for review in reviews[:3]:
        paras = review.find_elements(By.CSS_SELECTOR, "p")
        text = paras[0].text[:80] if paras else ""
        print(f"  - {text}")

finally:
    driver.quit()
    shutil.rmtree(ext_dir)

Expected output:

Proxy IP: 185.xx.xx.xx
Title: Amazon Reviews | Read Customer Service Reviews of www.amazon
Rating: 1.7
Reviews on page: 70
  - Always late on deliveries in Statesville, North Carolina...
  - I have two points: 1. You are not allowed to leave negat...
  - Amazon Blink camera system, outside in particular, when i...

Proxy IP: 185.xx.xx.xx
Title: Amazon Reviews | Read Customer Service Reviews of www.amazon
Rating: 1.7
Reviews on page: 70
  - Always late on deliveries in Statesville, North Carolina...
  - I have two points: 1. You are not allowed to leave negat...
  - Amazon Blink camera system, outside in particular, when i...

One browser session, 2 steps: verify the proxy is active, then scrape real review data from a protected page. The same selectors work for any company on Trustpilot – replace amazon.com in the URL with your target.

Rotate user agents

Anti-bot systems compare your user agent string against other browser fingerprint signals. A mismatched user agent (claiming an older Chrome version while your browser reports current features) can trigger detection. Keep user agent strings current and consistent with your Chrome version:

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
import random

user_agents = [
    (
        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
        "AppleWebKit/537.36 (KHTML, like Gecko) "
        "Chrome/147.0.0.0 Safari/537.36"
    ),
    (
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
        "AppleWebKit/537.36 (KHTML, like Gecko) "
        "Chrome/147.0.0.0 Safari/537.36"
    ),
    (
        "Mozilla/5.0 (X11; Linux x86_64) "
        "AppleWebKit/537.36 (KHTML, like Gecko) "
        "Chrome/147.0.0.0 Safari/537.36"
    ),
]

options = uc.ChromeOptions()
selected_ua = random.choice(user_agents)
options.add_argument(f"--user-agent={selected_ua}")

driver = uc.Chrome(options=options)
driver.get("https://httpbin.org/user-agent")
print(driver.find_element(
    By.TAG_NAME, "pre"
).text)
driver.quit()

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
import random

user_agents = [
    (
        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
        "AppleWebKit/537.36 (KHTML, like Gecko) "
        "Chrome/147.0.0.0 Safari/537.36"
    ),
    (
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
        "AppleWebKit/537.36 (KHTML, like Gecko) "
        "Chrome/147.0.0.0 Safari/537.36"
    ),
    (
        "Mozilla/5.0 (X11; Linux x86_64) "
        "AppleWebKit/537.36 (KHTML, like Gecko) "
        "Chrome/147.0.0.0 Safari/537.36"
    ),
]

options = uc.ChromeOptions()
selected_ua = random.choice(user_agents)
options.add_argument(f"--user-agent={selected_ua}")

driver = uc.Chrome(options=options)
driver.get("https://httpbin.org/user-agent")
print(driver.find_element(
    By.TAG_NAME, "pre"
).text)
driver.quit()

Expected output:

{
  "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."
}

{
  "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."
}

Update the Chrome version number in these strings to match your installed Chrome. Find your version at chrome://version or at whatismybrowser.com.

Add behavioral delays and patterns

User agent rotation covers one fingerprint signal. Behavioral patterns are the other major detection layer. Modern anti-bot systems weigh behavioral signals as heavily as technical fingerprints. Fixed delays and linear mouse movements can create detectable patterns. Use randomized timing and vary your interaction patterns:

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
from selenium.webdriver.common.action_chains import ActionChains
import time
import random

driver = uc.Chrome()
driver.get("https://books.toscrape.com")

# Randomized delay between 2 and 6 seconds
time.sleep(random.uniform(2, 6))

# Scroll down in random increments (simulates reading)
for _ in range(random.randint(2, 5)):
    scroll_amount = random.randint(200, 500)
    driver.execute_script(
        f"window.scrollBy(0, {scroll_amount});"
    )
    time.sleep(random.uniform(0.5, 2.0))

# Move mouse to element before clicking
element = driver.find_element(By.CSS_SELECTOR, "article.product_pod a")
ActionChains(driver).move_to_element(element).pause(
    random.uniform(0.3, 1.0)
).click().perform()

time.sleep(random.uniform(1, 3))
print(f"Current URL: {driver.current_url}")
driver.quit()

import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
from selenium.webdriver.common.action_chains import ActionChains
import time
import random

driver = uc.Chrome()
driver.get("https://books.toscrape.com")

# Randomized delay between 2 and 6 seconds
time.sleep(random.uniform(2, 6))

# Scroll down in random increments (simulates reading)
for _ in range(random.randint(2, 5)):
    scroll_amount = random.randint(200, 500)
    driver.execute_script(
        f"window.scrollBy(0, {scroll_amount});"
    )
    time.sleep(random.uniform(0.5, 2.0))

# Move mouse to element before clicking
element = driver.find_element(By.CSS_SELECTOR, "article.product_pod a")
ActionChains(driver).move_to_element(element).pause(
    random.uniform(0.3, 1.0)
).click().perform()

time.sleep(random.uniform(1, 3))
print(f"Current URL: {driver.current_url}")
driver.quit()

The key patterns to vary across sessions:

• Delay ranges – use random.uniform(2, 6) instead of fixed time.sleep(3)
• Viewport sizes – alternate between common resolutions (1920x1080, 1366x768, 1536x864)
• Scroll behavior – vary scroll distance and pause duration
• Session timing – avoid running at the exact same time daily

Manage cookies between sessions

Session behavior also includes cookie handling. For sites that require login or track session state, save and restore cookies:

import undetected_chromedriver as uc
import json
import os

COOKIE_FILE = "cookies.json"

driver = uc.Chrome()
driver.get("https://books.toscrape.com")

# Save cookies after a session
cookies = driver.get_cookies()
with open(COOKIE_FILE, "w") as f:
    json.dump(cookies, f)
print(f"Saved {len(cookies)} cookies")

driver.quit()

# Restore cookies in a new session
driver = uc.Chrome()
driver.get("https://books.toscrape.com")

if os.path.exists(COOKIE_FILE):
    with open(COOKIE_FILE, "r") as f:
        cookies = json.load(f)
    for cookie in cookies:
        try:
            driver.add_cookie(cookie)
        except Exception:
            pass  # Skip cookies that don't match domain
    driver.refresh()
    print(f"Restored {len(cookies)} cookies")

driver.quit()