Cómo utilizar cURL con Python en 2026

Si escribes en Python y utilizas API HTTP, probablemente te hayas encontrado con esta situación: la documentación de una API o el botón «Copiar como cURL» de tu navegador te proporciona una línea de comando que empieza por curl -X POST ..., y ahora la necesitas dentro de un script de Python. Averiguar cómo usar cURL con Python parece sencillo, pero tiene más de una respuesta correcta.

cURL en sí es una herramienta de línea de comandos para transferir datos a través de protocolos de red (HTTP, HTTPS, FTP). Desde Python, puedes llamar al binario de curl como un proceso externo, controlar su biblioteca C subyacente (libcurl) a través de PycURL, o utilizar la biblioteca Requests como alternativa en Python. Cada opción tiene sus pros y contras en cuanto a velocidad, control y facilidad de mantenimiento.

Esta guía está dirigida a ingenieros de backend, datos y scraping que ya conocen Python y buscan una forma clara de convertir cualquier fragmento de código de curl en código funcional. Cubrimos los tres métodos con ejemplos ejecutables, asignamos los indicadores comunes de curl a sus equivalentes en Python, creamos un pequeño flujo de trabajo de scraping y terminamos con la resolución de problemas para que puedas entregar el código en lugar de luchar con tus herramientas.

La mayoría de los equipos se enfrentan a la cuestión de «cURL en Python» por la misma razón: alguien les ha pasado un comando de cURL. La documentación de las API incluye ejemplos de solicitudes como curl invocaciones, las herramientas de desarrollo del navegador exportan las llamadas de red en el mismo formato, y Postman e Insomnia te permiten copiar cualquier solicitud como cURL. Ese fragmento es la fuente de verdad, y quieres que tu código Python se comporte de forma idéntica.

Ejecutar curl dentro de Python te permite depurar primero la solicitud exacta y luego pasar a algo más idiomático. Una ejecución de copiar-pegar a través de subprocess demuestra que el punto final funciona. A partir de ahí, puedes reescribir la llamada en PycURL o Requests con la confianza de que no has cambiado el formato de la conexión. Ese breve ciclo de retroalimentación es la verdadera razón por la que los desarrolladores quieren saber cómo usar cURL con Python, no curl por sí solo.

Cuando los desarrolladores preguntan cómo usar cURL con Python, normalmente se refieren a uno de estos tres enfoques concretos. Antes de escribir ningún código, elige el que mejor se adapte a la tarea. Las tres opciones no son intercambiables, y elegir la incorrecta suele implicar reescribir la llamada más adelante.

Utiliza subprocess como tu paso de traducción, PycURL como tu herramienta avanzada y Requests como tu opción predeterminada. La mayor parte del código Python de producción acaba en Requests; los otros dos cubren los casos extremos.

El subprocess módulo forma parte de la biblioteca estándar de Python, por lo que puedes ejecutar curl sin instalar nada nuevo. Esta es la interpretación más literal de «usar cURL con Python», y resulta realmente útil cuando quieres reproducir un comando exactamente tal y como aparece en la documentación de la API.

Una regla de seguridad innegociable: pasa el comando como una lista de argumentos, no como una sola cadena de shell. Las cadenas invitan a la inyección de shell cuando cualquier parte de la solicitud proviene de la entrada del usuario. La forma de lista de argumentos omite el shell por completo. La documentación de Python subprocess cubre el modelo de seguridad en detalle.

Toma una línea de curl, divídela en tokens y pasa la lista a subprocess.run. Establece capture_output=True para que stdout y stderr te sean devueltos, y text=True para que obtengas cadenas en lugar de bytes.

import subprocess

cmd = [
    "curl", "-s",
    "-H", "Accept: application/json",
    "https://httpbin.org/get?lang=python",
]

result = subprocess.run(cmd, capture_output=True, text=True, timeout=15)
print(result.stdout)

La -s opción silencia el indicador de progreso de curl para que stdout solo contenga el cuerpo de la respuesta. El timeout=15 argumento lanza subprocess.TimeoutExpired si curl se cuelga, que es exactamente lo que quieres en un script que no debe bloquearse indefinidamente. Mantén esta forma para la traducción: una vez que funcione, tendrás una base de referencia verificada para portar a PycURL o Requests.

Por defecto, subprocess.run no lanza una excepción cuando curl sale con un valor distinto de cero. Tienes que inspeccionar el código de retorno tú mismo, o optar por lanzar una excepción explícitamente.

import json, subprocess

result = subprocess.run(cmd, capture_output=True, text=True, timeout=15)

if result.returncode != 0:
    raise RuntimeError(f"curl failed ({result.returncode}): {result.stderr.strip()}")

try:
    payload = json.loads(result.stdout)
except json.JSONDecodeError as exc:
    raise RuntimeError(f"non-JSON response: {result.stdout[:200]}") from exc

print(payload["args"])

También puedes llamar a result.check_returncode(), que lanza CalledProcessError en cualquier salida distinta de cero. En cualquier caso, registra result.stderr cuando la llamada falle. Curl escribe allí su salida de diagnóstico, y ese mensaje suele ser suficiente para distinguir un fallo de DNS de un error TLS o una respuesta 4xx.

PycURL es una interfaz de Python para libcurl, la misma biblioteca C que alimenta al propio binario curl. Ofrece opciones de bajo nivel para tiempos de espera, configuración SSL, encabezados, cookies, redireccionamientos y protocolos más allá de HTTP. Cuando el rendimiento o el control detallado son importantes, PycURL es la opción adecuada.

Instálalo con pip install pycurl. El paquete de Python es una envoltura ligera, por lo que también necesitas libcurl y los encabezados de desarrollo de OpenSSL en el sistema. En Debian/Ubuntu es apt install libcurl4-openssl-dev libssl-dev; en macOS, brew install curl openssl. Trataremos los errores de tiempo de enlace de OpenSSL en la sección de resolución de problemas, ya que son la causa más común por la que falla una instalación nueva.

PycURL sigue el patrón de libcurl: crear un identificador, establecer opciones, ejecutar y, a continuación, cerrar. Las escrituras se dirigen a un búfer similar a un archivo, que suele ser un BytesIO.

import json, pycurl
from io import BytesIO
from urllib.parse import urlencode

# GET
buf = BytesIO()
c = pycurl.Curl()
c.setopt(c.URL, "https://httpbin.org/get?lang=python")
c.setopt(c.WRITEDATA, buf)
c.perform()
status = c.getinfo(pycurl.RESPONSE_CODE)
c.close()
print(status, buf.getvalue().decode("utf-8"))

Para un POST codificado en formulario, configura POSTFIELDS un cuerpo codificado como URL. Para JSON, volcá el diccionario y configura el Content-Type.

# POST form
form = urlencode({"a": 1, "b": "two"})
buf = BytesIO()
c = pycurl.Curl()
c.setopt(c.URL, "https://httpbin.org/post")
c.setopt(c.POSTFIELDS, form)
c.setopt(c.WRITEDATA, buf)
c.perform(); c.close()

# POST JSON
body = json.dumps({"hello": "world"})
buf = BytesIO()
c = pycurl.Curl()
c.setopt(c.URL, "https://httpbin.org/post")
c.setopt(c.HTTPHEADER, ["Content-Type: application/json"])
c.setopt(c.POSTFIELDS, body)
c.setopt(c.WRITEDATA, buf)
c.perform(); c.close()

Configuración HTTPHEADER es la forma de controlar Content-Type, Accept, Authorization y cualquier otro encabezado de solicitud. A continuación, desarrollaremos ese patrón.

HTTPHEADER toma una lista de "Name: value" cadenas. Las cookies pueden incluirse como un Cookie encabezado para llamadas puntuales, o puedes dejar que libcurl gestione un almacén de cookies con COOKIEFILE y COOKIEJAR.

c.setopt(c.HTTPHEADER, [
    "Accept: application/json",
    "Authorization: Bearer eyJhbGciOi...",
    "Cookie: session=abc123; theme=dark",
])

# Or use a cookie jar to persist Set-Cookie across requests
c.setopt(c.COOKIEFILE, "cookies.txt")
c.setopt(c.COOKIEJAR, "cookies.txt")

Para las redirecciones, habilita FOLLOWLOCATION (el equivalente a curl -L) y limita la cadena con MAXREDIRS para que un servidor que se comporte mal no pueda mantenerte en un bucle infinito.

c.setopt(c.FOLLOWLOCATION, True)
c.setopt(c.MAXREDIRS, 5)

Si solo necesitas los encabezados de respuesta (una curl -I solicitud de estilo), establece NOBODY en True y redirige el flujo de encabezados a una llamada de retorno mediante HEADERFUNCTION. Esa llamada de retorno se ejecuta una vez por cada línea de encabezado, lo cual resulta útil al extraer datos como Last-Modified o metadatos de límite de velocidad. Para recetas más avanzadas, consulta nuestro desglose de los encabezados de respuesta HTTP en cURL.

WRITEDATA acepta cualquier objeto similar a un archivo, por lo que una descarga es un cambio de una sola línea: abre un archivo en modo de escritura binaria y apúntale a libcurl. El uso de memoria se mantiene constante independientemente del tamaño de la carga útil.

import os, pycurl

url = "https://example.com/large.iso"
out = "large.iso"

mode = "ab" if os.path.exists(out) else "wb"
offset = os.path.getsize(out) if mode == "ab" else 0

with open(out, mode) as fp:
    c = pycurl.Curl()
    c.setopt(c.URL, url)
    c.setopt(c.WRITEDATA, fp)
    c.setopt(c.FOLLOWLOCATION, True)
    if offset:
        c.setopt(c.RANGE, f"{offset}-")  # resume from byte offset
    c.perform(); c.close()

El Range: bytes={offset}- encabezado le indica al servidor que envíe solo la parte final que falta, que es exactamente cómo curl -C - se reanudan las descargas interrumpidas. El servidor debe admitir solicitudes de rango (la mayoría de las CDN lo hacen).

Para la mayoría de las tareas cotidianas, Requests es la respuesta. No viene incluido con Python (se instala con pip install requests), pero la API se ajusta perfectamente a la semántica de curl: los parámetros de consulta, los encabezados, las cookies, los cuerpos JSON y los tiempos de espera son todos argumentos clave.

import requests

# GET with query params
r = requests.get(
    "https://httpbin.org/get",
    params={"lang": "python"},
    headers={"Accept": "application/json"},
    timeout=15,
)
r.raise_for_status()
print(r.json())

# POST JSON
r = requests.post(
    "https://httpbin.org/post",
    json={"hello": "world"},
    headers={"Authorization": "Bearer ..."},
    timeout=15,
)

raise_for_status() es tu aliado: convierte cualquier 4xx/5xx en un requests.HTTPError, por lo que la diferencia entre fallos de red (requests.ConnectionError, requests.Timeout) y los errores HTTP queda clara en tu código.

Elige Requests por defecto cuando la llamada sea una de muchas en un programa de Python, necesites el estado de la sesión o tu equipo vaya a mantener el código. Elige PycURL cuando hayas detectado un cuello de botella real o necesites opciones exclusivas de libcurl. Para una comparación más detallada de los clientes HTTP de Python, consulta nuestro resumen sobre el tema.

Una vez que sepas cómo usar cURL con Python en sus tres variantes, la forma más rápida de portar un nuevo comando es traducir sus indicadores uno por uno. Esta tabla recoge los indicadores que verás en el 95 % de la documentación de API y las exportaciones de herramientas de desarrollo.

Si prefieres no traducir a mano, existen convertidores públicos de curl a Python (y el convertidor de ScrapingBee es uno muy conocido) que toman un comando curl y generan una llamada Requests con los encabezados, parámetros y datos rellenados. Úsalos para empezar y, a continuación, comprueba que el resultado es correcto con esta tabla.

Una razón habitual para aprender a usar cURL con Python es el scraping web. Este es el patrón que seguimos al crear un prototipo de un pequeño scraper: recuperamos el HTML con PycURL para ganar velocidad, lo analizamos con BeautifulSoup y, a continuación, guardamos el resultado. Todo el código tiene menos de 40 líneas y cubre comprobaciones de estado, codificación y una salida en CSV.

import csv, json, pycurl
from io import BytesIO
from bs4 import BeautifulSoup

URL = "https://books.toscrape.com/catalogue/page-1.html"

def fetch(url: str) -> str:
    buf = BytesIO()
    c = pycurl.Curl()
    c.setopt(c.URL, url)
    c.setopt(c.WRITEDATA, buf)
    c.setopt(c.FOLLOWLOCATION, True)
    c.setopt(c.TIMEOUT, 20)
    c.setopt(c.HTTPHEADER, ["User-Agent: scraping-pipeline/1.0"])
    c.perform()
    code = c.getinfo(pycurl.RESPONSE_CODE)
    c.close()
    if code != 200:
        raise RuntimeError(f"unexpected status {code} for {url}")
    return buf.getvalue().decode("utf-8")

def parse(html: str) -> list[dict]:
    soup = BeautifulSoup(html, "html.parser")
    rows = []
    for card in soup.select("article.product_pod"):
        rows.append({
            "title": card.h3.a["title"],
            "price": card.select_one(".price_color").text.strip(),
            "stock": card.select_one(".availability").text.strip(),
        })
    return rows

def main():
    rows = parse(fetch(URL))
    with open("books.csv", "w", newline="") as fp:
        writer = csv.DictWriter(fp, fieldnames=rows[0].keys())
        writer.writeheader(); writer.writerows(rows)
    print(json.dumps(rows[:2], indent=2))

if __name__ == "__main__":
    main()

Cambia PycURL por subprocess si quieres reproducir un comando curl tal cual, o por Requests si necesitas el estado de la sesión. Una vez que empieces a acceder a sitios web reales con límites de frecuencia y defensas antibots, querrás una capa de proxy delante de este paso de obtención.

La mayor parte de las dificultades a la hora de aprender a usar cURL con Python provienen de un pequeño conjunto de fallos recurrentes. Aquí tienes una breve lista y cómo solucionar cada uno de ellos.

• PycURL ImportError: pycurl: libcurl link-time ssl backend (...) is different from compile-time ssl backend (...). Tu rueda de PycURL se compiló con un backend SSL diferente al de libcurl en tu sistema. En el momento de escribir este artículo, la solución más fiable en macOS es instalar OpenSSL a través de Homebrew y reinstalar PycURL desde el código fuente con ese backend; en Windows, instala los binarios de OpenSSL 1.1.x y configura PYCURL_SSL_LIBRARY, LIB, y INCLUDE antes pip install pycurl --no-binary :all:. Vuelve a consultar las notas de instalación de PycURL para tu plataforma, ya que las variables de entorno exactas han cambiado entre versiones.
• UnicodeEncodeError de PycURL en los cuerpos POST. PycURL espera bytes para POSTFIELDS. Codifica los datos no ASCII explícitamente: c.setopt(c.POSTFIELDS, body.encode("utf-8")).
• subprocess.TimeoutExpired. Pase siempre timeout= a subprocess.run. Trata la excepción como un fallo de red, no como un error.
• Errores de TLS y certificados autofirmados. PycURL: c.setopt(c.SSL_VERIFYPEER, 0); Requests: verify=False. Haz esto solo en entornos de confianza y, en producción, es preferible fijar un paquete de CA.
• Distinguir entre errores HTTP y de transporte. Con Requests, captura requests.HTTPError por separado de requests.ConnectionError. Con subprocess, un valor distinto de cero returncode indica un fallo a nivel de transporte; un error HTTP 4xx sigue devolviendo 0 a menos que se pase --fail.

Una vez que dispongas de las tres herramientas, la elección dependerá de la situación.

• Depurar una API o reproducir un informe de error. Opta por subprocess primero. Ejecutar el comando curl literal elimina «mi cliente Python es el problema» de las variables.
• Scripts de un solo uso y trabajos de CI. Requests. Es legible, está bien documentado y es fácil de mantener para el siguiente ingeniero.
• Scrapers de larga duración, altos volúmenes de solicitudes o protocolos más allá de HTTP. PycURL. Obtienes la reutilización de conexiones de libcurl, un control TLS detallado y una menor sobrecarga por solicitud.
• Cookies y flujos de inicio de sesión. Requests Session es la opción más sencilla; el «cookie jar» de PycURL es la alternativa cuando ya estás utilizando libcurl.

Saber cómo usar cURL con Python no se trata tanto de elegir un ganador como de adaptar la herramienta a la solicitud.

• Tres opciones reales para combinar curl con Python: subprocess (ejecutar el binario), PycURL (enlaces a libcurl) y Requests. Elige deliberadamente, no por costumbre.
• Utiliza subprocess como capa de traducción: verifica el formato de la conexión con el comando literal y, a continuación, pasa a PycURL o Requests con confianza.
• Asigna los indicadores de curl a Python de forma sistemática: -H se convierte en headers, -d se convierte en datos o json, -G se convierte en params, -F se convierte en archivos, -L se convierte en redireccionamientos, -o se convierte en una escritura en streaming.
• Establece siempre tiempos de espera, comprueba siempre los códigos de estado y trata los errores HTTP como una categoría distinta de los errores de transporte.
• Para el scraping de gran volumen o descargas con soporte de reanudación, PycURL se amortiza por sí solo. Para todo lo demás, utiliza Requests por defecto.

Ambas cosas. «Ejecutar curl» suele significar llamar al curl desde Python mediante subprocess, lo que requiere que curl esté en tu PATH. «Usar una biblioteca de Python» significa importar PycURL (un envoltorio alrededor de libcurl) o Requests (un cliente HTTP puro de Python) y no tocar nunca el binario. Las solicitudes de red parecen idénticas para el servidor; solo difiere el código de llamada.

PycURL suele ser más rápido en pruebas sintéticas porque descarga el trabajo HTTP a libcurl en C. En cargas de trabajo reales, la diferencia se reduce: la latencia de red, los handshakes TLS y el análisis suelen ser los factores dominantes. PycURL sigue ganando en miles de conexiones simultáneas, donde la sobrecarga por solicitud se acumula. Para la mayoría de los scripts, la diferencia no es apreciable.

Pega el comando curl en un conversor de curl a Python (hay varios gratuitos en línea), selecciona la salida Requests y, a continuación, revisa el código generado comparándolo con la tabla de traducción de indicadores de esta guía. El conversor gestiona automáticamente los encabezados, los parámetros y los datos. Aún así, debes añadir timeout, raise_for_status()y un manejo adecuado de excepciones antes de implementarlo.

En Requests, utiliza la files palabra clave: requests.post(url, files={"upload": open("data.csv", "rb")}). Para un mayor control sobre el nombre del archivo y el tipo de contenido, pasa una tupla: files={"upload": ("data.csv", fp, "text/csv")}. En PycURL, configura la HTTPPOST opción con una lista de tuplas que describan cada campo del formulario, incluyendo una pycurl.FORM_FILE entrada para la ruta en el disco.

Ese error significa que el paquete wheel se compiló con un backend SSL que no coincide con tu libcurl del sistema. La solución es reinstalar PycURL desde el código fuente con tu libcurl local: pip install --no-binary :all: pycurl tras instalar libcurl y los encabezados de desarrollo de OpenSSL (brew install curl openssl en macOS; los paquetes de desarrollo equivalentes en Linux). En Windows, configura las rutas de OpenSSL mediante variables de entorno antes de reinstalar.

Saber cómo usar cURL con Python es en realidad tres habilidades en una: llamar al binario curl con subprocess, manejar libcurl a través de PycURL y escribir código idiomático de Requests. Cada uno tiene su función. subprocess es tu paso de traducción de la documentación de la API a código verificado. PycURL es tu herramienta de rendimiento para rastreadores y descargas de alto rendimiento. Requests es la opción predeterminada para todo lo demás, ya que se mantiene legible a medida que crece el proyecto.

La tabla de correspondencias entre flags y Python, la receta de descarga en streaming y la lista de resolución de problemas anterior cubren la mayoría de los escollos. El que queda es lo que tu servidor de destino hace con el tráfico que no proviene de navegadores: los límites de velocidad, los CAPTCHAs, los retos de JavaScript y los bloqueos de IP te afectarán tarde o temprano, por muy limpio que sea tu código Python.

Esa es la capa en la que nos centramos en WebScrapingAPI. Si dedicas más tiempo a luchar contra las defensas antibots que a escribir tu scraper, nuestra API de scraping toma una solicitud al estilo curl y devuelve el HTML sin procesar, gestionando la rotación de proxies, la resolución de CAPTCHAs y los reintentos por su cuenta, para que puedas mantener tu código de subprocesos, PycURL o Requests tal y como está y simplemente cambiar el punto final. Elige el método curl que mejor se adapte a tu trabajo y deja que la capa de red sea problema de otros.