cURL funciona en unas 20 mil millones de instalaciones en todo el mundo: viene integrado por defecto en macOS, la mayoría de distribuciones de Linux y Windows 10/11. Y aun así, pregúntale a diez desarrolladores cómo enrutar correctamente una solicitud de cURL a través de un proxy y obtendrás diez respuestas ligeramente distintas, la mitad de las cuales se rompen en cuanto aparece autenticación o SOCKS.
Esa es la brecha que quiero cerrar aquí. La mayoría de los tutoriales te muestran un comando, te dicen que funciona y pasan a otra cosa. No te enseñan a comprobar si el proxy realmente está haciendo algo (spoiler: a veces no lo está), y desde luego no te guían por los códigos de error que aparecen en cuanto tu configuración se aparta un poco del caso ideal. Esta guía cubre todo el panorama: proxies HTTP/HTTPS, SOCKS4/SOCKS5/socks5h, variables de entorno (y sus trampas muy concretas), una tabla de solución de problemas en condiciones y qué hacer cuando cURL y un proxy simplemente ya no bastan.
¿Qué es cURL y por qué usarlo con un proxy?
cURL es una herramienta de línea de comandos para transferir datos hacia y desde una URL. Eso es todo: sin interfaz gráfica, sin adornos, solo un programa que habla HTTP, HTTPS, FTP y algunos otros protocolos. La invocación más simple posible es:
curl https://example.com
Eso descarga la página y vuelca el HTML sin procesar en tu terminal. Útil por sí solo, pero la verdadera razón por la que desarrolladores y usuarios técnicos de negocio recurren a cURL es para probar APIs, extraer datos, comprobar contenido restringido por geolocalización y ejecutar solicitudes dentro de pipelines de CI/CD.
Un proxy se sitúa entre tu equipo y el servidor de destino, reenviando tu solicitud en tu nombre. El destino ve la IP del proxy, no la tuya. Esto importa por varias razones legítimas: probar cómo se ve tu sitio desde otro país, sortear límites de velocidad durante QA o enrutar el tráfico a través de la pasarela corporativa que exige tu empresa. cURL admite toda la gama de protocolos de proxy: HTTP, HTTPS, SOCKS4 y SOCKS5, y las opciones que verás una y otra vez en esta guía son -x / --proxy (la dirección del proxy), -v (salida detallada, tu mejor aliada para depurar) y -k (omitir la verificación SSL, algo que básicamente no deberías usar fuera de pruebas).
Una nota rápida antes de seguir: esta guía trata sobre la mecánica de red de usar un proxy con cURL. No es una autorización para ignorar los términos de servicio de un sitio ni la política de seguridad de tu organización. Un proxy cambia tu ruta de red, no cambia lo que es legal o permitido.
Antes de empezar
Dificultad: De principiante a intermedio
Tiempo necesario: ~15 minutos para revisar los ejemplos principales
Lo que necesitarás:
- cURL instalado (compruébalo con
curl --version; si usas macOS, Linux o Windows 10/11, lo más probable es que ya esté ahí) - Credenciales del proxy de tu proveedor: host, puerto, protocolo (HTTP/HTTPS/SOCKS) y nombre de usuario/contraseña si son necesarios
- Una terminal (Terminal en macOS, cualquier shell en Linux, PowerShell o CMD en Windows)
Si por alguna razón no tienes cURL instalado, basta una línea: brew install curl en macOS con Homebrew, sudo apt install curl en Debian/Ubuntu, o sudo yum install curl en RHEL/CentOS. En Windows, viene incluido con el sistema desde Windows 10 build 17063.
A lo largo de esta guía usaré valores de ejemplo: proxy.example:8080 para la dirección del proxy y user:pwd para las credenciales. Sustitúyelos por los datos reales de tu proxy, y nunca pegues credenciales verdaderas en el historial del shell, en una captura de pantalla o en un mensaje de Slack. He visto más contraseñas de proxy filtradas en canales de Slack de las que me gustaría admitir.
Cómo usar cURL con un proxy HTTP o HTTPS
Esta es la configuración más común y la que usarás en la gran mayoría de tareas con proxy.
Usar la opción -x / --proxy
La sintaxis básica es esta:
curl -x "http://user:pwd@proxy.example:8080" "https://httpbin.org/ip"
-x y --proxy hacen exactamente lo mismo; usa la que te resulte más fácil de recordar. Como HTTP es el esquema de proxy predeterminado de cURL, técnicamente puedes omitir el prefijo http:// y escribir solo proxy.example:8080. Aun así, yo lo pondría de forma explícita, porque dentro de seis meses agradecerás esa claridad.
Encierra toda la URL entre comillas dobles. Si tu contraseña contiene @, # o &, una cadena sin comillas será alterada por tu shell antes de que cURL la vea.
Conectar a través de un proxy HTTPS
Algunos proveedores cifran con TLS la conexión al propio proxy, no solo la conexión desde el proxy hasta tu destino. Eso es distinto de hacer scraping de un sitio HTTPS: el protocolo del proxy y el protocolo del destino son variables independientes. Para indicarlo:
curl -x "https://user:pwd@proxy.example:8080" "https://httpbin.org/ip"
Si aquí aparece un error de certificado, resiste la tentación de añadir -k y seguir. Esa opción desactiva por completo la verificación del certificado SSL, lo cual puede servir para una prueba local de cinco minutos, pero es una muy mala idea para cualquier cosa que toque producción o datos reales de usuarios. Si estás trabajando con un proxy corporativo que intercepta TLS (una configuración MITM, bastante común en entornos empresariales), la solución correcta es importar el certificado CA del proxy, no desactivar la verificación.
Autenticación con --proxy-user
También puedes separar las credenciales en su propia opción en lugar de meterlas en la URL:
curl -x "http://proxy.example:8080" --proxy-user "user:pwd" "https://httpbin.org/ip"
Ojo: la -U en mayúscula no es lo mismo que la autenticación del sitio destino (-u / --user, en minúscula). Confundirlas es una forma fácil de enviar la contraseña del proxy al destino equivocado. En entornos corporativos que usan NTLM o Digest en lugar de Basic, añade --proxy-ntlm o --proxy-digest junto con --proxy-user.
Cómo usar cURL con un proxy SOCKS: SOCKS4 vs. SOCKS5 vs. socks5h
Los proxies SOCKS funcionan a un nivel más bajo que los HTTP: no les importa qué protocolo estás tunelizando, lo que los hace útiles para tráfico que no sea HTTP, circuitos Tor y cualquier cosa sensible para la privacidad. La mayoría de guías de la competencia reducen esto a un solo comando y listo. Eso es un error, porque las diferencias entre SOCKS4, SOCKS5 y socks5h:// de verdad importan.
| Función | SOCKS4 | SOCKS5 | socks5h:// |
|---|---|---|---|
| Soporte TCP | Sí | Sí | Sí |
| Soporte UDP | No | Sí | Sí |
| Autenticación | No | Sí | Sí |
| Resolución DNS remota | No | No (DNS local) | Sí (el proxy resuelve) |
| Compatible con Tor | No | Arriesgado (fuga DNS) | Sí |
La fila de resolución DNS es la que realmente hace tropezar a la gente. Con socks5://, tu máquina resuelve el nombre de host antes de entregar la conexión al proxy, lo que significa que tu resolvedor DNS local (y, por extensión, tu ISP) ve exactamente a qué dominio intentas acceder, aunque el tráfico HTTP real pase por el proxy. socks5h:// lo corrige haciendo que el proxy resuelva el nombre de host, de modo que no se filtre localmente nada sobre el destino. Esta es la razón por la que la documentación de Tor insiste en socks5h://: usar socks5:// sin la h anula una buena parte del anonimato que Tor pretende ofrecer.
Aquí va cada variante en cURL:
curl --socks4 "proxy.example:1080" "http://example.com"
curl -x "socks5://user:pwd@proxy.example:1080" "http://example.com"
curl -x "socks5h://user:pwd@proxy.example:1080" "http://example.com"
Salvo que tengas un motivo específico para no hacerlo, usa socks5h:// por defecto. No cuesta nada extra y evita una fuga que, de otro modo, probablemente nunca notarías.
Configurar el proxy con variables de entorno (y evitar las trampas)
Poner -x en cada comando se vuelve tedioso muy rápido. Las variables de entorno te permiten definir el proxy una sola vez por sesión de shell y hacer que todas las llamadas posteriores de cURL lo hereden automáticamente; el manual de cURL documenta http_proxy, HTTPS_PROXY, ALL_PROXY y NO_PROXY como el conjunto compatible.
Lo básico
export http_proxy="http://user:pwd@proxy.example:8080"
export HTTPS_PROXY="http://user:pwd@proxy.example:8080"
export ALL_PROXY="socks5h://proxy.example:1080"
La parte que constantemente confunde a la gente es esta: el nombre de la variable se refiere al protocolo de la URL de destino, no al del proxy. Así que http_proxy gobierna solicitudes a URLs http://, y HTTPS_PROXY gobierna solicitudes a URLs https://; puedes apuntar ambas al mismo servidor proxy HTTP sin problema, y eso es totalmente normal.
Omitir con NO_PROXY
export NO_PROXY="localhost,127.0.0.1,.internal.example"
Va separado por comas, y el punto inicial en .internal.example actúa como comodín para cualquier subdominio. NO_PROXY tiene prioridad sobre todo lo demás: incluso si -x está definido explícitamente en la línea de comandos, una coincidencia en NO_PROXY hará que esa solicitud se salte el proxy.
Las trampas que realmente hacen caer a la gente
- Olvidar
export. Si solo escribeshttp_proxy=http://...sinexport, la variable solo vive en tu shell actual y cURL, como proceso hijo, no la ve en absoluto. En mi experiencia, esta es la causa más común de los tickets de soporte del tipo «el proxy no funciona». - Sensibilidad a mayúsculas y minúsculas. cURL comprueba específicamente primero
http_proxyen minúsculas y le da prioridad si existen ambas variantes. Otras herramientas solo leen la versión en mayúsculas. Si estás intentando averiguar por qué una variable «no se recoge», busca si hay un duplicado con distinta capitalización. - La trampa del alias de PowerShell. En PowerShell 5.1, escribir
curlno ejecuta cURL: lanzaInvoke-WebRequest, una herramienta totalmente distinta con opciones distintas. Si tu opción-xda errores extraños en Windows, escribecurl.exeexplícitamente para asegurarte de que estás usando cURL de verdad. - Diferencias de sintaxis en Windows. CMD usa
set http_proxy=...; PowerShell usa$env:http_proxy = "...". Confundir estos formatos entre sesiones de terminal es una forma fácil de perder una tarde. - Variables obsoletas.
unset http_proxyyunset https_proxylimpian una configuración de proxy muerta que, sin que te des cuenta, está enroutando —y fallando— todas las solicitudes.
Para alternar rápido, un par de alias en tu .bashrc ahorran tiempo real:
alias proxyon='export http_proxy="http://proxy.example:8080"; export https_proxy="http://proxy.example:8080"'
alias proxyoff='unset http_proxy; unset https_proxy'
Hacer que cURL use siempre un proxy (archivo de configuración)
Si trabajas detrás de un proxy corporativo el 95% del tiempo, un archivo .curlrc (en sistemas tipo Unix, en tu carpeta personal) o _curlrc (en Windows, en la carpeta de app data) establece un valor predeterminado persistente sin tocar variables de entorno:
proxy="http://proxy.example:8080"
Para cualquier solicitud puntual en la que necesites omitirlo, --noproxy "*" sobrescribe la configuración solo para esa ejecución. La prioridad suele ser opción de línea de comandos > variable de entorno > archivo de configuración, así que -x en la línea de comandos siempre gana si hay conflicto.
Una advertencia importante: no pongas una contraseña en texto plano dentro de .curlrc si el archivo puede sincronizarse, respaldarse o acabar por accidente en un repositorio. En pipelines de CI, usa el gestor de secretos de tu plataforma e inyecta las credenciales como variables de entorno ocultas en su lugar.
Cómo verificar que tu proxy realmente está funcionando
Esta es la sección que casi todas las demás guías se saltan, y la que más tiempo de depuración ahorra. Configurar un proxy y asumir que está encaminando el tráfico es cómo la gente se pasa horas resolviendo problemas de un scraper que en realidad nunca estaba usando el proxy.
Método 1: comparar tu IP de salida
Ejecuta dos veces la misma petición que devuelve la IP: una directa y otra a través del proxy, y compara:
curl https://httpbin.org/ip
curl -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip
Si ambos comandos devuelven la misma IP, tu proxy no está haciendo nada. Revisa la sintaxis de la opción, tus variables de entorno o si NO_PROXY está coincidiendo por error con tu destino.
Método 2: leer la salida detallada
Añade -v a cualquier solicitud con proxy y cURL imprimirá todo el intercambio:
curl -v -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip
Busca una línea como * Connected to proxy.example (xx.xx.xx.xx) port 8080, seguida de > CONNECT httpbin.org:443 HTTP/1.1 y, finalmente, < HTTP/1.1 200 Connection established. Esa secuencia —conexión al proxy y luego túnel CONNECT al destino— es el método HTTP CONNECT en acción, y es exactamente lo que debe ocurrir cuando un destino HTTPS pasa por un proxy HTTP. Si esa línea CONNECT nunca aparece, la opción del proxy no se está aplicando. Una precaución aquí: usa -v solo mientras depuras activamente, y elimina información sensible antes de compartir la salida en cualquier sitio, porque el modo detallado puede mostrar credenciales del proxy en texto plano.
Método 3: comparar lado a lado
Para pruebas de geolocalización específicamente, guarda ambas salidas en archivos y compáralas:
curl https://httpbin.org/ip > direct.json
curl -x "http://user:pwd@proxy.example:8080" https://httpbin.org/ip > proxied.json
diff direct.json proxied.json
Si el contenido de la respuesta (o las cabeceras, en contenido restringido por región) es distinto, tienes una confirmación visual de que el proxy realmente está cambiando tu ruta de red: una forma rápida y barata de despejar dudas antes de seguir investigando.
Solución de problemas de errores comunes de proxy en cURL
La mayoría de las guías pasan por aquí de puntillas y mencionan -k una vez. Este tema merece una tabla de referencia de verdad.
| Error | Causa probable | Solución |
|---|---|---|
curl: (7) Failed to connect | Host/puerto del proxy incorrectos, o el proxy está caído | Verifica la dirección; prueba la conectividad básica con telnet host port o nc -zv host port |
407 Proxy Authentication Required | Credenciales del proxy ausentes o incorrectas | Añade --proxy-user user:pass; comprueba si el proveedor requiere NTLM/Digest/Negotiate en lugar de Basic |
curl: (56) Recv failure: Connection reset by peer | El proxy cortó la conexión a mitad de la transferencia | Revisa la estabilidad del proxy con el proveedor; si es un proxy que termina TLS, verifica el manejo de certificados en vez de desactivar la validación |
curl: (28) Connection timed out | Firewall bloqueando, proxy obsoleto o puerto equivocado | Ejecuta env | grep -i proxy para buscar variables residuales; elimina las obsoletas; prueba una solicitud directa para aislar la causa |
| Fallo de verificación de certificado | Certificado del proxy no confiable o interceptado | Obtén la cadena CA correcta y usa --proxy-cacert; evita desactivar la verificación salvo en un diagnóstico puntual |
La primera acción universal para cualquiera de estos casos es añadir -v. Te dice exactamente en qué punto se rompe la conexión —resolución DNS, conexión TCP, handshake TLS o intercambio de autenticación con el proxy— en lugar de dejarte adivinar a partir de un código de tres dígitos.
Para proxies corporativos específicamente, --proxy-ntlm y --proxy-negotiate cubren esquemas de autenticación de dominios Windows. Hay una cosa que cURL de verdad no maneja de forma nativa: los archivos PAC (scripts de Proxy Auto-Config que algunas empresas usan para asignar proxies dinámicamente). Si tu empresa usa uno, tendrás que extraer manualmente el host y el puerto reales del proxy —normalmente desde los ajustes de red del navegador— porque cURL no incluye un analizador PAC integrado.
Cuando cURL + un proxy no son suficientes
cURL con un proxy funciona muy bien para HTML estático, llamadas a APIs REST y descargas sencillas de datos. Donde se queda corto es frente a las defensas favoritas de la web moderna: aplicaciones de una sola página renderizadas con JavaScript, sistemas anti-bot como Cloudflare o Akamai y muros de CAPTCHA. Si apuntas cURL a una app en React o Vue detrás de una de estas capas, lo normal es que te devuelva un <div id="root"></div> vacío: técnicamente una respuesta correcta, prácticamente datos inútiles. Eso no es un fallo de cURL. Simplemente no es un navegador, y nunca pretendió serlo.
Si ya te sientes cómodo ejecutando cURL desde la terminal y llegas a ese límite, el siguiente paso natural no es cambiar a una pila de herramientas totalmente distinta, sino añadir una capa que se encargue del renderizado y de la estructura por ti. Ahí es donde están pensadas para encajar las herramientas para desarrolladores de Thunderbit.
| Escenario | cURL + Proxy | API de Thunderbit (POST /extract) |
|---|---|---|
| Página HTML estática | Funciona perfectamente | Funciona y además devuelve datos estructurados |
| SPA renderizada con JS | Devuelve HTML vacío o parcial | renderMode: "full" maneja el JS |
| Anti-bot / CAPTCHA | Bloqueado | Manejo integrado |
| Salida de datos estructurados | HTML sin procesar: tendrás que analizarlo tú | JSON según tu propio esquema |
| Lotes (100+ URLs) | Bucle manual + tu propia limitación de tasa | POST /batch/extract |
La API abierta de Thunderbit expone un endpoint /extract que devuelve JSON ajustado al esquema directamente desde páginas con mucho JavaScript, y un endpoint /distill para convertir contenido limpio a Markdown; ambos pueden llamarse desde la misma sesión de terminal en la que ya estabas ejecutando comandos cURL. También hay un servidor MCP para asistentes de programación con IA como Claude o Cursor, y un CLI (npx @thunderbit/thunderbit-cli extract <url> --schema fields.json) si prefieres seguir trabajando completamente en scripts. Nada de esto reemplaza a cURL en las tareas en las que cURL es bueno; simplemente toma el relevo donde cURL ya no puede ir más lejos estructuralmente. Si quieres una visión más amplia de dónde encaja la extracción asistida por IA frente a escribir tu propia lógica de scraping, nuestro resumen sobre AI web scraping y nuestra comparación de los mejores AI web scrapers lo explican con más detalle, y nuestro artículo sobre web scraping sin código es una buena introducción si vienes desde el mundo de negocio y no desde ingeniería.
Conclusión
Conseguir que cURL y un proxy se entiendan correctamente no es difícil cuando sabes dónde están los puntos reales de fallo, y resulta que casi ninguno es el proxy en sí. Olvidar export. Confundir -u con -U. Usar socks5:// cuando querías socks5h://. Ejecutar el alias curl de PowerShell en lugar de curl.exe. Cada uno de estos errores genera un mensaje confuso y genérico que no tiene nada que ver con el proveedor del proxy.
El hábito que más tiempo ahorra: verifica antes de depurar. Ejecuta la comprobación de la IP, echa un vistazo a la salida de -v y confirma que el proxy realmente está en la ruta de la solicitud antes de asumir que algo falla más abajo. Y cuando tu destino empiece a devolverte JavaScript en lugar de HTML limpio, eso no es un problema de cURL que se resuelva con más opciones: es una señal de que necesitas una herramienta pensada para renderizar, como la API de Thunderbit, que ofrece un plan gratuito si quieres comprobar por ti mismo la diferencia entre recibir JSON y recibir HTML sin procesar.
Preguntas frecuentes
¿cURL usa un proxy por defecto?
No. A menos que hayas configurado las variables de entorno http_proxy / HTTPS_PROXY o un archivo .curlrc, cURL se conecta directamente al destino sin usar proxy.
¿Cómo hago para que cURL no use proxy en una sola solicitud?
Añade --noproxy "*" a ese comando concreto. Para quitarlo de toda la sesión de shell, ejecuta unset http_proxy && unset https_proxy.
¿Puedo usar cURL con proxies rotativos?
Sí. Si tu proveedor ofrece una puerta de enlace rotativa (un único endpoint que asigna una IP nueva por solicitud), basta con apuntar -x a esa dirección como harías con cualquier otro proxy. Para una lógica de rotación más compleja frente a destinos renderizados con JavaScript, una capa de API como la de Thunderbit gestiona internamente la rotación y la parte anti-bot, así no tienes que montar la lógica de reintentos a mano.
¿Por qué socks5:// filtra mis consultas DNS pero socks5h:// no?
Con socks5://, tu máquina local resuelve el nombre de host de destino antes de enviar la solicitud de conexión al proxy, lo que significa que el resolvedor DNS de tu ISP ve el dominio que visitas. socks5h:// traslada la resolución del nombre de host al propio proxy, así que localmente no se ve nada sobre el destino.
¿Es legal usar cURL con un proxy?
Usar un proxy es legal en la mayoría de jurisdicciones por sí solo. Lo que importa es para qué lo uses: respeta siempre los términos de servicio del sitio destino, robots.txt cuando aplique y cualquier ley de privacidad de datos relevante. Esta guía cubre solo la mecánica técnica, no una aprobación legal para ningún caso concreto.
Más información
