Selenium com proxy em Python: Chrome, Edge, senha e SOCKS5

O seu script do Selenium funciona, mas você precisa ver as páginas como um visitante na Alemanha as vê, ou a tarefa precisa rodar a partir de um servidor cujo IP o site já limita. Você adiciona um proxy e recebe uma página em branco, sem nenhum erro. A causa costuma ser a senha: o padrão WebDriver não tem campo para credenciais de proxy, então user:pass@host:port é recusado ou ignorado em silêncio.

Este guia cobre a configuração do proxy no Chrome, no Edge e no Firefox, os métodos de autenticação que funcionam hoje, SOCKS5, HTTPS, rotação e as mensagens de erro. Todos os exemplos em Python foram executados com Selenium 4.49, Chrome 154, Edge 153 e Firefox 156 no Windows 11, contra um proxy de teste local que exige usuário e senha.

O que é o Selenium?#

O Selenium controla um navegador de verdade a partir do código. É usado sobretudo para testar aplicações web, mas também para coletar dados de páginas que só aparecem com JavaScript. Ele abre páginas, clica, digita texto, envia formulários e lê o conteúdo da página como um usuário faria. O seu código chama a biblioteca do Selenium, a biblioteca conversa com um driver (ChromeDriver, msedgedriver ou geckodriver), e o driver controla o navegador pelo protocolo W3C WebDriver.

O Selenium aceita Chrome, Edge, Firefox e Safari, com bibliotecas oficiais para Python, Java, C#, Ruby e JavaScript. Desde a versão 4.6 ele vem com o Selenium Manager, que encontra o navegador instalado e baixa o driver correspondente. Ainda está escolhendo a ferramenta? Veja Playwright ou Selenium: qual escolher no seu projeto?

Como funciona um proxy no Selenium?#

No Selenium, o proxy pertence à sessão do navegador, não a uma requisição isolada:

1. Você coloca o proxy nas opções do navegador, como o argumento --proxy-server do Chrome ou como um objeto Proxy (a capability proxy do padrão WebDriver).
2. O driver inicia o navegador com essa configuração, que vale para todas as abas até driver.quit().
3. Para uma página https://, o navegador envia CONNECT host:443 ao proxy e abre um túnel criptografado. Para uma página http://, ele envia a URL completa ao proxy.
4. Se o proxy exige login, ele responde 407 Proxy Authentication Required. É justamente esta etapa que o padrão WebDriver não cobre.
5. O site de destino vê o IP de saída do proxy. Para usar outro proxy, você inicia um novo navegador.

O Chrome também manda o próprio tráfego de fundo (atualizações, serviços da conta) pelo proxy, e isso entra na conta de um plano cobrado por gigabyte.

Como usar o Selenium com proxy em Python?#

Passo 1: instale o Selenium. O Selenium 4.49 exige Python 3.10 ou mais recente:

pip install selenium

Passo 2: obtenha um servidor proxy. Escolha um produto na página de proxies; o Gerador de endpoints do painel da Proxynet entrega o endereço do gateway, a porta e um nome de usuário que já traz o país, a cidade e a sessão que você escolheu. HTTP e SOCKS5 usam portas separadas no mesmo gateway.

Passo 3: prepare o driver. A partir do Selenium 4.6, o Selenium Manager baixa sozinho o driver adequado na primeira execução. Baixar o ChromeDriver à mão e passar executable_path, como mandavam os guias antigos, não é mais necessário, e esse parâmetro nem existe no Selenium 4 atual. Se a máquina precisa de um proxy para chegar à internet, defina SE_PROXY para os downloads do Selenium Manager.

Passo 4: inicie o navegador com o proxy. Para um proxy que não pede senha (whitelist de IP, explicada abaixo):

from selenium import webdriver
from selenium.webdriver.common.by import By

PROXY = "http://pr.proxynet.io:8000"

options = webdriver.ChromeOptions()
options.add_argument(f"--proxy-server={PROXY}")
options.add_argument("--headless")  # remova para ver o navegador

driver = webdriver.Chrome(options=options)
try:
    driver.get("https://api.ipify.org/?format=json")
    print(driver.find_element(By.TAG_NAME, "body").text)  # {"ip": "<IP de saída>"}
finally:
    driver.quit()

No lugar de pr.proxynet.io:8000, coloque o host e a porta do seu painel da Proxynet. O IP impresso deve ser o IP de saída do proxy. O objeto Proxy do Selenium faz o mesmo trabalho (options.proxy = Proxy({"proxyType": ProxyType.MANUAL, "httpProxy": "host:port", "sslProxy": "host:port"})), e no nosso teste as duas formas encaminharam o tráfego do mesmo jeito.

Como usar um proxy com usuário e senha no Selenium?#

A definição de proxy do W3C WebDriver tem chaves para endereços de proxy, mas nenhuma para usuário ou senha, e a documentação de proxy do Chromium diz que o Chrome não usa credenciais embutidas nas configurações de proxy. Também não existe um argumento --proxy-auth no Chrome, embora ele apareça em exemplos antigos. Estes são os nossos testes contra um proxy que exige login:

A terceira linha é a perigosa: o script parece funcionar, mas o tráfego não passa pelo proxy.

Caminho 1: whitelist de IP#

Cadastre o IP público da máquina que roda o script na lista de IPs autorizados do painel da Proxynet, e o proxy para de pedir credenciais. O código do Passo 4 passa a funcionar sem mudanças, e o mesmo vale para as versões de Edge e Firefox. A Proxynet aceita até 10 IPs. Isso serve para um servidor com IP fixo, não para um notebook cujo IP muda; veja Autenticação de proxy: user:pass ou whitelist de IP.

Caminho 2: responder ao 407 pelo Chrome DevTools Protocol#

O Chrome e o Edge expõem o domínio Fetch do DevTools Protocol. Com handleAuthRequests ativado, o navegador pausa a requisição que precisa de credenciais e dispara Fetch.authRequired, cujo source é Server ou Proxy. A função auxiliar responde só aos desafios do proxy; o websocket-client já vem instalado com o Selenium.

# proxy_auth.py
import json
import threading
import urllib.request

import websocket  # instalado junto com o selenium (websocket-client)


def attach_proxy_auth(driver, username, password):
    """Responde aos desafios 407 do proxy nesta aba pelo Chrome DevTools Protocol."""
    caps = driver.capabilities
    vendor = caps.get("goog:chromeOptions") or caps.get("ms:edgeOptions")  # Chrome ou Edge
    address = vendor["debuggerAddress"]
    with urllib.request.urlopen(f"http://{address}/json") as resp:
        targets = json.load(resp)
    page = next(t for t in targets if t["type"] == "page")
    ws = websocket.create_connection(page["webSocketDebuggerUrl"], suppress_origin=True)

    counter = {"id": 0}

    def send(method, params=None):
        counter["id"] += 1
        ws.send(json.dumps({"id": counter["id"], "method": method, "params": params or {}}))

    def listen():
        while True:
            try:
                msg = json.loads(ws.recv())
            except Exception:
                return  # o navegador foi fechado
            method = msg.get("method")
            params = msg.get("params", {})
            if method == "Fetch.requestPaused":
                send("Fetch.continueRequest", {"requestId": params["requestId"]})
            elif method == "Fetch.authRequired":
                if params["authChallenge"]["source"] == "Proxy":
                    answer = {"response": "ProvideCredentials",
                              "username": username, "password": password}
                else:
                    answer = {"response": "Default"}  # o login do próprio site não é respondido aqui
                send("Fetch.continueWithAuth", {"requestId": params["requestId"],
                                                "authChallengeResponse": answer})

    send("Fetch.enable", {"handleAuthRequests": True})
    while json.loads(ws.recv()).get("id") != counter["id"]:
        pass  # espera a interceptação ficar ativa antes do primeiro driver.get()
    threading.Thread(target=listen, daemon=True).start()
    return ws

Para usar, basta uma linha depois que o driver inicia:

from selenium import webdriver
from proxy_auth import attach_proxy_auth

options = webdriver.ChromeOptions()
options.add_argument("--proxy-server=http://pr.proxynet.io:8000")
driver = webdriver.Chrome(options=options)
attach_proxy_auth(driver, "user", "pass")
driver.get("https://api.ipify.org/?format=json")

Limites: a função auxiliar cobre só a aba à qual se conectou, então uma janela nova começa sem ela. Com uma senha errada, o Chrome mostra ERR_TOO_MANY_RETRIES.

E o Selenium Wire e as extensões de proxy?#

O repositório do Selenium Wire foi arquivado em 3 de janeiro de 2024, e num ambiente limpo de Python 3.13 o from seleniumwire import webdriver falhou no nosso teste com ModuleNotFoundError: No module named 'pkg_resources'. As extensões de autenticação dependiam da opção --load-extension, que as versões oficiais do Chrome ignoram a partir da 137; só o Chrome for Testing e o Chromium ainda a aceitam. O SeleniumBase aceita proxy="user:pass@host:port" e cuida do login sozinho; veja Proxy com SeleniumBase: autenticação e rotação.

Qual método de proxy usar no Selenium?#

Como configurar um proxy no Microsoft Edge com Selenium?#

O Edge é baseado no Chromium, então o EdgeOptions aceita o mesmo argumento, e o Selenium Manager baixa o msedgedriver:

from selenium import webdriver

options = webdriver.EdgeOptions()
options.add_argument("--proxy-server=http://pr.proxynet.io:8000")
driver = webdriver.Edge(options=options)

A função auxiliar CDP também funciona com o Edge: com o Edge 153 e o proxy de teste protegido por senha, a página carregou pelo proxy.

Como configurar um proxy no Selenium com Firefox?#

O Firefox não lê --proxy-server. Defina as preferências de rede dele ou passe o objeto Proxy, que o geckodriver converte nas mesmas preferências. O Firefox não estava instalado na nossa máquina de teste; o Selenium Manager baixou o Firefox 156 na primeira execução.

from selenium import webdriver

options = webdriver.FirefoxOptions()
options.set_preference("network.proxy.type", 1)  # 1 = configuração manual
options.set_preference("network.proxy.http", "pr.proxynet.io")
options.set_preference("network.proxy.http_port", 8000)
options.set_preference("network.proxy.ssl", "pr.proxynet.io")  # usado para páginas https://
options.set_preference("network.proxy.ssl_port", 8000)
driver = webdriver.Firefox(options=options)

Para SOCKS5, defina network.proxy.socks e network.proxy.socks_port e coloque network.proxy.socks_version em 5. O Firefox então envia o nome de domínio ao proxy, porque network.proxy.socks5_remote_dns vem ativada por padrão. A antiga network.proxy.socks_remote_dns, que ainda aparece em muitos tutoriais, não fez diferença para SOCKS5 no Firefox 156, enquanto definir socks5_remote_dns como False fez o Firefox resolver os nomes localmente. O Firefox não tem preferência para credenciais de proxy, e a função auxiliar CDP não se aplica a ele. O add_auth_handler do BiDi do Selenium chegou a enviar as nossas credenciais, mas o carregamento da página ainda falhou com UnexpectedAlertPresentException por causa da janela de login do proxy; por isso, use uma whitelist de IP.

O Selenium funciona com proxy SOCKS5?#

Sim, sem senha: --proxy-server=socks5://host:port. No nosso teste, o Chrome enviou o nome de domínio ao proxy em vez de resolvê-lo localmente; a documentação do Chromium confirma que, com SOCKS5, a resolução de nomes sempre acontece do lado do proxy.

Com senha, não: o Chromium não tem suporte a autenticação SOCKS5, e o driver.get() gerou net::ERR_SOCKS_CONNECTION_FAILED. A função auxiliar CDP não ajuda aqui, porque o SOCKS não tem um 407 para responder. Use a porta SOCKS5 com whitelist, ou a porta HTTP com a função auxiliar. Mais detalhes em Proxy SOCKS5: o que é, como funciona e SOCKS4 vs SOCKS5 e Diferença entre SOCKS e HTTP proxy; os Proxies SOCKS5 da Proxynet rodam numa porta própria do mesmo gateway.

O Selenium funciona com sites HTTPS através de um proxy?#

Sim. O endereço do proxy mantém o esquema http:// mesmo quando todas as páginas são https://: o navegador abre um túnel CONNECT, e o TLS vai de ponta a ponta entre o navegador e o site, então o proxy vê o nome do host, mas não o conteúdo. É por isso que um objeto Proxy precisa de sslProxy além de httpProxy; só com httpProxy, as nossas páginas https:// saíram direto, sem passar pelo proxy.

Um esquema https:// em --proxy-server criptografa a conexão com o próprio proxy; veja Proxies HTTPS.

Como integrar proxies ao Selenium com Java?#

O Java usa o mesmo objeto Proxy. Colocar user:pass@ em setHttpProxy, como fazem alguns exemplos antigos, fez o Chrome ignorar o proxy no nosso teste; por isso, usuário e senha não entram no endereço do proxy, e a versão abaixo depende de uma whitelist de IP. Também não há System.setProperty("webdriver.chrome.driver", …), porque o Selenium Manager encontra o driver. O Selenium 4 exige Java 11 ou mais recente.

import org.openqa.selenium.Proxy;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;

public class SeleniumProxyExample {
    public static void main(String[] args) {
        // Sem credenciais aqui: o IP da máquina está na whitelist do proxy
        String proxyAddress = "pr.proxynet.io:8000";

        Proxy proxy = new Proxy();
        proxy.setHttpProxy(proxyAddress);
        proxy.setSslProxy(proxyAddress);

        ChromeOptions options = new ChromeOptions();
        options.setProxy(proxy);

        // O Selenium Manager encontra ou baixa o ChromeDriver correspondente
        WebDriver driver = new ChromeDriver(options);
        try {
            driver.get("https://api.ipify.org/?format=json");
            System.out.println(driver.getPageSource());
        } finally {
            driver.quit();
        }
    }
}

options.addArguments("--proxy-server=http://pr.proxynet.io:8000") é o equivalente do argumento em Python. Escrevemos este exemplo com base na documentação do Selenium e não o executamos, porque a máquina de teste só tem Java 8.

Como rotacionar proxies residenciais no Selenium?#

O proxy fica fixo durante toda a vida do navegador, então rotacionar significa iniciar um navegador novo:

• Gateway rotativo. Com Proxies rotativos, o IP de saída muda do lado do gateway e o seu código mantém um único endereço. As conexões de um mesmo carregamento de página podem sair por IPs diferentes: tudo bem para listas de produtos, um problema para um fluxo de login.
• Sessões fixas. Com Proxies de sessão fixa, o IP continua o mesmo por 1 a 60 minutos. Dê a cada navegador o próprio nome de usuário de sessão, gerado no Gerador de endpoints: um navegador, uma sessão, um IP de saída.

Os dois modos funcionam com os Proxies residenciais; veja O que é rotação de IP e como ela funciona? e Como rotacionar proxies em Python.

Em automação, a origem do endereço pesa na taxa de sucesso: IPs residenciais servem para alvos com verificação rigorosa, e os Proxies de datacenter dão conta de coletas rápidas em sites pouco exigentes. Se o endereço não pode mudar no meio de um fluxo que dura mais do que uma sessão fixa, use Proxies ISP.

Exemplo completo: navegadores em paralelo com novas tentativas#

O script lê seis páginas renderizadas com JavaScript do quotes.toscrape.com, um site feito para treino. Ele roda três instâncias do Chrome ao mesmo tempo, inicia um navegador novo a cada tentativa, bloqueia imagens para economizar tráfego e repete as falhas temporárias com espera crescente. Erros que uma nova tentativa não resolve encerram a tarefa na hora, inclusive os que só aparecem na página de erro do Chrome.

import random
import re
import time
from concurrent.futures import ThreadPoolExecutor, as_completed

from selenium import webdriver
from selenium.common.exceptions import TimeoutException, WebDriverException
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait

from proxy_auth import attach_proxy_auth

PROXY_SERVER = "http://pr.proxynet.io:8000"
PROXY_USER = "user"
PROXY_PASS = "pass"
URLS = [f"https://quotes.toscrape.com/js/page/{n}/" for n in range(1, 7)]
WORKERS = 3  # navegadores abertos ao mesmo tempo
ATTEMPTS = 3
# Uma nova tentativa não resolve estes erros: confira antes o endereço, a porta e as credenciais
FATAL = ("ERR_PROXY_CONNECTION_FAILED", "ERR_NO_SUPPORTED_PROXIES",
         "ERR_SOCKS_CONNECTION_FAILED", "ERR_TOO_MANY_RETRIES")


def new_driver():
    options = webdriver.ChromeOptions()
    options.add_argument(f"--proxy-server={PROXY_SERVER}")
    options.add_argument("--headless")
    # Sem imagens: menos tráfego pelo proxy
    options.add_experimental_option("prefs", {"profile.managed_default_content_settings.images": 2})
    driver = webdriver.Chrome(options=options)
    driver.set_page_load_timeout(30)
    attach_proxy_auth(driver, PROXY_USER, PROXY_PASS)
    return driver


def scrape(url):
    for attempt in range(ATTEMPTS):
        driver = new_driver()  # um navegador novo, e uma nova conexão com o proxy, a cada tentativa
        try:
            driver.get(url)
            # Alguns erros de proxy abrem a página de erro do Chrome sem gerar exceção
            if driver.execute_script("return document.body.className") == "neterror":
                code = re.search(r"ERR_[A-Z_]+", driver.page_source)
                raise WebDriverException(code.group(0) if code else "Chrome error page")
            WebDriverWait(driver, 10).until(
                EC.presence_of_element_located((By.CSS_SELECTOR, "div.quote span.text"))
            )
            quotes = driver.find_elements(By.CSS_SELECTOR, "div.quote span.text")
            return url, [q.text for q in quotes]
        except (TimeoutException, WebDriverException) as exc:
            if any(code in str(exc) for code in FATAL) or attempt == ATTEMPTS - 1:
                raise
            time.sleep(2**attempt + random.random())  # espera exponencial com variação aleatória
        finally:
            driver.quit()


with ThreadPoolExecutor(max_workers=WORKERS) as pool:
    futures = [pool.submit(scrape, url) for url in URLS]
    for future in as_completed(futures):
        try:
            url, quotes = future.result()
            print(f"{url}: {len(quotes)} quotes")
        except Exception as exc:
            print("failed:", str(exc).splitlines()[0])

As seis páginas retornaram 10 citações cada, em cerca de 22 segundos; uma porta fechada encerrou todas as tarefas com net::ERR_PROXY_CONNECTION_FAILED, e uma senha errada, com ERR_TOO_MANY_RETRIES. Mantenha o número de workers baixo: cada worker é um Chrome completo, e sessões paralelas demais levam ao erro 429 Too Many Requests.

Como verificar se o Selenium está mesmo usando o proxy?#

Abra no navegador com proxy uma página que devolve o seu IP, como api.ipify.org, e compare com o seu próprio IP; se forem iguais, o tráfego não está passando pelo proxy. O painel da Proxynet também deve mostrar o consumo. O WebRTC ainda pode revelar o IP local; veja Vazamentos de WebRTC e DNS: o que são e como evitar. Uma rotina completa está em Como testar um proxy, e uma verificação de uma linha no terminal, em cURL com proxy.

Erros comuns de proxy no Selenium e como resolver#

As mensagens abaixo vêm dos nossos testes. Os códigos do Chrome aparecem na exceção (unknown error: net::ERR_…) ou só na página de erro.

Os erros de conexão dos clientes HTTP comuns do Python são explicados linha por linha em Max Retries Exceeded With URL: o que é e como resolver.

Casos de uso#

• Monitoramento de preços em lojas cheias de JavaScript, a partir do mercado em que você vende: veja como monitorar preços da concorrência e a página de monitoramento de preços.
• Localização e QA: carregar o seu próprio site a partir de vários países antes de um lançamento; veja testes de aplicativos.
• Verificação de anúncios: conferir os seus anúncios nas regiões pelas quais você paga; veja verificação de anúncios.
• Coleta de dados em páginas que só funcionam com JavaScript; veja extração de dados.

Um proxy muda de onde a requisição vem, não o que o site permite: leia o robots.txt e os termos do site, mantenha a taxa de requisições baixa e prefira uma API oficial quando ela existir. O proxy também não esconde a automação: um navegador sob controle do WebDriver informa navigator.webdriver como true, como o padrão exige.

Guia de decisão#

Perguntas frequentes#

O Selenium consegue usar um proxy com usuário e senha?#

Não pelas opções padrão, que não têm campos para credenciais. No Chrome e no Edge, a função auxiliar do DevTools mostrada neste post responde ao 407 do proxy; em qualquer navegador, uma whitelist de IP dispensa a senha.

O Selenium Wire ainda funciona em 2026?#

Ele foi arquivado em 3 de janeiro de 2024 e, num ambiente limpo de Python 3.13, nem chegou a ser importado no nosso teste, porque depende do pkg_resources, que as versões atuais do setuptools não trazem mais. Use a função auxiliar ou uma whitelist.

Como trocar o proxy sem reiniciar o navegador?#

O proxy é definido quando a sessão começa: chame driver.quit() e inicie um novo driver. Para ter um IP novo por página dentro do mesmo navegador, use um gateway rotativo, ou o Playwright, que aceita um proxy por contexto.

O proxy funciona no modo headless?#

Sim. O --proxy-server e a função auxiliar CDP se comportam do mesmo jeito com e sem --headless; todos os exemplos deste post rodaram em modo headless.

Dá para usar um proxy SOCKS5 com autenticação no Selenium?#

Não no Chrome nem no Edge, que não têm suporte a autenticação SOCKS5; o Firefox 156 também só ofereceu ao nosso proxy o método sem senha. Use SOCKS5 com whitelist, ou a porta HTTP com senha.

Por que o site ainda mostra o meu IP real?#

Em geral, o proxy nunca chegou a ser aplicado: credenciais dentro do objeto Proxy fazem o Chrome se conectar direto, e um objeto Proxy sem sslProxy deixa as páginas https:// fora do proxy. Se o IP está certo, mas a localização parece errada, teste se há vazamento de WebRTC.

Em resumo#

O Selenium define o proxy uma vez por sessão do navegador: --proxy-server no Chrome e no Edge, preferências ou o objeto Proxy no Firefox. Para autenticação, use uma whitelist de IP ou, no Chrome e no Edge, a função auxiliar do DevTools que responde ao 407; o Selenium Wire e as extensões carregadas pela linha de comando são becos sem saída. O SOCKS5 só funciona sem senha, e rotacionar significa um navegador por IP ou por sessão. Com a configuração pronta, escolha um plano na página de proxies da Proxynet e pegue os dados do gateway no Gerador de endpoints.