How to Configure Selenium Stealth to Avoid Detection

selenium-stealth is a Python library that patches the default WebDriver configuration to mask automation fingerprints detected by modern anti-bot systems. It modifies navigator.webdriver, WebGL parameters, and Chrome runtime properties to mimic human browsing behavior. Implementing these adjustments is a foundational step in Advanced Scraping Techniques & Anti-Bot Evasion, enabling your automation scripts to bypass basic heuristic checks without sacrificing execution speed or stability.

Installation & Environment Setup

Before configuring stealth parameters, ensure your environment has compatible dependencies. selenium-stealth operates alongside standard Selenium and requires a matching ChromeDriver version. Selenium 4.6+ includes Selenium Manager, which downloads a matching driver automatically; webdriver-manager remains useful when you need to pin a specific driver version.

pip install selenium selenium-stealth webdriver-manager

Core Stealth Configuration Parameters

The stealth() function accepts multiple boolean flags and string overrides that directly alter browser fingerprinting. Key parameters include languages, vendor, platform, webgl_vendor, renderer, fix_hairline, and run_on_insecure_origins. Align these values with a realistic browser profile to prevent fingerprint mismatches.

Critical: Apply stealth immediately after driver initialization but before navigating to any URL. Patches applied after the first driver.get() call leave the initial request unprotected.

Advanced Fingerprint Masking & Proxy Integration

To scale operations reliably, combine stealth settings with authenticated proxy endpoints. Route traffic through residential or datacenter proxies while maintaining consistent User-Agent strings and locale headers. For complex SPAs that require persistent sessions and dynamic DOM rendering, pair your stealth setup with Mastering Selenium for Dynamic Websites to synchronize header injection with JavaScript execution flows.

Validation & Troubleshooting Detection Flags

Verify your configuration by visiting fingerprinting validation sites like bot.sannysoft.com or amiunique.org. Check that navigator.webdriver === false, that the plugins array is populated, and that chrome.runtime is a valid object. If blocked, temporarily disable headless mode to debug TLS handshake mismatches, verify that proxy geolocation aligns with browser locale, and confirm ChromeDriver matches your installed Chrome version exactly.

Code Examples

Basic Selenium Stealth Initialization

from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.chrome.service import Service
from selenium_stealth import stealth
from webdriver_manager.chrome import ChromeDriverManager

chrome_options = Options()
chrome_options.add_argument("--disable-blink-features=AutomationControlled")
chrome_options.add_argument("--no-sandbox")
chrome_options.add_argument("--disable-dev-shm-usage")

driver = webdriver.Chrome(
    service=Service(ChromeDriverManager().install()),
    options=chrome_options
)

stealth(
    driver,
    languages=["en-US", "en"],
    vendor="Google Inc.",
    platform="Win32",
    webgl_vendor="Intel Inc.",
    renderer="Intel Iris OpenGL Engine",
    fix_hairline=True,
    run_on_insecure_origins=False
)

driver.get("https://bot.sannysoft.com")
print(driver.title)
driver.quit()

Explanation: Initializes a standard ChromeDriver, applies core stealth patches, and validates the configuration against a public fingerprint checker. The --disable-blink-features=AutomationControlled flag provides an additional layer of detection masking at the browser argument level.

Stealth with Proxy & Custom Headers

from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium_stealth import stealth

PROXY = "http://user:pass@proxy-ip:port"

chrome_options = Options()
chrome_options.add_argument(f"--proxy-server={PROXY}")
chrome_options.add_argument("--disable-blink-features=AutomationControlled")
chrome_options.add_experimental_option("excludeSwitches", ["enable-automation"])

driver = webdriver.Chrome(options=chrome_options)

stealth(
    driver,
    languages=["en-US", "en"],
    vendor="Google Inc.",
    platform="Win32",
    webgl_vendor="Intel Inc.",
    renderer="Intel Iris OpenGL Engine",
    fix_hairline=True
)

driver.get("https://httpbin.org/ip")
print(driver.page_source)
driver.quit()

Explanation: Routes stealth-configured traffic through an authenticated proxy while excluding the enable-automation switch. This prevents Chrome from setting the navigator.webdriver flag at the browser level before the Python stealth patches are applied.

Common Mistakes

• Applying stealth patches after calling driver.get(), which leaves the initial request exposed to bot detection.
• Hardcoding outdated User-Agent strings that conflict with the actual Chrome version being automated.
• Running headless mode without --disable-blink-features=AutomationControlled, which leaks automation markers through the navigator.webdriver property.
• Mismatching proxy IP geolocation with browser locale and timezone settings, triggering behavioral anomaly flags.
• Overriding navigator.webdriver manually via execute_script() instead of using the library's native patching, which can cause inconsistent DOM state.

Frequently Asked Questions

Is selenium-stealth better than undetected-chromedriver?selenium-stealth is a lightweight patching library that modifies WebDriver properties on a standard ChromeDriver, offering faster execution and easier maintenance. undetected-chromedriver patches the browser binary itself, which can be more robust against advanced TLS fingerprinting but often suffers from slower startup and compatibility issues with newer Chrome versions.

Does selenium-stealth work in headless mode? Yes, but headless mode requires additional Chrome arguments including --disable-blink-features=AutomationControlled and the modern --headless=new flag. Headless mode inherently leaks rendering differences, so combining stealth patches with proper viewport sizing and WebGL spoofing is necessary.

How often should I update ChromeDriver for stealth configurations? Update ChromeDriver immediately whenever your local or server Chrome browser updates. Version mismatches cause WebDriver session failures and can break stealth patches that rely on specific browser APIs. Use webdriver-manager to automate this synchronization.

Can selenium-stealth bypass Cloudflare Turnstile or reCAPTCHA v3? No. selenium-stealth masks browser fingerprints and reduces heuristic detection, but does not solve cryptographic challenges like Turnstile or reCAPTCHA v3. For those, integrate third-party CAPTCHA-solving APIs, residential proxies with high trust scores, or behavioral automation that more closely mimics human timing.