How to use playwright-stealth

What is playwright-stealth?

playwright-stealth is a Python package that patches a running Playwright session to hide the markers that identify it as automated. It is a port of puppeteer-extra-plugin-stealth, which does the same job in the Node ecosystem and is where most of the technique originated.

The problem it addresses: a headless browser differs from a real one in ways that are trivial to read from JavaScript. It announces HeadlessChrome in its user agent, sets navigator.webdriver to true, ships no plugins, and is missing the window.chrome object a real Chrome carries. Any page can check all four in a line of code.

It differs from Patchright in where it intervenes. Patchright patches the framework and you swap an import; playwright-stealth leaves Playwright alone and injects fixes into each page at runtime. That makes it easier to add to an existing script and means the fixes have to be applied to every context you create.

Installing and wrapping a session

pip install playwright-stealth

from playwright.sync_api import sync_playwright
from playwright_stealth import Stealth

with Stealth().use_sync(sync_playwright()) as pw:
    browser = pw.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto("https://example.com")

That is the whole setup. The advice usually stops there, so we read back what the page sees afterwards.

It fixes three of the four signals plain Playwright fails. On the fourth it reports two different operating systems in the same call.

What it changes

That is a better result than Patchright managed by default, which cleared the webdriver flag and left the other three. It also removes HeadlessChrome from the user agent, which neither Patchright configuration did.

The contradiction

Three consecutive runs, byte-identical output every time:

navigator.userAgent            Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ... Chrome/148
navigator.userAgentData.platform   macOS
navigator.platform             Win32

The user agent says Macintosh. The modern platform API agrees and says macOS. The legacy navigator.platform says Win32.

A real machine cannot answer that pair two ways. A Mac reports MacIntel; a Windows machine reports Win32 and does not send a Macintosh user agent. Catching this needs no fingerprinting library and no heuristic, only an equality check between two properties any script can read.

We are not claiming this defeats any specific system, and we did not test it against a detector. We are saying the two values disagree, that they disagreed on every run, and that it is trivially readable.

Why the legacy property is the one that matters

navigator.platform is deprecated and every modern guide will tell you to use navigator.userAgentData instead. That is exactly why it is worth checking: a stealth patch written against the modern API has no reason to remember the old one, and a detector written five years ago has no reason to stop reading it.

Deprecated does not mean absent. It means nobody is looking at it except the people looking for you.

Reading the signals yourself

from playwright.sync_api import sync_playwright
from playwright_stealth import Stealth

with Stealth().use_sync(sync_playwright()) as pw:
    browser = pw.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.evaluate("""() => ({
        ua: navigator.userAgent,
        platform: navigator.platform,
        uaPlatform: navigator.userAgentData?.platform,
        webdriver: String(navigator.webdriver),
    })"""))

Four lines of JavaScript, and it is worth running against whatever you are using rather than trusting any table, including this one. The projects in this space ship quickly and a result from August is a result from August.

Why the mismatch is reproducible

Camoufox changes the operating system it claims between launches, and every run agrees with itself: a Mac user agent arrives with MacIntel, a Windows one with Win32. We measured that in how to choose an anti-detect browser.

This is the opposite shape. The values do not vary at all, so the mismatch is reproducible rather than intermittent, which makes it something you can check for in one line before a run rather than a ghost you chase through a log.

Adding a proxy

playwright-stealth wraps Playwright, so the proxy argument is unchanged:

with Stealth().use_sync(sync_playwright()) as pw:
    browser = pw.chromium.launch(
        headless=True,
        proxy={"server": "http://gate.example.com:7000",
               "username": "user-session-abc123",
               "password": "secret"},
    )

The two things that break this are provider-side rather than library-side. The session token sits in the username at some providers and the password at others, and the wrong one produces a 407 with nothing naming the cause. And some providers take no username and password at all, wanting your IP on an allowlist instead.

We publish what each provider states about both on its provider page with the date we read it, and print that a provider says nothing where it says nothing. The format converter reshapes a credential into the separate fields this call expects.

Limitations

No anti-bot system, no evasion claim, no recommendation. Seven signals from playwright-stealth 2.0.3 on Chromium 148, one machine, three runs, one day. The value here is a check you can re-run in a minute, not a verdict with a shelf life.

One boundary worth naming: this guide exists for pages you do not control. If the captcha you keep meeting is on your own application, stealth is the wrong tool entirely, and testing captcha flows in Playwright with the vendors' test keys is the shorter and more honest path.