# puppeteer (oss-invisible/puppeteer)

> This is a Python port of Puppeteer that runs on a patched, anti-detect Firefox build so sites using reCAPTCHA, hCaptcha or Cloudflare Turnstile can't tell it's a bot, letting you scrape and automate without hitting captchas.

- GitHub: https://github.com/oss-invisible/puppeteer
- GitHub.Locker page: https://github.locker/oss-invisible/puppeteer
- Stars: 155
- Language: Python
- License: MIT
- Last push: 2026-11-17

## Questions and answers

Written by GitHub.Locker from the README and the repository; check the README below for details.

**Is this a drop-in replacement for pyppeteer, or a separate framework?**

It's a drop-in Python library: the same launch, Browser, Page and ElementHandle API as pyppeteer (Puppeteer's Python port), so you just swap the import and keep your existing code.

**How do I switch my existing pyppeteer code over to this?**

Since the API matches pyppeteer exactly, migrating is just swapping the import; you should not keep pyppeteer installed alongside it because this package already implements its API.

**What Python version and OS do I need?**

You need Python 3.11 or newer, and it only runs on Windows x86-64/ARM64 or Linux x86-64/arm64.

**Any catch before I rely on this for scraping?**

There's no macOS build listed, and the author explicitly flags this as educational-only with no warranties, so use it at your own risk and check the laws of your jurisdiction.

**Is the whole project really MIT?**

Mostly: it's MIT overall, but two files from Playwright's driver are licensed Apache-2.0 and the patched Firefox binary itself is MPL-2.0.

**How does the fingerprint evasion actually work?**

The browser fingerprint (navigator, screen, GPU/WebGL, canvas, fonts, audio, WebRTC, timezone, network) is set inside the patched Firefox engine itself rather than injected via JavaScript, so it looks the same whether headless or headed.

**Does it fake human mouse and keyboard behavior too?**

Yes, every click, hover and drag follows a natural mouse path with human-like timing, and input goes through the browser's real input path so pages receive trusted events instead of synthetic ones.

**How is this different from puppeteer-extra-plugin-stealth?**

That plugin patches the page from JavaScript and its last substantive commit was mid-2024, while invisible_puppeteer patches Firefox at the C++ source level, leaving no JS shim for a site to detect.

**Are there sibling projects for other automation frameworks?**

Yes: invisibleplaywright offers the same engine with Playwright's API, invisibleselenium with Selenium's API, and invisibleplaywrightmcp exposes it to AI agents over MCP.


---

## README (checked against GitHub 2026-11-18)

Source: https://github.com/oss-invisible/puppeteer/blob/main/README.md

<div align="center">
<picture>
  <source media="(max-width: 374px) and (prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/oss-invisible/puppeteer/main/docs/banner-small-dark.gif">
  <source media="(max-width: 374px)" srcset="https://raw.githubusercontent.com/oss-invisible/puppeteer/main/docs/banner-small-light.gif">
  <source media="(max-width: 1239px) and (prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/oss-invisible/puppeteer/main/docs/banner-phone-dark.gif">
  <source media="(max-width: 1239px)" srcset="https://raw.githubusercontent.com/oss-invisible/puppeteer/main/docs/banner-phone-light.gif">
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/oss-invisible/puppeteer/main/docs/banner-dark.gif">
  <img alt="invisible_puppeteer, Puppeteer's API in Python on an anti-detect Firefox. An animation: the import that changes, the fingerprint set inside the engine, a mouse that moves like a hand, and the options for a reproducible run." src="https://raw.githubusercontent.com/oss-invisible/puppeteer/main/docs/banner-light.gif" width="100%">
</picture>
<h3 align="center">Puppeteer gets caught by anti-bots and captchas.<br>
This one runs on an anti-detect Firefox with an undetected fingerprint, compatible with your existing Puppeteer code in Python.</h3>
</div>

<p align="center">
<a href="https://decodo.com/deals/residential-offer?utm_medium=affiliate&utm_source=Federico+Elia&promoter_id=15854270&fpr=7859773"><img alt="Decodo residential proxies, free trial (sponsored)" src="https://raw.githubusercontent.com/oss-invisible/puppeteer/main/docs/decodo-residential-proxies-trial.png" width="560"></a><br>
<sub>Sponsored</sub>
</p>

## How it works

Anti-bots ask two questions, and reCAPTCHA, hCaptcha and Cloudflare Turnstile score the answers. invisible_puppeteer answers yes to both.

**1. Is this a real browser?** Yes. It is Firefox, patched at the C++ source level.

- The browser fingerprint is set inside the engine, not injected into the page: navigator, screen, GPU/WebGL, canvas, fonts, audio, WebRTC, timezone, network. Headless or headed, the same values either way.
- No Chromium, no DevTools protocol and no JavaScript shim for a page to find.

**2. Is a real person using it?** Yes. The actions are humanized in the driver.

- Every click, hover and drag follows a natural mouse path with human timing, no teleporting cursor.
- Input goes through the browser's real input path, so the page sees trusted events.

---

## Install

Windows, in PowerShell:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
uv init --python ">=3.11" my-project
cd my-project
uv add invisible-puppeteer
uv run invisible-puppeteer fetch
```

Linux:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv init --python ">=3.11" my-project
cd my-project
uv add invisible-puppeteer
uv run invisible-puppeteer fetch
```

Supported platforms: **Windows x86_64 / ARM64** (the x86_64 engine, under Windows' own emulation), **Linux x86_64**. Linux arm64 is no longer supported from firefox-56 (firefox-55 is the last engine built for it).

Then save one of the examples below as `main.py` in `my-project` and run it with `uv run main.py`.

---

## Usage

**Puppeteer's API in Python, with no code changes.** The same `launch`, `Browser`, `Page` and `ElementHandle` as pyppeteer, Puppeteer's Python port. If you already use it, switching is the import:

```diff
- from pyppeteer import launch
+ from invisible_puppeteer import launch
```

```python
import asyncio
from invisible_puppeteer import launch

async def main():
    browser = await launch()
    page = await browser.newPage()
    await page.goto("https://example.com")
    await page.click("a")          # the mouse arcs to the link
    print("seed =", browser.seed)  # log it to replay the run
    await browser.close()

asyncio.run(main())
```

Every session gets a distinct fingerprint (GPU, audio, fonts, screen, ~200 fields). Do not install pyppeteer alongside it: this package already implements its API.

### Options

```python
browser = await launch(
    seed=42,                        # same seed, same fingerprint, every run
    proxy={"server": "socks5://host:1080", "username": "u", "password": "p"},
    timezone="America/New_York",    # default: derived from the proxy's exit IP
    pin={"screen.width": 2560, "screen.height": 1440},   # force fields, the rest stays seed-derived
    headless=True,                  # the default: hidden desktop, real rendering, same fingerprint as headed
    userDataDir="./profile",        # cookies and storage survive the run
)
```

Proxies can be `socks5`, `socks4`, `http` or `https`, and DNS goes through them too. The viewport defaults to the fingerprint's screen size instead of Puppeteer's 800x600. The fields you can pin are the same as in invisible_playwright: **[pinning](https://github.com/oss-invisible/playwright/blob/main/docs/pinning.md)**.

## CLI

```bash
invisible-puppeteer fetch      # download the engine if missing, check every cached one, print the path
invisible-puppeteer version    # wrapper, core and engine versions
```

---

## Related projects

- **[invisible_playwright](https://github.com/oss-invisible/playwright)**: the same engine with Playwright's API, and **[the guides](https://github.com/oss-invisible/playwright/blob/main/docs/guides.md)** on how detection works.
- **[invisible_selenium](https://github.com/oss-invisible/selenium)**: the same engine with Selenium's API.
- **[invisible_playwright_mcp](https://github.com/oss-invisible/playwright_mcp)**: the same engine for AI agents, over MCP.
- **[invisible_core](https://github.com/oss-invisible/core)**: turns a seed into a fingerprint and the fingerprint into Firefox preferences. This package depends on an exact version of it.
- **[firefox_antidetect_patch](https://github.com/oss-invisible/firefox_antidetect_patch)**: the C++ patches that build the browser.

**Switching from another tool?**

- **[pyppeteer](https://github.com/pyppeteer/pyppeteer)**: its own README says it is no longer maintained. [What that means](https://github.com/oss-invisible/playwright/blob/main/docs/pyppeteer-unmaintained-playwright.md).
- **[puppeteer-extra-plugin-stealth](https://github.com/berstend/puppeteer-extra)**: it patches the page from JavaScript, and its last substantive commit is from mid-2024. [What that means](https://github.com/oss-invisible/playwright/blob/main/docs/puppeteer-extra-stealth-unmaintained.md).

## Development

The setup and the test commands are in [CONTRIBUTING.md](CONTRIBUTING.md#development-setup).

## License

MIT, see [LICENSE](LICENSE). The Juggler client it drives the browser with lives in [invisible-core](https://github.com/oss-invisible/core), which carries two files taken from Playwright's driver under Apache-2.0. The patched Firefox binary is MPL-2.0, built from [oss-invisible/firefox_antidetect_patch](https://github.com/oss-invisible/firefox_antidetect_patch).

## Disclaimer

This project is for educational purposes only. It is provided as-is, with no warranties. I take no responsibility for how it is used. Use it at your own risk and in compliance with the laws of your jurisdiction.

---

<p align="center">
  Built by <a href="https://it.linkedin.com/in/federico-elia-5199951b6">Federico Elia</a>
  &nbsp;<a href="https://it.linkedin.com/in/federico-elia-5199951b6"><img src="https://raw.githubusercontent.com/oss-invisible/playwright/main/docs/badges/linkedin.svg" alt="LinkedIn"></a>
</p>

<p align="center">
  <a href="https://github.com/oss-invisible/puppeteer/actions/workflows/tests.yml"><img src="https://github.com/oss-invisible/puppeteer/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
  <a href="https://github.com/oss-invisible/puppeteer/blob/main/LICENSE"><img src="https://raw.githubusercontent.com/oss-invisible/playwright/main/docs/badges/license.svg" alt="License: MIT"></a>
  <a href="https://www.python.org/downloads/"><img src="https://raw.githubusercontent.com/oss-invisible/playwright/main/docs/badges/python.svg" alt="Python 3.11+"></a>
</p>

