How to Use Selenium Stealth for Browser Automation

selenium-stealth is a Python package for Selenium automation with Chrome and Chromium. The documented workflow is to install it, create a Chrome WebDriver, call stealth(driver, ...), then navigate. It does not apply to every browser Selenium supports, and changing browser properties cannot guarantee access to a site or hide your network identity.

Use it for authorized browser automation and testing. The package’s statements about detection tests and reCAPTCHA are maintainer claims, not independently established guarantees in the documentation reviewed for this guide.

1. Install the packages

Create and activate a virtual environment, then install Selenium and selenium-stealth:

python -m venv .venv
# macOS or Linux:
source .venv/bin/activate
# Windows PowerShell:
.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install selenium selenium-stealth

The package’s documented installation command is pip install selenium-stealth. Selenium is installed explicitly here so the environment contains both dependencies. For reproducible deployments, pin versions after validating the combination in your own environment, and update pins deliberately.

2. Start Chrome and apply the settings

Current Selenium can use Selenium Manager to locate or obtain a compatible browser driver when you create a WebDriver. You usually do not need to copy a ChromeDriver executable path into the code. The example below follows the documented package call pattern; its fingerprint values are illustrative and should not be copied as claims about your host.

from selenium import webdriver
from selenium_stealth import stealth

options = webdriver.ChromeOptions()
# For a controlled headless run, uncomment:
# options.add_argument("--headless=new")

driver = webdriver.Chrome(options=options)
try:
    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://example.com")
    print(driver.title)
finally:
    driver.quit()

Save as capture.py and run python capture.py. Replace the example URL with a page you are permitted to automate. Call stealth() after creating the driver and before navigating so its configured behavior is in place for the page load. The package README also documents user_agent and run_on_insecure_origins; see the options section below.

3. Understand the documented options

Option	Purpose	Practical note
`user_agent`	Sets the user-agent value used by the package’s configuration.	Use a value consistent with the browser and test environment. A user-agent change does not change the IP address or make other signals consistent.
`languages`	Sets the configured language list.	Use language tags appropriate to the test locale, such as `["en-US", "en"]`.
`vendor`	Sets the configured browser vendor property.	Do not assume an example value is correct for every browser build.
`platform`	Sets the configured platform property.	Match the environment being tested; changing a reported value does not change the operating system.
`webgl_vendor`	Sets the configured WebGL vendor value.	Hardware and graphics stack affect real WebGL behavior; arbitrary values can be inconsistent.
`renderer`	Sets the configured WebGL renderer value.	Choose only when you understand the browser and graphics environment under test.
`fix_hairline`	Enables the package’s hairline correction behavior.	The README’s sample enables it. Disable it if it is inappropriate for your test.
`run_on_insecure_origins`	Controls whether the package behavior is applied on insecure origins.	Use only where required by a controlled test; prefer HTTPS for ordinary automation.

These are the options documented by the package README, not a promise that every combination is realistic or accepted by a site. Keep settings aligned with the actual browser, OS, locale, and graphics environment where possible. Avoid using browser fingerprint changes to bypass access controls.

4. Use Selenium Manager and match ChromeDriver

Selenium’s current Python documentation says Selenium Manager handles browser and driver management for most supported platforms when a driver is created. Manual installation remains available if your environment needs it. For Chrome, Selenium’s guidance says the Chrome and ChromeDriver major versions should match; a mismatch can prevent session startup.

Install a supported Chrome or Chromium build in the execution environment.
Try webdriver.Chrome(options=options) first so Selenium Manager can handle the driver.
If your environment requires a manually managed driver, install the ChromeDriver version compatible with that Chrome major version and configure it using the current Selenium API for your installed version.
When startup fails, inspect the Chrome and ChromeDriver versions before changing stealth settings.

The selenium-stealth README includes an older-looking explicit executable path example. Do not blindly copy that argument into current code: start with Selenium Manager, or consult Selenium’s current documentation if manual service configuration is necessary.

5. Know what selenium-stealth does and does not establish

The package describes itself as making Selenium more stealthy and documents support for Selenium Chrome/Chromium. Its README identifies Puppeteer Extra Stealth as its implementation lineage. Those are the project authors’ descriptions. Selenium itself supports a broader set of browser drivers, including Chrome, Edge, Firefox, Safari, WebKitGTK, and WPEWebKit, but that does not mean selenium-stealth applies to those browsers.

The README says the package passes public bot tests and helps maintain a normal reCAPTCHA v3 score. The reviewed material does not provide an independent benchmark, test protocol, sample size, or dated third-party confirmation. Treat those statements as project claims rather than reliable outcomes. Browser properties are only one part of a request context; network identity and site policy still matter.

undetected-chromedriver is a separate project that describes patching ChromeDriver. Its own README says it does not hide the user’s IP address and notes that data-center IP reputation can affect outcomes. There is not enough evidence here to call either package a universal winner. Choose based on your authorized testing need, compatibility, setup, and maintenance requirements.

6. Run it safely and reliably

Run browser automation in a container or virtual machine when appropriate, especially for jobs involving untrusted pages.
Use a dedicated test account with no sensitive local files or network access.
Keep Chrome and ChromeDriver current and compatible.
Do not expose ChromeDriver or Selenium Server ports to unauthorized remote connections. Protect server ports when using Selenium Server or third-party tooling.
Always close the session with driver.quit(), including when navigation or assertions fail. A try/finally block, as above, helps release the browser process.
Use explicit waits for page conditions in real workflows rather than assuming navigation means every dynamic element is ready.

7. Troubleshoot common errors

Symptom	Likely cause	What to do
`SessionNotCreatedException` or a message about version mismatch	Chrome and ChromeDriver are incompatible, or the selected browser is unavailable.	Check the installed Chrome version and ensure ChromeDriver has the matching major version. Let Selenium Manager resolve it where supported.
Chrome fails to start in a container or headless environment	Browser dependencies, permissions, or environment-specific startup configuration are missing.	Confirm Chrome can start in that environment without selenium-stealth first. Check container dependencies and run the process with suitable permissions; do not run as a highly privileged account unnecessarily.
`ModuleNotFoundError: No module named 'selenium_stealth'`	The package was installed into a different Python environment, or installation failed.	Activate the intended virtual environment and run `python -m pip install selenium-stealth` using the same `python` that runs the script.
`TypeError` for an unsupported `stealth()` argument	The installed package version and example/API expectations differ.	Check the installed version and that version’s package documentation; remove or adapt the unsupported argument rather than guessing.
The browser opens but the site shows a challenge, denial, or different content	Browser settings do not determine access. Site policy, network reputation, authentication, or other signals may matter.	Use the site’s approved API or request access for authorized testing. Do not treat configuration changes as a guarantee or attempt to evade access controls.
The page title or elements are empty immediately after navigation	The page may still be loading or may render content asynchronously.	Wait for a specific expected element or condition with Selenium’s wait tools, and handle timeout as a test result.

8. Performance, reliability, and cost

Each WebDriver session starts a real browser process, so its startup, memory use, and page rendering usually dominate the small Python configuration step. Reuse a session for related pages when test isolation allows it; create separate sessions when cookies, state, or failure containment require isolation. A longer timeout can help slow pages but also increases the time a stalled job occupies a worker, so set timeouts to the workflow’s needs and record failures.

Selenium and selenium-stealth are software dependencies, not a managed screenshot service. Account for the compute and maintenance cost of browser hosts, driver/browser updates, and retries in your own environment. For reliable automation, pin and periodically review dependencies, capture useful error logs, and distinguish browser startup failures from page-load timeouts.

Or skip the browser setup

If your job is simply to get a website screenshot, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns an image or PDF. The API options include full-page capture, device presets, custom waits, and more; see the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write("shot.webp", res);

Cookie banners are accepted and removed before capture, along with known newsletter popups and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, timeouts, and failed loads are not billed, and cache hits cost nothing. Response headers report the page verdict and billing status. An MCP server gives AI agents screenshot, page-info, and PDF tools. The free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, no card required.

FAQ

Does selenium-stealth work with Firefox?

The package documents Selenium Chrome/Chromium support. Selenium supports Firefox independently, but the package should not be assumed to configure Firefox.

Does selenium-stealth hide my IP address?

No. Browser configuration does not change your network identity.

Should I use selenium-stealth or undetected-chromedriver?

They take different approaches, and the available project documentation does not establish a universal winner. Compare their current compatibility and maintenance against your legitimate test requirement.

Can I use it to guarantee a successful reCAPTCHA score?

No. The README makes a maintainer claim about reCAPTCHA v3, but the reviewed evidence does not establish a guarantee.