Guia de Proxy para Python Requests: Sintaxe, Autenticação, Rotação, Repetições

O dicionário de proxies é apenas três linhas de código, mas erros de proxy no Requests preenchem uma década de Stack Overflow. Aqui está a configuração completa — sintaxe, autenticação, variáveis de ambiente, rotação, repetições e SOCKS5 — com as arestas afiadas rotuladas.

Python Requests ainda é o cliente HTTP padrão para scraping e automação, e apontá-lo para um proxy é um trabalho de três linhas: passe um dicionário de proxies e cada requisição sai do IP do proxy em vez do seu. No entanto, 'python requests proxy não funciona' permaneceu uma das principais buscas por mais de uma década — a pergunta original no Stack Overflow sobre o dicionário de proxies data de 2011, sua resposta principal tem mais de 480 votos, e ainda estava sendo editada em janeiro de 2026. A sintaxe tem arestas afiadas: um esquema ausente levanta uma exceção, o esquema errado dentro da chave https aciona erros de SSL, e variáveis de ambiente substituem o código silenciosamente. Este guia de proxy para Python Requests cobre tudo isso: sintaxe, autenticação, variáveis de ambiente, rotação, repetições, SOCKS5 e os erros que você realmente enfrentará.

O dicionário de proxies: sintaxe de proxy para Python Requests

O argumento proxies mapeia um protocolo para uma URL de proxy. Duas chaves cobrem o scraping normal — uma para alvos HTTP simples, outra para alvos HTTPS — e ambas geralmente apontam para o mesmo proxy:

import requests

proxies = {
    "http": "http://USER:PASS@gate.quantumproxies.io:PORT",
    "https": "http://USER:PASS@gate.quantumproxies.io:PORT",
}

r = requests.get("https://httpbin.org/ip", proxies=proxies, timeout=(5, 30))
print(r.json())  # {'origin': '<proxy exit IP>'}

Três regras evitam 90% das falhas de configuração:

• O esquema é obrigatório. Desde o Requests 2.0.0, uma URL de proxy sem http:// levanta MissingSchema. Strings simples ip:port funcionavam na versão 1.x e quebraram em todos os lugares quando a versão 2.0 foi lançada.
• Use http:// dentro da chave https. A chave nomeia o protocolo de destino; o valor nomeia como você alcança o proxy. Proxies aceitam HTTP simples e fazem túnel TLS através de uma requisição CONNECT. Escrever https:// lá é a causa clássica de SSLError: UNEXPECTED_EOF_WHILE_READING.
• Chaves podem direcionar hosts específicos. Uma chave como https://api.example.com roteia apenas aquele host através de um determinado proxy — útil para enviar um domínio difícil através de IPs residenciais enquanto o restante vai direto.

Autenticação de proxy: nome de usuário e senha

Proxies autenticados usam autenticação HTTP Básica embutida na URL: http://USER:PASS@host:port. Se a senha contiver @, : ou /, codifique a URL primeiro com urllib.parse.quote(password, safe="") — caracteres especiais não codificados dividem a URL no lugar errado e produzem falhas de autenticação que parecem proxies inativos. Uma resposta 407 Proxy Authentication Required significa que o próprio proxy o rejeitou: credenciais erradas ou um plano de lista de IPs permitidos chamado de um endereço não registrado. Ambos os casos são dissecados em nosso guia de solução de problemas 407. Para qualquer coisa além de um script único, anexe os proxies a uma Session — você obtém agrupamento de conexões, persistência de cookies e um lugar para configurar tudo:

import requests

session = requests.Session()
session.proxies = {
    "http": "http://USER:PASS@gate.quantumproxies.io:PORT",
    "https": "http://USER:PASS@gate.quantumproxies.io:PORT",
}
session.headers.update({"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"})

r = session.get("https://httpbin.org/ip", timeout=(5, 30))
print(r.status_code, r.json())

Variáveis de ambiente e trust_env

Requests também lê configurações de proxy do ambiente — as mesmas variáveis que curl e a maioria das ferramentas Unix respeitam: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY e NO_PROXY (uma lista de hosts a excluir, por exemplo, localhost,127.0.0.1,.internal). Esta é a maneira mais limpa de fazer proxy de uma biblioteca de terceiros que usa Requests internamente sem tocar em seu código. A precedência é explícita sobre implícita: um argumento proxies= na chamada vence, depois session.proxies, depois o ambiente. Duas ferramentas relacionadas valem a pena conhecer: session.trust_env = False desativa toda a busca no ambiente — a solução quando uma variável de proxy corporativa sequestra seu scraper — e urllib.request.getproxies() retorna configurações de proxy a nível de SO (incluindo configuração de sistema macOS e Windows) exatamente no formato de dicionário que Requests espera.

Rotação: um gateway supera uma lista de proxies

A receita tradicional de rotação — carregar uma lista de IPs, random.choice() por requisição, eliminar os inativos — é uma máquina que você não precisa mais construir. Um gateway rotativo faz isso no lado do servidor: você configura um endpoint e o provedor atribui um novo IP de saída do pool a cada requisição. Através de proxies residenciais rotativos, esse pool é de mais de 90 milhões de IPs domésticos em mais de 200 países, então mil requisições parecem mil visitantes diferentes sem uma única linha de lógica de rotação:

import requests

proxies = {
    "http": "http://USER:PASS@gate.quantumproxies.io:PORT",
    "https": "http://USER:PASS@gate.quantumproxies.io:PORT",
}

for _ in range(3):
    r = requests.get("https://httpbin.org/ip", proxies=proxies, timeout=(5, 30))
    print(r.json()["origin"])  # a different exit IP on each iteration

Quando um fluxo abrange várias requisições — login, adicionar ao carrinho, finalizar compra — a rotação por requisição quebra a sessão. Sessões persistentes resolvem isso: um parâmetro de sessão no nome de usuário do proxy fixa um IP de saída por uma janela definida, depois gira. Mesmo endpoint, uma mudança de string. Se você está escalando além de loops simples, Python assíncrono com httpx ou aiohttp multiplica o throughput, e o sistema de middleware do Scrapy oferece rotação, repetições e tratamento de banimentos como configuração de framework.

Repetições e timeouts que sobrevivem a saídas ruins

Mesmo pools premium servem ocasionalmente uma saída lenta ou moribunda, então o código de produção precisa de duas proteções: um timeout em cada requisição (Requests por padrão espera para sempre) e repetições automáticas com backoff. O timeout leva uma tupla (connect, read) — falha rapidamente em proxies inalcançáveis, permite leituras de página mais lentas. As repetições são montadas na camada de transporte via urllib3:

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

retry = Retry(
    total=4,
    backoff_factor=1,  # exponential backoff between attempts
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["GET", "HEAD"],
)

session = requests.Session()
session.mount("http://", HTTPAdapter(max_retries=retry))
session.mount("https://", HTTPAdapter(max_retries=retry))
session.proxies = {
    "http": "http://USER:PASS@gate.quantumproxies.io:PORT",
    "https": "http://USER:PASS@gate.quantumproxies.io:PORT",
}

r = session.get("https://httpbin.org/ip", timeout=(5, 30))

Com um gateway rotativo, essa combinação é silenciosamente poderosa: cada repetição viaja automaticamente através de um IP de saída diferente, então um endereço instável nunca pode falhar uma requisição quatro vezes seguidas.

Proxies SOCKS5 com Requests

O suporte a SOCKS é um extra: instale-o com pip install requests[socks]. Então a sintaxe do dicionário é idêntica — apenas o esquema muda. Prefira socks5h:// sobre socks5://: o h empurra a resolução DNS para o proxy, o que impede vazamentos de DNS da sua rede real e resolve nomes de host geograficamente restritos a partir da localização da saída. Cada plano da QuantumProxies expõe tanto proxies HTTP quanto proxies SOCKS5 no mesmo gateway, então trocar protocolos é uma troca de esquema, não uma nova compra:

proxies = {
    "http": "socks5h://USER:PASS@gate.quantumproxies.io:PORT",
    "https": "socks5h://USER:PASS@gate.quantumproxies.io:PORT",
}

Erros comuns de proxy para Python Requests, decodificados

• MissingSchema — URL de proxy sem http://. Obrigatório desde o Requests 2.0.0.
• ProxyError: Cannot connect to proxy — host ou porta errados, ou um proxy inativo. Verifique o endpoint com curl antes de culpar seu código.
• SSLError / UNEXPECTED_EOF_WHILE_READING — geralmente https:// dentro da chave https. Defina o esquema do valor para http://.
• 407 Proxy Authentication Required — credenciais ruins, caracteres especiais não codificados na senha ou um IP de origem não permitido.
• ConnectTimeout / ReadTimeout — saída lenta ou alvo lento. Defina timeout=(5, 30) e deixe as repetições girarem para um novo IP.
• Proxy funciona no curl, falha no Python — uma variável de ambiente está substituindo seu dicionário. Imprima session.proxies e tente trust_env = False.

Para uma análise mais profunda das rastreabilidades e suas causas raízes, veja debugging ProxyError, SSLError e ConnectTimeout no Requests.

Perguntas frequentes

Como uso um proxy com Python Requests?

Passe um dicionário proxies com chaves http e https para qualquer método de requisição: requests.get(url, proxies={...}). Cada valor é uma URL de proxy completa incluindo esquema, e credenciais são embutidas como http://user:pass@host:port. Anexe o mesmo dicionário a uma Session para aplicá-lo automaticamente a cada requisição.

Por que meu proxy para Python Requests não está funcionando?

Verifique os quatro suspeitos usuais na ordem: um esquema http:// ausente na URL do proxy, https:// usado dentro da chave https, caracteres especiais na senha que não foram codificados na URL e variáveis de ambiente substituindo seu código. Teste as mesmas credenciais com curl — se curl tiver sucesso, o problema está no seu dicionário.

O Python Requests suporta proxies SOCKS5?

Sim, após instalar a dependência extra com pip install requests[socks]. Use o esquema socks5h:// no seu dicionário de proxies para que a resolução DNS aconteça no lado do proxy — o esquema simples socks5:// resolve nomes de host localmente, o que vaza consultas DNS e pode quebrar scraping geograficamente direcionado.

Como configuro um proxy com variáveis de ambiente?

Exporte HTTP_PROXY e HTTPS_PROXY com a URL completa do proxy, e opcionalmente NO_PROXY para hosts a excluir. Requests os capta automaticamente, o que também faz proxy de bibliotecas de terceiros construídas sobre Requests. Para fazer seu código ignorar completamente o ambiente, defina session.trust_env = False.

Esse é o kit de ferramentas completo: um dicionário de duas chaves, credenciais na URL, repetições montadas uma vez e rotação tratada pelo gateway em vez do seu código. A única coisa que nenhuma sintaxe corrige é a qualidade do IP — um proxy de datacenter perfeitamente configurado ainda é bloqueado onde uma saída residencial passa tranquilamente. Combine código limpo com IPs limpos e Requests suportará cargas surpreendentemente grandes.

Obtenha proxies residenciais que funcionam na primeira tentativa