Patchright: a patched Playwright driver for Chromium automation

What Patchright patches, and who needs that

Playwright drives a browser through a protocol layer, and sites that want to detect automation look at what that layer leaves behind. Patchright takes the Playwright driver and patches it, then presents the result as a drop-in replacement you can use in place of Playwright. The README describes it as "a patched and undetected version of the Playwright Testing and Automation Framework" and says it "can be used as a drop-in replacement for Playwright." That last phrase is the whole pitch: existing scripts keep their shape, and the difference sits underneath in the driver.

The audience is narrow and specific. If you write Playwright code to test your own application against a Chromium browser, Patchright is not aimed at you. It is aimed at people automating browsers they do not control, where the page actively tries to work out whether a human is driving. The repository topics list reads like a description of that audience: antidetect, stealth, undetectable, cloudflare-bypass, web-scraping. The README's sponsor block reinforces it, since every sponsor listed is a proxy vendor selling residential or mobile IPs for scraping.

One constraint frames everything else. The README states in a callout that Patchright "only patches CHROMIUM based browsers. Firefox and Webkit are not supported." If your test matrix spans all three engines, Patchright can only cover one of them, and you would be maintaining two automation stacks side by side.

The driver repository is not the package you install

This is the single most common source of confusion, and the README addresses it directly. The repository you are reading about serves the Patchright Driver. To actually use Patchright, the README points you at the Python package, the NodeJS package, or the community-driven .Net package. Those are separate repositories. The homepage field on this repository points at playwright.dev, which is Playwright's own documentation, not a Patchright install guide.

What lives here is the patching machinery. The top-level entries include driver_patches/, patchright.patch, patchright_driver_patch.ts and a utils/ directory. The package.json is a build tool, not a runtime package: it declares no dependencies field at all, only devDependencies such as @biomejs/biome, ts-morph, tsx, typescript and yaml. Its scripts are patch, prepatch, patchright-nodejs:update, typecheck, format:check, format:fix, rebuild and test.

Two of those scripts explain the architecture. The prepatch script runs a git submodule update against patchright-nodejs, and the patch script changes into a playwright directory and executes patchright_driver_patch.ts. So the workflow is: pull the Playwright submodule, then apply the patch script to produce a patched driver. The rebuild and test scripts, both bash files under utils/, rebuild and test a local package. If you are a user rather than a maintainer, none of this is your path. You install a language package and the patched driver arrives with it.

Installing Patchright and running a first script

The README does not give install commands for this repository, because this repository is not the install target. It gives links. The NodeJS package is published as patchright on npm, and the Python package is published as patchright on PyPI. Both are named in the README's badge block. Pick the one that matches your stack and follow that repository's instructions.

For a Node project, the install is a normal npm install of the package name:

npm install patchright

The Python equivalent installs from PyPI under the same name:

pip install patchright

Because Patchright is a drop-in replacement, the import path is the only edit in most existing scripts. A Playwright script that starts with a require of playwright becomes a require of patchright, and the rest of the file, including browser launch and page calls, is unchanged. The README's claim is that it can be used as a drop-in replacement, so this substitution is the intended migration.

Chromium is the only browser to launch. The README is explicit that Firefox and Webkit are not supported, so a launch call naming one of those engines is outside what this project patches. If you are porting a script that launches all three, strip it down to the Chromium path before you start debugging anything else. Note also that the driver version tracks Playwright's own version numbering, with the most recent release listed as v1.63.0 on 2026-09-08, so matching your Playwright expectations to that tag is worth doing before you file anything as a Patchright bug.

Where Patchright stops being the right tool

Patchright patches a driver. It does not supply the rest of what a scraping or automation operation needs, and the README's own sponsor section is the clearest admission of that. The sponsor copy from Scrappey states the split plainly: "Getting the browser past detection is one problem. Keeping proxies rotating, fingerprints current and sessions alive across a few million requests is a different one." Patchright addresses the first. Proxies, IP reputation and session persistence are handled elsewhere, by the vendors advertising in the README or by whatever you build.

That means a patched driver with a datacenter IP from a flagged range will still get blocked. Nothing in this repository changes your network identity. If your problem is that your requests come from an IP that a site has already scored badly, Patchright does not touch it.

The other boundary is scope of patching. Firefox and WebKit are not supported, stated in the README without qualification. If you need cross-browser coverage, Patchright is not a partial solution, it is no solution for two of the three engines. And if your goal is testing your own application rather than evading detection, the patching is solving a problem you do not have, while adding a fork of the driver you now have to keep in step with upstream Playwright releases.

Patchright versus plain Playwright

The comparison is not between two unrelated tools. Patchright is built from Playwright, and the README frames the relationship as a substitution rather than a migration: drop-in replacement. Plain Playwright gives you the unpatched driver, official documentation at playwright.dev, and a test runner, codegen and trace viewer built around testing your own sites. Patchright gives you the same programming surface with a driver that has been altered to be less detectable.

The practical difference shows up in what each is optimized for. Playwright's design assumptions are that the page under automation is yours or one you are permitted to test, which is why its defaults are convenient and transparent. Patchright inverts that assumption: the page is adversarial about automation, so the driver's visible signals are the thing being minimized. Everything else, the API you call, the language bindings, the browser you launch, stays close enough that the README can call it a drop-in.

The cost of the inversion is maintenance coupling. Patchright's version numbers shadow Playwright's, with v1.63.0, v1.62.1 and v1.61.1 as the recent releases, so each upstream Playwright change is something the patch has to survive. You are trading upstream stability for a modified driver. If your automation runs against sites that do not care about detection, that trade buys you nothing.

Versioning, licence and what a fork costs you

Patchright is licensed Apache-2.0, the same licence family Playwright uses, and the LICENSE file sits at the repository root. Apache-2.0 permits commercial use and modification and includes a patent grant, but it also carries attribution and notice requirements, and modified files must be marked as changed. Since Patchright is by definition a modified build of another project, that marking obligation is not hypothetical. This is a description of the licence text, not legal advice; if you redistribute a patched driver inside a product, have someone qualified read the notice requirements.

Upgrade cost is the more practical concern. The repository's last push was on 2026-09-13, and the most recent release, v1.63.0, was tagged on 2026-09-08. The gap between v1.61.1 on 2026-06-23 and v1.62.1 on 2026-08-17 shows the cadence is not strictly monthly. Each release is a patch rebased onto a Playwright version, so upgrading Patchright means moving to whatever Playwright version that release was built against. If your code depends on Playwright behaviour that changed between those versions, you inherit the change plus whatever the patch alters.

The NodeJS package is a git submodule here, updated by the prepatch and patchright-nodejs:update scripts. That is a maintainer detail, but it explains why the driver repository and the package repositories can drift apart in version. When you report a problem, the version that matters is the one in the package you installed, not the driver tag.

Editorial conclusion

Adopt Patchright if you already write Playwright tests or scrapers against Chromium and want the driver patched rather than rewriting your scripts. Do not adopt it if your automation targets Firefox or WebKit, since the README states those are not supported, or if you need the driver repository itself to be the thing you install. Before committing, verify two things: which language package matches your stack, and whether the latest release tag, v1.63.0 from 2026-09-08, tracks the Playwright version your existing code expects.

Frequently asked questions

Official sources

1. Kaliiiiiiiiii-Vinyzu/patchright on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases