# Proxy no Playwright: autenticação, Python e Node | ProxyJam

Como configurar um proxy no Playwright por navegador ou por contexto, com usuário e senha em HTTP, e por que o SOCKS5 exige lista de IPs permitidos. Código testado.

- Canonical: https://proxyjam.com/pt/integrations/playwright/
- Updated: 2026-11-17
- Language: pt

Dê ao Playwright um endereço ISP estático, ao iniciar o navegador ou para um único contexto. Os exemplos foram executados em Chromium, Firefox e WebKit contra um proxy local antes de serem publicados.


Passe proxy com server, username e password para chromium.launch, ou para browser.new_context para limitá-lo a um contexto. Em HTTP, os três motores se autenticam com esses campos. Em SOCKS5, nenhum deles aceita usuário e senha: o Playwright se recusa a iniciar. Coloque o seu IP na lista de IPs permitidos do proxy e informe apenas o servidor socks5://.


## Configurar um proxy no Playwright

1. **Copie host, porta, usuário e senha** Em Meus Proxies no painel ou no pedido pela API. Cada endereço vem com os seus próprios quatro valores.
2. **Escolha o escopo** Em `launch`, o navegador inteiro usa o proxy. Em `new_context`, só esse contexto o usa, então um mesmo script pode executar vários contextos por endereços diferentes.
3. **Passe o objeto proxy** `{"server": "http://HOST:PORT", "username": "USERNAME", "password": "PASSWORD"}`. As credenciais vão em campos próprios, nunca dentro da URL do servidor.
4. **Vai usar SOCKS5? Retire as credenciais** O Playwright não consegue fazer login em um proxy SOCKS5, então mude o pedido para SOCKS5, admita o IP da sua máquina com a chamada da lista de IPs permitidos nas abas de código e mantenha apenas `socks5://HOST:PORT`, com a nova porta. Enquanto uma lista de IPs permitidos estiver definida, o proxy admite apenas os endereços listados e o usuário e a senha deixam de funcionar para esse pedido; enviar uma lista vazia desativa a lista de IPs permitidos e o login com senha volta a funcionar.
5. **Confirme o endereço de saída** Abra [Qual é o meu IP](/pt/what-is-my-ip/) em uma página desse navegador ou contexto uma vez, antes da execução real.

## Código testado para o Playwright

Executado com o Playwright 1.64 para Python e para Node. Os exemplos HTTP enviam usuário e senha e precisam de um pedido sem lista de IPs permitidos definida; o de SOCKS5 depende da lista de IPs permitidos e exige que o proxy seja mudado antes para SOCKS5, o que gera uma nova porta. Substitua os valores em maiúsculas pelos do seu pedido.

### Python

Proxy para o navegador inteiro, Python.

```
# pip install playwright && playwright install chromium
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(proxy={
        "server": "http://HOST:PORT",
        "username": "USERNAME",
        "password": "PASSWORD",
    })
    page = browser.new_page()
    page.goto("https://example.com/")
    print(page.title())
    browser.close()
```

### Node.js

Proxy para o navegador inteiro, Node.

```
// npm i playwright && npx playwright install chromium
const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({
    proxy: {
      server: 'http://HOST:PORT',
      username: 'USERNAME',
      password: 'PASSWORD',
    },
  });
  const page = await browser.newPage();
  await page.goto('https://example.com/');
  console.log(await page.title());
  await browser.close();
})();
```

### Por contexto

Proxy para um contexto de navegador.

```
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    # The proxy belongs to this context only; another context can use
    # a different address, or none.
    context = browser.new_context(proxy={
        "server": "http://HOST:PORT",
        "username": "USERNAME",
        "password": "PASSWORD",
    })
    page = context.new_page()
    page.goto("https://example.com/")
    print(page.title())
    browser.close()
```

### SOCKS5

SOCKS5 com um IP na lista de IPs permitidos.

```
# Switch the proxy to SOCKS5 and put your machine's IP on its allowlist:
# Chromium cannot send a SOCKS5 username and password.
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(proxy={"server": "socks5://HOST:PORT"})
    page = browser.new_page()
    page.goto("https://example.com/")
    print(page.title())
    browser.close()
```

### Chamada da lista de IPs permitidos

Adicione o seu IP à lista de IPs permitidos do proxy.

```
# Put the public IPv4 address your code runs from on the proxy's
# allowlist. Replaces the list; an empty list turns allowlisting off
# and the proxy falls back to username and password.
curl -X PUT "https://api.proxyjam.com/public/v1/orders/ORDER_ID/whitelist" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whitelisted_ips": ["YOUR_IP"]}'
```


## O que cada navegador do Playwright aceita

|  | HTTP com senha | SOCKS5 com senha | SOCKS5, com IP permitido |
|---|---|---|---|
| Chromium | Funciona | Recusado na inicialização | Funciona |
| Firefox | Funciona | Recusado na inicialização | Funciona |
| WebKit | Funciona | Recusado na inicialização | Funciona |

Testado em 2026-10-22 com o Playwright 1.64 para Python no macOS: cada motor foi iniciado contra um proxy local que exigia senha e contra outro que admitia um cliente da lista de IPs permitidos. Recusado significa que o Playwright parou na inicialização com um erro.


## Como o endereço se encaixa no modelo do Playwright

- **Um contexto, um endereço:** Cada contexto de navegador pode ter o seu próprio IP estático, de um pedido próprio
- **Login em HTTP:** Campos username e password, aceitos por Chromium, Firefox e WebKit
- **Login em SOCKS5:** Apenas por endereço IPv4 na lista de permitidos, definida pela API ou pelo MCP
- **Estabilidade:** O IP permanece o mesmo entre execuções durante todo o período que você pagou

## O que dá errado com proxies no Playwright

### Credenciais na string do servidor

O Playwright lê usuário e senha de campos próprios. Se forem escritos na URL do servidor, não são enviados de forma alguma: no nosso teste, a primeira navegação travou até estourar o tempo limite, sem nenhuma mensagem que apontasse para as credenciais.

### Uma senha de SOCKS5

Todos os motores recusam a autenticação SOCKS5, e o erro surge na inicialização, antes de qualquer página abrir. A solução não é outra biblioteca: coloque na lista de IPs permitidos o IP de onde o seu script roda e retire as credenciais.

### Esperar que new_page mude o endereço

As páginas compartilham o proxy do contexto, e os contextos compartilham o do navegador, a menos que tenham um próprio. Para usar dois endereços lado a lado, crie dois contextos, cada um com o seu proxy.

### Pular a verificação de saída

Um erro de digitação na porta ou um proxy ainda em HTTP falha de forma evidente, mas um contexto criado sem o objeto proxy sai direto e em silêncio. Carregue uma página que mostre o IP uma vez para cada contexto que você configurar.


## Perguntas sobre proxies no Playwright

### Como configuro um proxy com autenticação no Playwright?

Passe um objeto com server, username e password, para launch ou para new_context. Com um proxy HTTP, Chromium, Firefox e WebKit enviam essas credenciais quando o proxy as solicita.

### Posso usar um proxy SOCKS5 com senha no Playwright?

Não. O Playwright para na inicialização com um erro dizendo que o navegador não oferece suporte à autenticação de proxy SOCKS5, nos três motores. Coloque na lista de IPs permitidos o IP de onde o seu script roda e passe apenas o servidor socks5; a nossa lista de IPs permitidos vale tanto em SOCKS5 quanto em HTTP.

### Como uso um proxy diferente para cada página?

Dê a cada contexto de navegador o seu próprio proxy e abra a página nesse contexto. As páginas de um mesmo contexto sempre compartilham o proxy dele, então um proxy por página significa um contexto por página.

### A configuração é a mesma em Python e em Node?

O mesmo objeto com os mesmos três campos: o Python o escreve como dicionário e o Node como objeto literal. Os dois exemplos desta página foram executados com o Playwright 1.64.

### Posso usar o proxy para scraping?

Testes das suas próprias páginas por região, verificações de qualidade, verificação de anúncios, pesquisa de preços e de mercado, monitoramento de SEO e proteção de marca podem ser feitos sem análise prévia conforme a nossa política de uso aceitável. A disponibilidade pública, por si só, não autoriza a coleta de dados, dados pessoais exigem uma base legal declarada, e a seção 5 da política proíbe usar o endereço em violação a CAPTCHAs, detecção de bots, limites de requisições ou bloqueios de contas.


Contextos e endereços estáticos se correspondem um a um: um contexto por mercado ou por tarefa, cada um chegando ao destino pelo mesmo IP, sem mudanças, a cada execução do script. Compre quantos endereços você tiver de contextos em [proxies ISP](/pt/isp-proxies/), compare os planos em [preços](/pt/pricing/) e baixe páginas sem navegador com o guia de [Python requests](/pt/integrations/python-requests/).



## Fontes

- [Playwright documentation, Network: HTTP proxy](https://playwright.dev/python/docs/network#http-proxy): a opção proxy na inicialização e por contexto
- [Playwright API, BrowserType.launch](https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch): os campos server, bypass, username e password
- [RFC 1929, Username/Password Authentication for SOCKS V5](https://www.rfc-editor.org/rfc/rfc1929): o login SOCKS5 que os navegadores não implementam




O Playwright controla Chromium, Firefox e WebKit com uma única API, e o proxy faz parte de como um navegador ou um contexto é criado. Isso facilita usar vários endereços em um mesmo script, e é também onde está o seu único limite rígido: SOCKS5 com senha.

## Proxy no Playwright com Python

O exemplo em Python inicia o Chromium com o proxy para o navegador inteiro; o exemplo por contexto o limita a um único contexto. Trocar de motor é trocar chromium por firefox ou webkit; o objeto proxy continua o mesmo.

## Autenticação de proxy no Playwright

Os três motores respondem ao 407 do proxy com o usuário e a senha do objeto proxy quando o proxy fala HTTP. Um proxy SOCKS5 não recebe essa resposta de nenhum deles, e é por isso que o exemplo de SOCKS5 não leva credenciais e depende da lista de IPs permitidos.

## Proxy por página no Playwright, e bypass

Não é possível anexar um proxy a uma única página. A unidade é o contexto: crie um contexto por endereço e abra dentro dele as páginas que devem compartilhar esse endereço. No Playwright, contextos são baratos, então um script que confere uma loja a partir de três países mantém três contextos, cada um construído a partir do seu próprio pedido.

O objeto proxy também aceita um campo bypass, uma lista de hosts separados por vírgula que devem ser acessados diretamente. Use-o para os seus serviços internos ou um servidor de testes local, de modo que apenas o tráfego destinado ao mundo externo saia pelo endereço que você paga.

