Como Usar um Proxy com cURL (-x, Autenticação, SOCKS5 e Rotação)
Você está no terminal e precisa de um único comando para rotear uma requisição cURL por um proxy, agora mesmo, copiar e colar. Este guia entrega exatamente isso: as flags de proxy do curl, os três protocolos, autenticação, variáveis de ambiente, uma configuração permanente, rotação e uma tabela real de erro-para-correção - testada no curl 8.x em agosto de 2026. Sem enrolação e sem funil de vendas de fornecedor. Se você já conhece o cURL e só quer a sintaxe de proxy mais as pegadinhas que as outras páginas pulam, você está no lugar certo.
Última atualização: 24 de agosto de 2026. Testado no curl 8.x; essas flags têm se mantido estáveis nas versões recentes do curl, mas rode curl --version para confirmar a sua.
TL;DR: o comando de uma linha
Passe seu proxy ao cURL com -x (ou seu gêmeo idêntico --proxy):
curl -x http://USER:PASS@HOST:PORT https://example.com-x e --proxy são a mesma flag. Se você omitir o scheme, o cURL assume http://; se omitir a porta, ele assume 1080. Todo comando abaixo é uma variação daquela única linha.
O que você precisa antes de começar
Para rodar qualquer comando aqui, você precisa de quatro valores, que todo provedor de proxy entrega no painel dele:
HOST:PORT # the endpoint, e.g. p.webshare.io:80
USERNAME:PASSWORD # your proxy credentialsEsses quatro valores são tudo o que o cURL precisa. Se você não tem um endpoint ativo para testar, consiga um antes de continuar lendo - os comandos não valem nada sem um proxy de verdade por trás deles. A Webshare tem um plano gratuito genuíno (10 proxies, sem cartão) que é rápido de obter exatamente para esse tipo de teste, e ela entrega uma string simples host:port:user:pass que cai direto no -x. Você pode pegar proxies gratuitos para testar em poucos minutos. (A Webshare é parceira de afiliados; veja nossa divulgação de afiliados. Isso não muda nem o preço que você paga nem os comandos abaixo.)
Nos meus próprios testes com curl, eu colo o endpoint de sticky-session direto do painel da Webshare em vez de montar à mão uma linha de gateway rotativo, então host, porta e credenciais vêm como uma única string pronta que cai no -x. Não fixei isso em uma versão específica do curl - qualquer curl razoavelmente recente lida com essas flags do mesmo jeito - então use o que vem com o seu sistema.
Sintaxe básica de proxy no cURL: a flag -x / --proxy
As duas formas são intercambiáveis, então escolha a que você conseguir lembrar:
# These two lines are identical
curl -x http://HOST:PORT https://example.com
curl --proxy http://HOST:PORT https://example.comO cURL preenche dois padrões que surpreendem as pessoas. Omita o scheme e ele assume um proxy HTTP; omita a porta e ele assume 1080:
# No scheme -> HTTP proxy is assumed
curl -x HOST:PORT https://example.com
# No port -> 1080 is assumed (so this targets HOST:1080)
curl -x http://HOST https://example.comSeja explícito em scripts. Escrever o http://HOST:PORT completo evita a surpresa "por que está batendo na porta 1080?" mais tarde.
Proxies HTTP, HTTPS e SOCKS5 com cURL
O scheme na frente de HOST:PORT diz ao cURL como falar com o proxy. Isso é separado de a sua URL alvo ser https ou não.
| Tipo de proxy | Exemplo de flag |
|---|---|
| Proxy HTTP | -x http://HOST:PORT |
| Proxy HTTPS (TLS até o proxy) | -x https://HOST:PORT |
| SOCKS5, DNS local | -x socks5://HOST:PORT |
| SOCKS5, DNS remoto | -x socks5h://HOST:PORT |
Proxies HTTP e HTTPS
# Reach an https site through a plain HTTP proxy - this is normal
curl -x http://HOST:PORT https://example.com
# Proxy that itself speaks TLS
curl -x https://HOST:PORT https://example.comRepare nos dois níveis de TLS. http:// vs https:// no valor do -x descreve o salto de você até o proxy; o https:// na URL alvo é o salto do proxy até o site. A maioria dos proxies de datacenter usa um scheme http:// mesmo quando você está buscando páginas https, então comece por aí.
SOCKS5 e a distinção entre socks5:// e socks5h://
curl -x socks5://HOST:PORT https://example.com
curl --socks5 HOST:PORT https://example.com # same thing
# Let the PROXY resolve the hostname (remote DNS)
curl -x socks5h://HOST:PORT https://example.comAqui está o detalhe que a maioria dos guias pula. Com socks5://, o cURL resolve o hostname alvo na sua máquina e envia ao proxy um endereço IP. Com socks5h://, o cURL envia o hostname e o proxy faz a consulta DNS. Use socks5h:// sempre que quiser que o DNS aconteça na saída, por exemplo para evitar vazamentos de DNS local ou para resolver um nome que só existe na rede do proxy.
Autenticação de proxy no cURL (-U / --proxy-user)
A maioria dos proxies pagos exige um nome de usuário e uma senha. Duas formas de fornecê-los:
# Dedicated flag (-U is short for --proxy-user)
curl -x http://HOST:PORT -U USER:PASS https://example.com
curl -x http://HOST:PORT --proxy-user USER:PASS https://example.com
# Credentials embedded in the proxy URL
curl -x http://USER:PASS@HOST:PORT https://example.comA pegadinha que causa a maioria dos erros 407: quando você embute as credenciais na URL, qualquer caractere especial na senha precisa ser codificado em URL, ou o cURL lê a string errado e o proxy te rejeita. Codifique @ como %40, : como %3A, # como %23, e assim por diante:
# Password is p@ss:word -> encode it in the URL
curl -x "http://user:p%40ss%3Aword@HOST:PORT" https://example.com
# Or sidestep encoding entirely with -U (quote it for the shell)
curl -x http://HOST:PORT -U 'user:p@ss:word' https://example.comA forma -U só divide no primeiro dois-pontos, então um dois-pontos dentro da senha não é problema ali. --proxy-user também funciona para autenticação SOCKS5, não só HTTP.
Definir um proxy com variáveis de ambiente (HTTP_PROXY / HTTPS_PROXY)
Defina o proxy uma vez no seu shell e toda chamada cURL naquela sessão o usa. A sintaxe difere por shell, que é onde os tutoriais multiplataforma costumam errar.
# Unix / macOS (bash, zsh)
export http_proxy="http://USER:PASS@HOST:PORT"
export https_proxy="http://USER:PASS@HOST:PORT"
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"
curl https://example.com# Windows PowerShell (curl is an alias here - call curl.exe)
$env:HTTP_PROXY = "http://USER:PASS@HOST:PORT"
$env:HTTPS_PROXY = "http://USER:PASS@HOST:PORT"
curl.exe https://example.com:: Windows cmd.exe
set HTTP_PROXY=http://USER:PASS@HOST:PORT
set HTTPS_PROXY=http://USER:PASS@HOST:PORT
curl https://example.comDuas coisas para saber. Para a variável HTTP simples, o cURL lê apenas a minúscula http_proxy (uma escolha de segurança deliberada); HTTPS_PROXY e NO_PROXY funcionam em qualquer caixa. E NO_PROXY (ou a flag --noproxy por chamada) lista os hosts que devem contornar o proxy. Um -x por requisição sempre sobrescreve o que o ambiente definiu:
# Ignore the env proxy for these hosts
curl --noproxy example.com,localhost https://example.com
# -x wins over the environment variables for this one call
curl -x http://OTHER_HOST:PORT https://example.comFazer o cURL sempre usar um proxy (.curlrc)
Para um proxy que você usa o tempo todo, coloque-o no arquivo de configuração do cURL para nunca mais digitar a flag. No Unix e no macOS isso é ~/.curlrc; no Windows é _curlrc no seu diretório home ou em %APPDATA%\_curlrc. Adicione uma linha:
# ~/.curlrc (or %APPDATA%\_curlrc on Windows)
proxy = "http://USER:PASS@HOST:PORT"Agora todo comando cURL passa por aquele proxy automaticamente. Para contorná-lo em uma única chamada sem editar o arquivo, desative o proxy na própria linha:
curl --noproxy '*' https://example.com # ignore the config proxy
curl -x '' https://example.com # empty proxy = direct connectionRotacionar proxies por requisição
Dois padrões honestos cobrem quase toda necessidade de rotação. O primeiro usa o gateway rotativo de um provedor - um único endpoint que te entrega um novo IP de saída a cada requisição, então você só o chama em um laço:
# Rotating gateway endpoint (Webshare exposes one at p.webshare.io:80;
# check your dashboard for the exact host and rotation setting)
for i in $(seq 1 5); do
curl -s -x http://USER:[email protected]:80 https://ipinfo.io/ip
doneO segundo te dá controle total percorrendo o seu próprio arquivo de lista de proxies, um -x por linha. A Webshare e a maioria dos provedores deixam você exportar a lista no formato host:port:user:pass, que faz o parse de forma limpa:
# proxies.txt: one host:port:user:pass per line
while IFS=: read -r host port user pass; do
curl -s -x "http://$user:$pass@$host:$port" https://ipinfo.io/ip
done < proxies.txtFaça scraping com responsabilidade. Puxe apenas dados públicos, respeite o robots.txt e os termos de serviço de cada site, controle a sua taxa de requisições e fique longe de qualquer coisa atrás de um login. Isso é boa prática, não aconselhamento jurídico - verifique as regras do seu próprio projeto e jurisdição. Se a rotação é o coração do seu fluxo de trabalho, nossos guias sobre proxies rotativos e proxies para web scraping vão mais fundo do que um trecho de código consegue.
Verificar se o cURL está usando o proxy (confira seu IP)
Nunca presuma que o proxy pegou. Pergunte a um serviço de echo qual IP o site realmente viu:
# Should print the proxy's exit IP, not yours
curl -x http://USER:PASS@HOST:PORT https://ipinfo.io/ip
curl -x http://USER:PASS@HOST:PORT http://httpbin.org/ip
# See the proxy handshake and CONNECT line
curl -v -x http://USER:PASS@HOST:PORT https://example.comCompare o resultado com uma chamada direta (curl https://ipinfo.io/ip sem proxy). Se os dois IPs diferem, o proxy está funcionando; se coincidem, o cURL ainda está saindo direto e o seu -x ou variável de ambiente não está sendo aplicado. A saída do -v mostra a linha CONNECT até o proxy, que é a forma mais rápida de confirmar a rota.
Erros comuns de proxy no cURL e como corrigi-los
| Erro | Causa provável | Correção |
|---|---|---|
407 Proxy Authentication Required | Credenciais ausentes ou erradas, ou um caractere especial numa senha embutida na URL que não foi codificado | Adicione -U 'user:pass', ou codifique a senha em URL (@ -> %40, : -> %3A) |
curl: (7) Couldn't connect to proxy | Host, porta ou scheme errados | Reconfira HOST:PORT; tente http:// vs socks5://; confirme que o proxy está no ar e acessível |
curl: (56) / erro de certificado SSL via um proxy HTTPS | O certificado TLS do proxy não é confiável | Só para testes, adicione --proxy-insecure ou aponte --proxy-cacert para a CA; corrija o certificado direito em produção |
| O site resolve pelo seu DNS local no SOCKS5 | Usar socks5:// quando você queria DNS remoto | Mude para socks5h:// para que o proxy resolva o hostname |
| A requisição trava ou nunca retorna | Proxy morto ou alvo lento | Adicione --connect-timeout 10 e --max-time 30 para falhar rápido |
Nove em cada dez relatos de "proxy do curl não funciona" são a primeira linha: um 407 de uma senha não codificada. Recorra ao -U antes de recorrer a qualquer outra coisa.
Qual tipo de proxy você deve usar com o cURL?
O cURL trata todo proxy do mesmo jeito, então a escolha é sobre o alvo, não sobre a ferramenta. A orientação honesta em três linhas:
- Proxies de datacenter - os mais rápidos e baratos, mas mais fáceis de detectar, então melhores para scraping de alto volume de sites públicos com pouca defesa.
- Proxies residenciais - mais difíceis de bloquear porque parecem usuários domésticos reais, mas mais caros e geralmente cobrados por GB.
- Proxies ISP (residencial estático) - o meio-termo: a velocidade de um datacenter com um IP estável e com cara de residencial.
Para um desenvolvedor que só quer um endpoint simples que cai no curl -x e um plano gratuito para testar, a Webshare é a escolha de bom custo-benefício - baixo custo, amigável para desenvolvedores e uma string host:port:user:pass sem invólucro para brigar. Não é a única opção: Bright Data, Oxylabs e IPRoyal operam redes residenciais maiores ou mais especializadas, caso você precise delas (repare que a Oxylabs é dona da Webshare, então trate-as como relacionadas, não como rivais independentes). Você pode começar com os proxies gratuitos da Webshare, ou comparar o mercado inteiro no nosso hub dos melhores serviços de proxy.
Perguntas frequentes
O cURL suporta proxies SOCKS5?
Sim. Use -x socks5://HOST:PORT ou --socks5 HOST:PORT. Mude para socks5h:// quando quiser que o proxy, e não a sua máquina, resolva o hostname alvo (DNS remoto).
Como defino um proxy só para requisições HTTPS?
Defina a variável de ambiente https_proxy (ou HTTPS_PROXY) e deixe http_proxy sem definir, para que só o tráfego https seja roteado. Para uma única chamada, é só adicionar -x ao comando https e nada mais.
Como faço o cURL ignorar o proxy em uma requisição?
Use curl --noproxy '*' URL ou curl -x '' URL. Qualquer um sobrescreve uma variável de ambiente ou um proxy do .curlrc para aquela única chamada e conecta direto.
Por que meu proxy no cURL retorna 407?
Um 407 significa que o proxy rejeitou suas credenciais. Ou você não passou um nome de usuário e senha, ou um caractere especial numa senha embutida na URL não foi codificado em URL. Adicione -U 'user:pass', ou codifique a senha (@ vira %40).
Posso rotacionar IPs com o cURL?
Sim, de duas formas: chame o endpoint de gateway rotativo de um provedor em um laço para obter um novo IP a cada requisição, ou percorra o seu próprio arquivo de lista de proxies com um -x por linha. Para o mesmo trabalho em Python, veja usar um proxy com o Python requests.