Neste artigo
Para converter curl para Python, mapeie a URL, o método, os headers e o corpo do comando em uma chamada do Requests e depois compare o que o servidor recebe. Comece pelo exemplo pareado abaixo e escolha explicitamente o comportamento de redirecionamento.
Uma resposta bem-sucedida, por si só, não prova equivalência. Em nosso teste em localhost, traduções diretas puderam alterar os bytes do JSON, a codificação de formulários e o comportamento de redirecionamento, mesmo quando o código parecia correto.
Principais fatos
- Nosso snapshot em localhost cobriu seis casos de teste, cada um repetido três vezes por cliente.
- O teste incluiu 36 execuções iniciais de cliente, sem contar os redirecionamentos seguidos.
- O caso de consulta repetida preservou a ordem dos parâmetros e as chaves duplicadas.
- O caso de JSON preservou os dados, mas alterou os bytes do corpo.
- O caso de formulário transformou um espaço literal em um sinal de mais.
- O caso de redirecionamento gerou uma requisição com curl e duas com Requests.
Como converter curl para Python com Requests?
Traduza uma requisição por vez, mantendo o destino e as entradas visíveis. Este exemplo de GET envia parâmetros de consulta repetidos e um header personalizado para um endpoint público de eco; use apenas dados sintéticos nele.
python -m pip install requests
curl --silent --show-error 'https://httpbin.org/get?tag=a&tag=b&page=2' -H 'X-Test: 1'
import requests
response = requests.get(
'https://httpbin.org/get',
params=[('tag', 'a'), ('tag', 'b'), ('page', '2')],
headers={'X-Test': '1'},
allow_redirects=False,
timeout=(5, 20),
)
response.raise_for_status()
print(response.status_code)
print(response.json()['args'])
Quando o endpoint responder normalmente, espere o status 200 e argumentos equivalentes a {'page': '2', 'tag': ['a', 'b']}. A ordem de exibição do dicionário é irrelevante aqui; os valores repetidos, não.
O Quickstart do Requests documenta parâmetros de consulta, headers e tratamento de respostas. Para o seu próprio endpoint, troque primeiro a URL e depois altere uma entrada por vez, para que as falhas continuem fáceis de isolar.
Quais mapeamentos de flags de curl para Python mais importam?
Mapeie o significado da requisição, não apenas o nome da flag. O manual do curl e a referência da API do Requests descrevem as opções por trás desta lista de verificação de conversão.
| Entrada do curl | Equivalente no Requests | Ponto de revisão |
|---|---|---|
| -X POST | requests.post(…) ou request(‘POST’, …) | Confira o método real, incluindo métodos implícitos nas opções de corpo. |
| Consulta na URL ou -G | params= | Mantenha chaves duplicadas e a ordem quando necessário. |
| -H | headers= | Preserve os valores obrigatórios. |
| -b ‘name=value’ | cookies= | Um arquivo de cookies exige tratamento separado. |
| -u para autenticação Basic | auth=(username, password) | Não presuma que todo esquema de autenticação seja Basic. |
| Header Authorization: Bearer | headers={‘Authorization’: …} | Leia o token de uma fonte segura de segredos. |
| -d ou –data-raw | data= ou json= | Escolha conforme o formato do corpo e os requisitos de bytes. |
| -F | files=, opcionalmente data= | Confira nomes de arquivos e nomes de campos. |
| -L | allow_redirects=True | Defina a política de redirecionamento explicitamente. |
| -x | proxies= | Preserve o esquema e o roteamento do proxy. |
A tradução de flags nem sempre é de um para um. Trate opções incomuns de assinatura, certificado, DNS e protocolo como itens de revisão separados. Use nosso guia de headers com curl para identificar quais headers de origem importam.
Como preservar JSON, formulários e uploads de arquivos?
Use json= para JSON estruturado, data= para campos de formulário ou bytes exatos do corpo e files= para uploads multipart. Essas interfaces estão documentadas nos exemplos de corpo e upload do Requests.
Um POST também pode carregar parâmetros de consulta. Este exemplo mantém a consulta separada do corpo JSON e lê um token Bearer do ambiente. Defina API_URL com o seu endpoint autorizado e API_TOKEN pelo seu mecanismo habitual de segredos antes de executá-lo.
import os
import requests
response = requests.post(
os.environ['API_URL'],
params=[('mode', 'validate')],
headers={'Authorization': 'Bearer ' + os.environ['API_TOKEN']},
json={'name': 'a', 'n': 1},
allow_redirects=False,
timeout=(5, 20),
)
response.raise_for_status()
print(response.status_code)
Para corpos assinados, serialize uma única vez e assine os mesmos bytes que você envia. Nosso caso de JSON alterou os espaços em branco durante a tradução. A serialização compacta reproduz o corpo original desse caso, mas não consegue reconstruir espaços em branco ou ordem de chaves arbitrários do original.
import json
import os
import requests
body = json.dumps({'name': 'a', 'n': 1}, separators=(',', ':')).encode('utf-8')
response = requests.post(
os.environ['API_URL'],
data=body,
headers={'Content-Type': 'application/json'},
allow_redirects=False,
timeout=(5, 20),
)
response.raise_for_status()
Para campos de formulário repetidos, use data=[('k', '1'), ('k', '2'), ('x', 'a b')]. Em nosso teste, isso codificou o espaço como +, enquanto a entrada literal de -d no curl manteve o espaço. A opção –data-urlencode do curl codifica os valores dos campos, mas uma decodificação equivalente ainda não estabelece bytes idênticos.
Para uploads, deixe o cliente construir o boundary multipart. Este exemplo autocontido usa conteúdo de arquivo sintético; compare o conteúdo dos arquivos e os nomes dos campos separadamente do envelope multipart.
import os
import requests
response = requests.post(
os.environ['API_URL'],
data={'label': 'example'},
files={'file': ('sample.txt', b'hello\n', 'text/plain')},
allow_redirects=False,
timeout=(5, 20),
)
response.raise_for_status()
Como copiar uma requisição do navegador com segurança?
Capture apenas uma requisição autorizada e remova os segredos antes de compartilhá-la. No Chrome DevTools, abra Network, clique com o botão direito na requisição e escolha Copy > Copy as cURL, conforme descrito na referência de Network do Chrome.
Inspecione o texto antes de executar qualquer coisa. As aspas do shell fazem parte da sintaxe do comando, não necessariamente do payload. Verifique aspas embutidas, continuações de linha e referências a variáveis de acordo com o shell usado na captura.
Mova os valores de autorização e de sessão para um armazenamento de segredos. Mantenha os headers de aplicação obrigatórios, mas revise os headers Host, Content-Length e os específicos do navegador antes de copiá-los. Remova os headers questionáveis um de cada vez e teste de novo; apagar tudo de uma vez esconde qual valor era o importante.
Registre o momento da captura e a operação pretendida. Uma requisição copiada é um instantâneo, então a expiração da sessão ou uma mudança no estado da aplicação pode invalidá-la. A tradução não estabelece emulação de navegador nem reproduz uma interação completa.
Quando usar um conversor ou outra abordagem?
Use a conversão manual para o código que você vai manter e um conversor para uma tradução inicial que você possa inspecionar. Mantenha o curl quando preservar o comportamento dele for mais importante do que usar um cliente HTTP nativo de Python.
| Abordagem | Use X quando… | Evite X quando… |
|---|---|---|
| Conversão manual para Requests | Use a conversão manual para Requests quando precisar de código legível e mantido. | Evite a conversão manual para Requests quando algum comportamento incomum do curl continuar sem mapeamento. |
| curlconverter | Use o curlconverter quando quiser uma tradução inicial. | Evite o curlconverter quando não puder revisar o código gerado ou proteger as credenciais. |
| Manter o curl via subprocess | Use o subprocess quando o comportamento atual do curl for essencial. | Evite o subprocess quando o conteúdo do comando não for confiável ou quando for exigido Python nativo. |
O site oficial do curlconverter afirma que a conversão acontece no seu navegador. Essa afirmação vale para esse site, não para todo conversor de curl para Python. O repositório oficial documenta este caminho pela CLI:
npm install --global curlconverter
curlconverter --language python 'https://httpbin.org/get'
Executar o curl a partir do Python é uma abordagem diferente. Seguindo a documentação do subprocess do Python, use uma lista fixa de argumentos e evite a avaliação pelo shell. Ainda assim, revise cada argumento e cada destino.
import subprocess
result = subprocess.run(
['curl', '--silent', '--show-error', '--fail',
'--max-time', '20', 'https://httpbin.org/get'],
check=True,
capture_output=True,
text=True,
timeout=25,
)
print(result.stdout)
Como verificar se a conversão é equivalente?
Use a Verificação de Equivalência de Requisições em 4 camadas para separar entradas de aplicação iguais de bytes e comportamento de resposta iguais. Decida quais propriedades o seu endpoint exige antes de aceitar uma conversão.

- Camada 1, destino e método: compare o método, o caminho e os pares ordenados da consulta.
- Camada 2, headers e autenticação: compare os valores de headers selecionados e o local das credenciais, sem registrar segredos em log.
- Camada 3, payload: compare o tamanho do corpo bruto, o SHA-256 e a igualdade do payload interpretado.
- Camada 4, transporte e resposta: compare o status, a URL final e o número de saltos de redirecionamento.
No nosso teste de 15 de outubro de 2026, um servidor HTTP com logs, vinculado a 127.0.0.1, recebeu seis casos de teste, cada um executado três vezes com cada cliente. Isso dá 36 execuções iniciais, com os redirecionamentos seguidos contados à parte. Os resultados se repetiram de forma consistente nas três execuções.
Fonte: DataImpulse, TESTE DE EQUIVALÊNCIA ENTRE CURL E PYTHON REQUESTS, 15 de outubro de 2026, 16:12 UTC. O ambiente Linux usou curl 8.5.0, Python 3.12.3 e Requests 2.34.2. Este é um snapshot em localhost, não um benchmark.
| Caso de teste | Equivalência semântica | Equivalência de bytes | Equivalência de redirecionamento | Explicação |
|---|---|---|---|---|
| Consulta repetida | Sim | Sim, consulta | Não exercitado | Os pares em tupla preservaram tag=a, tag=b e page=2. |
| Header personalizado e cookie | Sim | Sim, valores selecionados | Não exercitado | X-Test e o cookie sintético coincidiram. |
| Header Bearer | Sim | Sim, valor selecionado | Não exercitado | O valor sintético de autorização coincidiu. |
| POST com JSON | Sim | Não | Não exercitado | Os espaços adicionados alteraram o hash do corpo. |
| Campos de formulário repetidos | Mesmos campos decodificados | Não | Não exercitado | Um espaço literal virou +. |
| Redirecionamento 302 | Somente a requisição inicial | Não estabelecido para a cadeia | Não | O curl fez uma requisição; o Requests fez duas. |
As equivalências de bytes acima dizem respeito aos campos indicados, não às mensagens completas na rede. O User-Agent foi diferente entre os clientes. O snapshot não consegue estabelecer compatibilidade com APIs externas, comportamento de TLS, desempenho de proxies nem taxas de sucesso generalizadas.
Para a sua própria verificação repetível, guarde os comandos higienizados, o código do servidor e as versões dos pacotes. Registre as quatro camadas separadamente. Repita o caso de redirecionamento com os dois clientes parando no redirecionamento e depois com os dois seguindo; esses são passos de validação complementares, não resultados medidos adicionais relatados aqui.
Por que o código convertido falha ou retorna resultados diferentes?
Encontre a primeira camada que difere antes de mudar várias configurações. Comece com o comando original e a requisição convertida próximos no tempo, usando as mesmas entradas autorizadas.
- Autenticação: verifique a expiração das credenciais, o escopo e o estado de sessão exigido. Nunca imprima tokens ao diagnosticar um 401 ou 403.
- Redirecionamentos: inspecione a resposta inicial antes de comparar o conteúdo final. Nosso caso de teste expôs comportamentos padrão diferentes logo de cara.
- Codificação: compare os bytes quando assinaturas ou payloads exatos importarem; compare os campos decodificados quando o significado para a aplicação importar.
- Erros HTTP: inspecione o status e um trecho higienizado da resposta. O Requests oferece raise_for_status() para tratar status HTTP de falha.
- Timeouts: defina valores explícitos de conexão e leitura. Eles não são um prazo total de tempo decorrido.
- TLS: corrija problemas de confiança no certificado ou de hostname. Desativar a verificação cria risco de interceptação.
- Streaming: consuma a resposta de forma deliberada e feche-a; use um gerenciador de contexto em downloads com streaming.
O Quickstart do Requests cobre o tratamento de status, enquanto o Advanced Usage explica timeouts, verificação de certificados e streaming. Diagnostique a falha antes de adicionar novas tentativas, principalmente em operações que alteram o estado do servidor.
Como os proxies entram em uma requisição convertida?
Traduza o roteamento depois que a conversão direta funcionar. Mantenha a autenticação do proxy separada do token Bearer ou dos cookies do destino.
import os
import requests
proxy_url = os.environ['PROXY_URL']
response = requests.get(
os.environ['API_URL'],
proxies={'http': proxy_url, 'https': proxy_url},
allow_redirects=False,
timeout=(5, 20),
)
response.raise_for_status()
print(response.status_code)
O Requests documenta URLs de proxy, autenticação de proxy embutida e configurações de proxy via ambiente em sua documentação de proxies. Inspecione o roteamento do ambiente quando os resultados diferirem. SOCKS exige dependências opcionais; preserve o comportamento de DNS pretendido, além do endereço do proxy.
Use o guia de configuração de proxy no curl para revisar o comando de origem e o tutorial de proxy no Python Requests para o código de destino. Depois que as verificações de equivalência passarem, o guia de roteamento em Python e o guia de roteamento no curl oferecem próximos passos opcionais.
Perguntas frequentes
Como converto um comando curl em Python Requests?
Separe a requisição do curl em destino, método, headers e payload e depois traduza cada parte. Compare o que o servidor observa antes de confiar no resultado; a execução bem-sucedida, por si só, não basta.
Como as opções de JSON, formulário e upload do curl são mapeadas para Python?
Escolha json= para objetos JSON, data= para campos de formulário ou bytes exatos e files= para uploads multipart. Em requisições sensíveis a bytes, mantenha o corpo original e verifique o hash dele, em vez de presumir que a serialização o preserva.
Como preservar headers, cookies e autenticação Bearer com segurança?
Faça um inventário dos valores necessários e carregue os segredos reais em tempo de execução. Use substitutos sintéticos ao compartilhar exemplos e evite registrar em log tanto as credenciais do destino quanto as do proxy.
Por que o Python convertido pode se comportar de forma diferente do comando curl original?
Nosso snapshot expôs diferenças na serialização do corpo e no tratamento de redirecionamentos. Verifique a requisição e a resposta iniciais antes de atribuir a saída diferente ao serviço remoto.
Como traduzo as configurações de proxy do curl para o Requests?
Leve o endpoint do proxy para o mapeamento proxies e preserve o esquema dele. Verifique o roteamento do ambiente e a autenticação do proxy separadamente da autenticação da aplicação antes de comparar os resultados.
Um JSON interpretado igual prova que a conversão está correta?
Prova apenas que os payloads comparados são decodificados para os mesmos dados. Nosso caso de JSON ainda teve hashes de corpo diferentes, o que importa quando a validação depende dos bytes exatos.
Precisa de roteamento por proxy depois que a conversão funcionar?
Comece pelo guia de configuração do Requests da DataImpulse se o seu fluxo autorizado precisar de roteamento por proxy. A DataImpulse não é uma API de scraping, um unblocker gerenciado nem uma VPN; a correção da requisição e o tratamento da resposta continuam sendo responsabilidade do seu código.
Última atualização: 15 de outubro de 2026.
