feder-cr/invisible_playwrightPlaywright que os anti-bots não conseguem ver, portanto sem captchas: mesma API, Firefox headless furtivo anti-detecção, impressão digital indetectável, contorno de detecção de bots, web scraping em Python e automação de navegador.
<div align="center">
<picture>
<source media="(max-width: 374px) and (prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/feder-cr/invisible_playwright/main/docs/banner-small-dark.gif">
<source media="(max-width: 374px)" srcset="https://raw.githubusercontent.com/feder-cr/invisible_playwright/main/docs/banner-small-light.gif">
<source media="(max-width: 1239px) and (prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/feder-cr/invisible_playwright/main/docs/banner-phone-dark.gif">
<source media="(max-width: 1239px)" srcset="https://raw.githubusercontent.com/feder-cr/invisible_playwright/main/docs/banner-phone-light.gif">
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/feder-cr/invisible_playwright/main/docs/banner-dark.gif">
<img alt="invisible_playwright, Playwright em um Firefox anti-detecção. Uma animação: a troca de duas linhas do Playwright, o conjunto de fingerprint dentro do motor, um mouse que se move como uma mão, e os testes de bot que ele passa." src="https://raw.githubusercontent.com/feder-cr/invisible_playwright/main/docs/banner-light.gif" width="100%">
</picture>
<h3 align="center">O Playwright é detectado por anti-bots e captchas.<br>
Este roda em um Firefox anti-detecção com um fingerprint indetectável, compatível com seu código Playwright existente.</h3>
</div>
## Como funciona
Os anti-bots fazem duas perguntas, e o reCAPTCHA, o hCaptcha e o Cloudflare Turnstile pontuam as respostas. O invisible_playwright responde sim para ambas.
**1. Este é um navegador real?** Sim. É o Firefox, corrigido no nível do código-fonte C++.
- O fingerprint do navegador é definido dentro do motor, não injetado na página: navigator, screen, GPU/WebGL, canvas, fontes, áudio, WebRTC, fuso horário, rede. Headless ou headed, os mesmos valores de qualquer forma.
- Sem shim JS, sem override, sem costura para ler.
**2. Uma pessoa real está usando?** Sim. As ações são humanizadas no driver.
- Cada clique, hover e arrasto segue um caminho natural de mouse com timing humano, sem cursor teletransportando.
- Cada entrada é byte a byte idêntica a um mouse real: fonte de entrada real, pressão, eventos confiáveis.
---
## Instalação
Windows, no 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-playwright
uv run invisible-playwright fetch # one-time download, sha256-verified: 240 MB, about 550 MB unpacked
```
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-playwright
uv run invisible-playwright fetch # one-time download, sha256-verified: 262 MB (x86_64) / 253 MB (arm64), about 550 MB unpacked
```
Plataformas suportadas: **Windows x86_64**, **Linux x86_64 / arm64**.
Em seguida, salve um dos exemplos abaixo como `main.py` em `my-project` e execute-o com `uv run main.py`.
---
## Uso
### Impressão digital aleatória por sessão
**A API do Playwright, síncrona e assíncrona, sem alterações no código.** Os mesmos objetos, as mesmas chamadas, os mesmos valores de retorno. Algumas superfícies estão fora do escopo — tracing, HAR, CDP, o contexto de requisição da API — e cada uma delas recusa com uma frase explicando o motivo, em vez de se comportar mal silenciosamente. Se você já usa o Playwright, a troca leva duas linhas:
```diff
- from playwright.sync_api import sync_playwright
- with sync_playwright() as p:
- browser = p.firefox.launch()
+ from invisible_playwright import InvisiblePlaywright
+ with InvisiblePlaywright() as browser:
```
Cada sessão recebe uma impressão digital distinta (GPU, áudio, fontes, tela, ~200 campos) e movimento de mouse em curva de Bezier.
**Sincronização**
```python
from invisible_playwright import InvisiblePlaywright
with InvisiblePlaywright(proxy={"server": "socks5://...", "username": "u", "password": "p"}) as browser:
page = browser.new_page()
page.goto("https://example.com")
page.click("#submit") # mouse arcs to the button on a Bezier curve
```
**Assíncrono**
```python
from invisible_playwright.async_api import InvisiblePlaywright
async with InvisiblePlaywright(proxy={"server": "socks5://...", "username": "u", "password": "p"}) as browser:
page = await browser.new_page()
await page.goto("https://example.com")
await page.click("#submit")
```
O objeto `browser` é um `playwright.sync_api.Browser` / `playwright.async_api.Browser` - todos os métodos do Playwright funcionam como estão.
Registre a seed para reproduzir uma execução:
```python
sf = InvisiblePlaywright()
with sf as browser:
print("seed =", sf.seed)
# ...
```
### Impressão digital reproduzível
```python
with InvisiblePlaywright(seed=42) as browser:
... # same GPU, same canvas hash, same audio context, every run
```
### Proxies
```python
proxy = {
"server": "socks5://gate.example.com:1080",
"username": "user",
"password": "pass",
}
with InvisiblePlaywright(proxy=proxy) as browser:
...
```
Esquemas suportados: `socks5`, `socks4`, `http`, `https`. O DNS é encaminhado através do proxy por padrão, sem vazamento local.
### Fuso horário
O fuso horário do navegador segue `timezone=`:
```python
# default: timezone is auto-derived from the egress IP (proxy egress if a
# proxy is set, otherwise the host's own public IP)
with InvisiblePlaywright(proxy=proxy) as browser:
...
# explicit IANA zone always wins, the only way to force a specific zone
with InvisiblePlaywright(proxy=proxy, timezone="America/New_York") as browser:
...
```
### Fixando campos específicos de fingerprint
Por padrão, tudo vem de `seed`. Para forçar valores específicos enquanto o restante permanece derivado da seed:
```python
with InvisiblePlaywright(
seed=42,
pin={
"gpu.renderer": "ANGLE (AMD, Radeon R9 200 Series Direct3D11 vs_5_0 ps_5_0, D3D11)",
"gpu.vendor": "Google Inc. (AMD)",
"screen.width": 2560,
"screen.height": 1440,
"hardware.concurrency": 16,
},
) as browser:
...
```
Um pin de GPU escolhe uma das personas validadas em vez de definir uma string livre,
porque os ~81 valores de `getParameter` e a lista de extensões viajam com o
nome do renderer e um detector os verifica de forma cruzada. Um nome que o pool
não contém gera um erro, e o erro lista os que ele contém.
A lista completa de chaves fixáveis, como o pinning interage com o amostrador Bayesiano e os padrões comuns estão em **[docs/pinning.md](https://github.com/feder-cr/invisible_playwright/blob/main/docs/pinning.md)**.
---
## CLI
O comando instalado é `invisible-playwright`, com um hífen. `python -m
invisible_playwright` funciona de forma idêntica e não precisa de nada no PATH.
```bash
invisible-playwright fetch # download the engine if missing, check every cached
# one against the seal, print the path
invisible-playwright version # wrapper, core and engine versions, and where the
# engine is cached
```
## Documentação, guias e comparações
**Se você prefere usar prompts em vez de scripts.** Esta página é o motor, como uma biblioteca
Python. Duas formas de usá-lo sem escrever código, ambas em uma linha: a partir de um cliente MCP
que você já tem (Claude Code, Claude Desktop, Cursor),
`claude mcp add stealth -- uvx aihawk`, veja
[a página do servidor MCP](https://github.com/feder-cr/AIHawk/wiki/mcp-server); ou com uma
interface e um modelo incluído, precisando apenas de uma chave OpenRouter,
`uvx aihawk ui --openrouter-key sk-or-...`, veja
[AIHawk](https://github.com/feder-cr/AIHawk). O mesmo motor por baixo, e o segundo
é um cliente do primeiro.
Tudo isso é mais fácil de ler, e pesquisável, em
**[a wiki](https://github.com/feder-cr/invisible_playwright/wiki)**,
organizada em quatro seções em vez de uma lista única:
- **[Documentação](https://github.com/feder-cr/invisible_playwright/blob/main/docs/documentation.md)** -
instalação, a troca de duas linhas a partir do Playwright puro, configuração de
proxy/fuso horário, fixação de campos específicos, a CLI.
- **[Guias](https://github.com/feder-cr/invisible_playwright/blob/main/docs/guides.md)** - como
a detecção realmente funciona, em sete grupos: identidade do navegador, canvas/WebGL/fontes/
áudio, rede e WebRTC, a camada de automação, agentes de IA, os próprios detectores
explicados a partir do código-fonte, e testes.
- **[Comparações](https://github.com/feder-cr/invisible_playwright/blob/main/docs/comparisons.md)** -
com Camoufox, Patchright, nodriver e playwright-stealth, e o argumento a favor do
Firefox em relação ao Chromium em geral.
- **[Integrações](https://github.com/feder-cr/invisible_playwright/blob/main/docs/integrations)** -
Scrapy, Crawlee, Robot Framework, CodeceptJS, executores de testes, Playwright MCP, e os
frameworks aos quais não se aplica, por nome.
Se você não sabe por onde começar: [Três formas de tornar o Playwright indetectável](https://github.com/feder-cr/invisible_playwright/blob/main/docs/playwright-stealth-levels.md)
é o mapa para o qual a maioria das outras páginas aponta de volta, [Playwright detectado como bot em um site](https://github.com/feder-cr/invisible_playwright/blob/main/docs/playwright-detected-as-bot.md)
é a ordem de solução de problemas, e [navigator.webdriver não é o indício que você pensa que é](https://github.com/feder-cr/invisible_playwright/blob/main/docs/navigator-webdriver-explained.md)
explica a propriedade mais famosa deste espaço e por que corrigi-la sozinha quase não traz
ganho.
A seção de detectores agora cobre os produtos comerciais anti-bot por nome, cada um
lido a partir de sua própria documentação ou de engenharia reversa confirmada:
[Cloudflare Bot Management](https://github.com/feder-cr/invisible_playwright/blob/main/docs/cloudflare-bot-management-explained.md) e
[Turnstile](https://github.com/feder-cr/invisible_playwright/blob/main/docs/cloudflare-turnstile-explained.md),
[DataDome](https://github.com/feder-cr/invisible_playwright/blob/main/docs/datadome-explained.md), [Kasada](https://github.com/feder-cr/invisible_playwright/blob/main/docs/kasada-explained.md),
[Akamai Bot Manager](https://github.com/feder-cr/invisible_playwright/blob/main/docs/akamai-bot-manager-explained.md),
[PerimeterX](https://github.com/feder-cr/invisible_playwright/blob/main/docs/perimeterx-explained.md), [hCaptcha](https://github.com/feder-cr/invisible_playwright/blob/main/docs/hcaptcha-explained.md),
[Imperva](https://github.com/feder-cr/invisible_playwright/blob/main/docs/imperva-incapsula-explained.md), e
[o restante do conjunto](https://github.com/feder-cr/invisible_playwright/blob/main/docs/guides-detectors-explained.md).
## Projetos relacionados
**As outras peças deste projeto.** O motor é o do meio de três, e os
dois ao seu redor são como a maioria das pessoas chega até ele:
- **[invisible_core](https://github.com/feder-cr/invisible_core)** - da semente à
impressão digital às preferências, além de proxy e geolocalização. Este pacote o fixa.
- **[AIHawk](https://github.com/feder-cr/AIHawk)** - este motor como um servidor
MCP (`uvx aihawk`, para qualquer cliente que traga seu próprio
modelo) e, no mesmo pacote, uma interface com um modelo incluído, a partir
de um comando. A interface é um cliente do servidor, sem caminho privado
para o navegador.
**Os vizinhos de código aberto.** Qual deles se encaixa depende da camada em que seu problema
está, e de você precisar de Firefox ou Chromium:
[três formas de tornar o Playwright indetectável](https://github.com/feder-cr/invisible_playwright/blob/main/docs/playwright-stealth-levels.md) percorre
o que cada camada consegue alcançar, e [agentes de navegador de IA e stealth](https://github.com/feder-cr/invisible_playwright/blob/main/docs/ai-browser-agents-stealth.md)
cobre os frameworks que escolhem o Chromium em vez do CDP por você.
**Do lado do Firefox**
- **[Camoufox](https://github.com/daijro/camoufox)** - também aplica patches em C++, superfície mais ampla, distribui um banco de dados de fingerprints em vez de derivá-lo de uma seed. [Comparação](https://github.com/feder-cr/invisible_playwright/blob/main/docs/vs-camoufox.md).
- **[LibreWolf](https://librewolf.net)** - um Firefox com padrões de privacidade para navegar, não para automatizar.
- **[arkenfox/user.js](https://github.com/arkenfox/user.js)** - endurecimento por meio de preferências. Onde uma preferência é suficiente, use-a.
**No lado do Chromium**
- **[Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)** - um fork corrigido do Playwright: o trabalho fica no driver, não no binário. [Comparação](https://github.com/feder-cr/invisible_playwright/blob/main/docs/vs-patchright.md).
- **[nodriver](https://github.com/ultrafunkamsterdam/nodriver)** - sucessor do `undetected-chromedriver`, controlando o Chrome via CDP. [Comparação](https://github.com/feder-cr/invisible_playwright/blob/main/docs/vs-nodriver.md).
- **[rebrowser-patches](https://github.com/rebrowser/rebrowser-patches)** - corrige o vazamento de `Runtime.enable` do CDP. [Comparação](https://github.com/feder-cr/invisible_playwright/blob/main/docs/vs-rebrowser-patches.md).
- **[fingerprint-suite](https://github.com/apify/fingerprint-suite)** - um gerador bayesiano de fingerprints, depois injetado na página. [Comparação](https://github.com/feder-cr/invisible_playwright/blob/main/docs/vs-fingerprint-suite.md).
- **[playwright-with-fingerprints](https://github.com/bablosoft/playwright-with-fingerprints)** - valores de um serviço remoto pago, apenas para Windows. [Comparação](https://github.com/feder-cr/invisible_playwright/blob/main/docs/vs-playwright-with-fingerprints.md).
- **[playwright-stealth](https://github.com/Mattwmaster58/playwright_stealth)** - um patch de script de inicialização; seu mantenedor o chama de prova de conceito. [Comparação](https://github.com/feder-cr/invisible_playwright/blob/main/docs/vs-playwright-stealth.md).
- **[puppeteer-extra-plugin-stealth](https://github.com/berstend/puppeteer-extra)** - o original dessa linhagem, último commit substancial em meados de 2024. [O que isso significa](https://github.com/feder-cr/invisible_playwright/blob/main/docs/puppeteer-extra-stealth-unmaintained.md).
- **[selenium-stealth](https://github.com/diprajpatra/selenium-stealth)** - a mesma abordagem no Selenium, último commit em dezembro de 2021. [O que isso significa](https://github.com/feder-cr/invisible_playwright/blob/main/docs/selenium-stealth-unmaintained.md).
- **[pyppeteer](https://github.com/pyppeteer/pyppeteer)** - sem manutenção segundo seu próprio README, que aponta para `playwright-python`. [Sobre o que é essa recomendação](https://github.com/feder-cr/invisible_playwright/blob/main/docs/pyppeteer-unmaintained-playwright.md).
---
## O que é corrigido no motor
Duas regras valem para tudo abaixo. Todo valor é decidido **antes que uma página possa
perguntar**, dentro do navegador, então não há shim JavaScript a ser encontrado. E todo valor
vem de **um único perfil**, então nenhuma superfície contradiz outra, que é como um
navegador falsificado costuma ser detectado. Fonte:
[feder-cr/firefox_antidetect_patch](https://github.com/feder-cr/firefox_antidetect_patch).
**Identidade**
- `navigator`, o user agent e os client hints são derivados em conjunto, então não podem divergir: [o Playwright define navigator.webdriver](https://github.com/feder-cr/invisible_playwright/blob/main/docs/does-playwright-set-navigator-webdriver.md), [client hints e Sec-Fetch](https://github.com/feder-cr/invisible_playwright/blob/main/docs/client-hints-sec-fetch.md).
- `navigator.languages` e o cabeçalho `Accept-Language` são a mesma declaração, enviada e lida: [Accept-Language e navigator.languages](https://github.com/feder-cr/invisible_playwright/blob/main/docs/accept-language-navigator-languages.md).
- A geometria da tela, `devicePixelRatio` e as media queries que a expõem são declaradas, não lidas do host: [devicePixelRatio e a pref do Firefox](https://github.com/feder-cr/invisible_playwright/blob/main/docs/devicepixelratio-firefox-pref.md), [fingerprinting por media queries CSS](https://github.com/feder-cr/invisible_playwright/blob/main/docs/css-media-query-fingerprinting.md).
**Renderização**
- A leitura do canvas é determinística por seed e mantém a forma real, em vez de bloqueada ou com ruído: [ruído de fingerprint de canvas](https://github.com/feder-cr/invisible_playwright/blob/main/docs/canvas-fingerprint-noise.md), [por que um fingerprint de canvas muda a cada execução](https://github.com/feder-cr/invisible_playwright/blob/main/docs/canvas-fingerprint-changes-every-run.md).
- O WebGL reporta uma persona de GPU coerente: fornecedor, renderizador e os limites de parâmetros são verificados de forma cruzada, não definidos um de cada vez: [strings do renderizador WebGL](https://github.com/feder-cr/invisible_playwright/blob/main/docs/webgl-renderer-strings.md), [os parâmetros WebGL são idênticos](https://github.com/feder-cr/invisible_playwright/blob/main/docs/webgl-parameters-are-identical.md).
- As fontes acompanham o navegador, então as mesmas faces existem em cada host e o motor de fontes da plataforma já não escolhe: [fontes empacotadas entre plataformas](https://github.com/feder-cr/invisible_playwright/blob/main/docs/bundled-fonts-cross-platform.md), [por que navegadores headless renderizam fontes diferentes](https://github.com/feder-cr/invisible_playwright/blob/main/docs/headless-fonts-differ.md), [detectar fontes instaladas a partir do JavaScript](https://github.com/feder-cr/invisible_playwright/blob/main/docs/detect-installed-fonts-javascript.md).
- As métricas de texto seguem essas fontes: `measureText` retorna mais de dez números a partir de uma única chamada, sem prompt de permissão: [measureText e TextMetrics](https://github.com/feder-cr/invisible_playwright/blob/main/docs/measuretext-textmetrics-fingerprinting.md).
- Canvas e WebGL concordam entre sistemas operacionais para a mesma seed: [consistência entre plataformas](https://github.com/feder-cr/invisible_playwright/blob/main/docs/canvas-webgl-cross-platform-consistency.md), [o canvas difere entre sistemas operacionais](https://github.com/feder-cr/invisible_playwright/blob/main/docs/canvas-differs-across-operating-systems.md).
**Áudio e mídia**
- A pilha de áudio responde a partir do perfil em vez do dispositivo host: [fingerprinting de AudioContext](https://github.com/feder-cr/invisible_playwright/blob/main/docs/audiocontext-fingerprinting.md), [taxa de amostragem e latência](https://github.com/feder-cr/invisible_playwright/blob/main/docs/audiocontext-samplerate-latency-fingerprint.md).
- A tabela de codecs é declarada, então um host Linux não responde a uma pergunta de Windows com suporte a Linux: [fingerprinting de codecs](https://github.com/feder-cr/invisible_playwright/blob/main/docs/codec-fingerprinting.md).
**Rede**
- O WebRTC oferece um candidato sintético carregando a saída do proxy, em vez de vazar o endereço real ou não oferecer nenhum, o que por si só é um indício: [spoofing de candidato ICE do WebRTC](https://github.com/feder-cr/invisible_playwright/blob/main/docs/webrtc-ice-candidate-spoofing.md), [o IP do WebRTC corresponde à saída do proxy](https://github.com/feder-cr/invisible_playwright/blob/main/docs/webrtc-ip-match-proxy-exit.md).
- O DNS resolve através do proxy, inclusive quando o proxy não está nas preferências: [um proxy vaza DNS](https://github.com/feder-cr/invisible_playwright/blob/main/docs/does-a-proxy-leak-dns-doh-explained.md), [como verificar vazamento de IP de proxy](https://github.com/feder-cr/invisible_playwright/blob/main/docs/how-to-check-proxy-ip-leak.md).
- O fuso horário vem do IP de saída, resolvido offline, então corresponde à saída: [incompatibilidade de fuso horário e proxy](https://github.com/feder-cr/invisible_playwright/blob/main/docs/timezone-proxy-mismatch.md), [fuso horário GeoIP offline](https://github.com/feder-cr/invisible_playwright/blob/main/docs/offline-geoip-timezone-proxy.md).
**A camada de automação**
- Os eventos de entrada vêm do caminho de entrada real, então `isTrusted` é verdadeiro porque é verdadeiro: [cliques do Playwright e isTrusted](https://github.com/feder-cr/invisible_playwright/blob/main/docs/playwright-clicks-istrusted.md).
- O ponteiro segue um caminho e tempo humanos, a uma cadência que um dispositivo real poderia produzir: [movimento humano do mouse](https://github.com/feder-cr/invisible_playwright/blob/main/docs/human-mouse-movement.md), [dinâmica do mouse como biometria comportamental](https://github.com/feder-cr/invisible_playwright/blob/main/docs/mouse-dynamics-behavioural-biometrics.md).
- A superfície do depurador não responde às perguntas de temporização que denunciam um navegador controlado: [detecção de temporização do depurador](https://github.com/feder-cr/invisible_playwright/blob/main/docs/debugger-timing-detection.md).
- Shadow roots em modo fechado são acessíveis, o que o Playwright padrão não consegue fazer em nenhum dos motores, enquanto a página ainda lê `null`: [shadow roots fechados](https://github.com/feder-cr/invisible_playwright/blob/main/docs/closed-shadow-root-playwright.md).
---
## Licença
MIT - veja [LICENSE](https://github.com/feder-cr/invisible_playwright/blob/main/LICENSE). O binário do Firefox modificado é distribuído sob a MPL-2.0 (licença upstream do Firefox). Os patches em C++ contra o mozilla-central que produzem esse binário estão em [feder-cr/firefox_antidetect_patch](https://github.com/feder-cr/firefox_antidetect_patch).
---
## Aviso legal
Este projeto é apenas para fins educacionais. É fornecido como está, sem garantias. Não me responsabilizo pela forma como é utilizado. Use por sua conta e risco e em conformidade com as leis da sua jurisdição.
---
<p align="center">
Criado por <a href="https://it.linkedin.com/in/federico-elia-5199951b6">Federico Elia</a>
<a href="https://it.linkedin.com/in/federico-elia-5199951b6"><img src="https://raw.githubusercontent.com/feder-cr/invisible_playwright/main/docs/badges/linkedin.svg" alt="LinkedIn"></a>
</p>
<p align="center">
<a href="https://github.com/feder-cr/invisible_playwright/actions/workflows/tests.yml"><img src="https://github.com/feder-cr/invisible_playwright/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
<a href="https://github.com/feder-cr/invisible_playwright/blob/main/LICENSE"><img src="https://raw.githubusercontent.com/feder-cr/invisible_playwright/main/docs/badges/license.svg" alt="Licença: MIT"></a>
<a href="https://www.python.org/downloads/"><img src="https://raw.githubusercontent.com/feder-cr/invisible_playwright/main/docs/badges/python.svg" alt="Python 3.11+"></a>
<a href="https://github.com/feder-cr/firefox_antidetect_patch/releases"><img src="https://raw.githubusercontent.com/feder-cr/invisible_playwright/main/docs/badges/firefox.svg" alt="Firefox 151.0"></a>
<img src="https://raw.githubusercontent.com/feder-cr/invisible_playwright/badges/docs/badges/launches.svg" alt="inicializações do navegador">
<a href="https://github.com/feder-cr/invisible_playwright/stargazers"><img src="https://raw.githubusercontent.com/feder-cr/invisible_playwright/badges/docs/badges/stars.svg" alt="Estrelas no GitHub"></a>
</p>