Cómo descargar archivos con curl

Q: ¿Cuál es la diferencia entre curl -o y curl -O?

-o nombre_archivo guarda la descarga con el nombre de archivo exacto que especifiques. -O extrae el nombre del archivo de la URL y lo usa. Usa -o cuando quieras un nombre o ruta personalizada; usa -O cuando el nombre del archivo remoto sea adecuado.

Q: ¿Cómo reanudo un archivo parcialmente descargado con curl?

Usa curl -C - -o nombre_archivo URL. El flag -C - detecta el tamaño del archivo existente y envía un encabezado Range para solicitar solo los bytes restantes. El servidor debe soportar solicitudes de rango para que esto funcione.

Q: ¿Cómo limito la velocidad de descarga en curl?

Usa --limit-rate con un valor y sufijo: curl --limit-rate 500k -o archivo URL limita la velocidad a 500 KB/s. Sufijos: k (KB/s), M (MB/s), G (GB/s).

Q: ¿Puede curl descargar múltiples archivos a la vez?

Sí. Usa múltiples flags -O: curl -O URL1 -O URL2 -O URL3. curl los descarga secuencialmente. Para descargas paralelas, pasa una lista de URLs a xargs -P 4 -I {} curl -O {}.

Q: ¿Cómo descargo un archivo que requiere autenticación?

Para HTTP Basic Auth: curl -u user:pass -o archivo URL. Para tokens Bearer: curl -H "Authorization: Bearer TOKEN" -o archivo URL. Para claves API en encabezados: curl -H "X-API-Key: KEY" -o archivo URL.

Q: ¿Cómo descargo archivos desde un servidor FTP con curl?

Usa curl -u user:pass -o archivo_local ftp://host/ruta/archivo. curl soporta FTP, FTPS (FTP sobre TLS) y SFTP (SSH FTP) de forma nativa. Para FTP anónimo, omite -u.

Q: ¿Cómo descargo archivos grandes de forma fiable con curl?

Combina -C - (reanudar en error), --retry 5 (reintento automático), --retry-delay 10 y -L (seguir redirecciones): curl -C - --retry 5 --retry-delay 10 -L -o archivo URL. Esto maneja automáticamente los problemas de red.

Q: ¿Cómo muestro una barra de progreso al descargar con curl?

Usa curl -# -o archivo URL para una barra de progreso simple. La salida predeterminada de curl ya muestra velocidad de transferencia, porcentaje y tiempo estimado. Para scripts, usa -s para suprimir toda la salida.

Q: ¿Puedo especificar un directorio de descarga en curl?

Con curl 7.73+, usa --output-dir /ruta/al/directorio combinado con -O. Para versiones anteriores, especifica la ruta completa con -o /ruta/al/directorio/nombre_archivo. Añade --create-dirs si el directorio aún no existe.

curl es una de las herramientas de línea de comandos más versátiles para descargar archivos mediante HTTP, HTTPS, FTP y docenas de otros protocolos. Ya sea que necesites guardar una respuesta de API en un archivo o automatizar descargas masivas en un script de shell, curl tiene un flag para ello. Esta guía cubre todas las opciones relacionadas con la descarga — desde el guardado básico de archivos con -o y -O hasta la reanudación de transferencias interrumpidas con -C -, la limitación de ancho de banda con --limit-rate y la visualización de barras de progreso. Cada flag incluye una explicación clara, patrones de uso comunes y un ejemplo listo para copiar.

Referencia rápida de flags de descarga

Flag	Descripción
-o	Escribir la salida en un archivo con nombre en lugar de stdout
-O	Escribir la salida en un archivo nombrado como el archivo remoto
-L	Seguir automáticamente redirecciones HTTP 3xx
-C -	Continuar/reanudar una transferencia de archivo previa
--limit-rate	Limitar la velocidad de transferencia a la tasa especificada
--max-filesize	Rechazar descargas mayores que el tamaño especificado
-J	Usar el encabezado Content-Disposition para nombrar el archivo
-#	Mostrar el progreso de la transferencia como una barra de progreso simple
-u	Especificar usuario:contraseña para autenticación del servidor
--retry	Reintentar la transferencia ante errores temporales (número de veces)
--retry-delay	Esperar esta cantidad de segundos entre reintentos
-T	Subir un archivo local a una URL (PUT por defecto)
--create-dirs	Crear directorios locales según sea necesario al guardar la salida
-s	Suprimir medidor de progreso y mensajes de error
--output-dir	Guardar archivo(s) de salida en el directorio especificado (curl 7.73+)

-o

Escribir la salida en un archivo con nombre en lugar de stdout

-O

Escribir la salida en un archivo nombrado como el archivo remoto

-L

Seguir automáticamente redirecciones HTTP 3xx

-C -

Continuar/reanudar una transferencia de archivo previa

--limit-rate

Limitar la velocidad de transferencia a la tasa especificada

--max-filesize

Rechazar descargas mayores que el tamaño especificado

-J

Usar el encabezado Content-Disposition para nombrar el archivo

Mostrar el progreso de la transferencia como una barra de progreso simple

-u

Especificar usuario:contraseña para autenticación del servidor

--retry

Reintentar la transferencia ante errores temporales (número de veces)

--retry-delay

Esperar esta cantidad de segundos entre reintentos

-T

Subir un archivo local a una URL (PUT por defecto)

--create-dirs

Crear directorios locales según sea necesario al guardar la salida

-s

Suprimir medidor de progreso y mensajes de error

--output-dir

Guardar archivo(s) de salida en el directorio especificado (curl 7.73+)

curl -o: Guardar con un nombre de archivo específico

Qué hace: El flag -o (o --output) indica a curl que guarde el cuerpo de la respuesta en un archivo que especifiques. Sin él, curl imprime la respuesta en stdout (tu terminal). Puedes usar cualquier nombre de archivo y ruta — curl crea el archivo o sobrescribe uno existente.
Uso típico: Usa -o cuando necesites controlar el nombre exacto del archivo o guardar en un directorio específico. Funciona con todos los protocolos — HTTP, HTTPS, FTP, SFTP y más. Combina con -L para redirecciones y -s para operación silenciosa en scripts.

$ curl -o report.pdf https://example.com/files/report.pdf

curl -O: Guardar con el nombre del archivo remoto

Qué hace: El flag -O (o --remote-name) guarda el archivo descargado con el nombre de archivo extraído de la URL. Por ejemplo, si la URL termina en /data.csv, curl crea un archivo llamado data.csv en el directorio actual.
Uso típico: Usa -O cuando el nombre del archivo remoto sea significativo y no necesites renombrarlo. Puedes pasar múltiples flags -O para descargar varios archivos con un solo comando. Nota: si la URL no contiene un nombre de archivo (p. ej., termina en /), curl falla — usa -o en su lugar.

$ curl -O https://example.com/files/data.csv

curl -L: Seguir redirecciones

Qué hace: El flag -L (o --location) indica a curl que siga automáticamente las redirecciones HTTP — 301 (Moved Permanently), 302 (Found), 307 y 308. Sin -L, curl devuelve la propia respuesta de redirección en lugar del contenido real.
Uso típico: La mayoría de las URLs de descarga redirigen al menos una vez (p. ej., de HTTP a HTTPS o de una URL corta al archivo real). Combina siempre -L con -o o -O al descargar archivos. Por defecto, curl sigue hasta 50 redirecciones; modifica esto con --max-redirs.

$ curl -L -o latest.tar.gz https://github.com/user/repo/releases/latest/download/app.tar.gz

curl -C -: Reanudar descargas interrumpidas

Qué hace: El flag -C - (o --continue-at -) indica a curl que detecte automáticamente el tamaño del archivo parcial existente y reanude la descarga desde donde se detuvo. El servidor debe soportar el encabezado HTTP Range para que esto funcione.
Uso típico: Si una descarga grande fue interrumpida por un problema de red o tiempo de espera, simplemente ejecuta el mismo comando de nuevo con -C - añadido. curl envía un encabezado Range: bytes=OFFSET- y descarga solo los datos restantes. Esto es esencial para archivos grandes sobre conexiones poco fiables.

$ curl -C - -o largefile.zip https://cdn.example.com/largefile.zip

curl --limit-rate: Limitar la velocidad de descarga

Qué hace: El flag --limit-rate establece un límite superior en la velocidad de descarga (y subida) a la tasa especificada. Acepta sufijos: k o K para kilobytes/s, m o M para megabytes/s, g o G para gigabytes/s.
Uso típico: Usa --limit-rate para evitar saturar tu ancho de banda al descargar archivos grandes, especialmente en conexiones compartidas. También es útil para probar cómo tu aplicación maneja respuestas lentas.

$ curl --limit-rate 1M -o bigfile.iso https://mirror.example.com/bigfile.iso

curl --max-filesize: Abortar si el archivo es demasiado grande

Qué hace: El flag --max-filesize indica a curl que aborte la transferencia si el tamaño esperado del archivo (del encabezado Content-Length) supera el límite especificado. El tamaño puede usar sufijos como k, M, G.
Uso típico: Úsalo en scripts para evitar que descargas inesperadamente grandes consuman espacio en disco. Ten en cuenta que no todos los servidores envían Content-Length — en ese caso, curl no puede aplicar este límite y la descarga continúa normalmente.

$ curl --max-filesize 100M -o update.bin https://example.com/update.bin

curl -J: Usar el nombre de archivo sugerido por el servidor

Qué hace: El flag -J (o --remote-header-name) indica a curl que use el nombre de archivo especificado en el encabezado Content-Disposition del servidor en lugar de extraerlo de la URL. Esto es común en APIs de descarga que devuelven archivos con nombres significativos.
Uso típico: Combina siempre -J con -O. Esto es útil cuando la URL es un endpoint de API (como /export?format=csv) pero el servidor devuelve un nombre de archivo correcto en los encabezados. Nota de seguridad: el servidor controla el nombre del archivo — úsalo solo con servidores de confianza.

$ curl -L -O -J https://example.com/api/export?format=csv

curl -#: Mostrar una barra de progreso

Qué hace: El flag -# (o --progress-bar) reemplaza el medidor de progreso detallado predeterminado con una barra de progreso simple ###. Es más fácil de leer en uso interactivo.
Uso típico: Usa -# al descargar interactivamente cuando quieras un indicador de progreso limpio. Para scripts, prefiere -s (silencioso) o el medidor de progreso predeterminado. La salida predeterminada de curl ya muestra velocidad, porcentaje, tiempo restante y tamaño total.

$ curl -# -o archive.tar.gz https://example.com/archive.tar.gz

Opciones adicionales de descarga

Flag	Descripción
-u	Especificar usuario:contraseña para autenticación del servidor
--retry	Reintentar la transferencia ante errores temporales (número de veces)
--retry-delay	Esperar esta cantidad de segundos entre reintentos
-T	Subir un archivo local a una URL (PUT por defecto)
--create-dirs	Crear directorios locales según sea necesario al guardar la salida
-s	Suprimir medidor de progreso y mensajes de error
--output-dir	Guardar archivo(s) de salida en el directorio especificado (curl 7.73+)

-u

Especificar usuario:contraseña para autenticación del servidor

--retry

Reintentar la transferencia ante errores temporales (número de veces)

--retry-delay

Esperar esta cantidad de segundos entre reintentos

-T

Subir un archivo local a una URL (PUT por defecto)

--create-dirs

Crear directorios locales según sea necesario al guardar la salida

-s

Suprimir medidor de progreso y mensajes de error

--output-dir

Guardar archivo(s) de salida en el directorio especificado (curl 7.73+)

Escenarios de descarga del mundo real

Estos ejemplos combinan múltiples flags para manejar tareas comunes de descarga que encontrarás en el desarrollo diario y scripting.

Descargar múltiples archivos a la vez

Usa múltiples flags -O para descargar varios archivos con un solo comando. curl los procesa secuencialmente. Para descargas paralelas, usa xargs o GNU parallel.

$ curl -O https://example.com/file1.txt -O https://example.com/file2.txt -O https://example.com/file3.txt

Descargar desde un servidor FTP

curl soporta FTP, FTPS y SFTP de forma nativa. Añade -u user:password para acceso autenticado. Usa -O para mantener el nombre del archivo remoto.

$ curl -u user:pass -o backup.sql ftp://ftp.example.com/db/backup.sql

Descargar con autenticación

Usa -u user:pass para Basic Auth o -H para enviar un token Bearer o clave API. Combina con -L y -o para una descarga completa.

$ curl -H "Authorization: Bearer eyJhbGciOi..." -L -o data.json https://api.example.com/export

Descarga fiable con reanudación y reintento

Combina -C - (reanudar), --retry (reintento automático en error) y -L (seguir redirecciones) para descargas robustas que sobrevivan a interrupciones de red.

$ curl -C - --retry 5 --retry-delay 10 -L -o largefile.zip https://cdn.example.com/largefile.zip

Preguntas frecuentes sobre descarga de archivos con curl

¿Cuál es la diferencia entre curl -o y curl -O?

-o nombre_archivo guarda la descarga con el nombre de archivo exacto que especifiques. -O extrae el nombre del archivo de la URL y lo usa. Usa -o cuando quieras un nombre o ruta personalizada; usa -O cuando el nombre del archivo remoto sea adecuado.

¿Por qué curl descarga un archivo vacío o HTML en lugar del archivo real?

La URL probablemente devuelve una redirección HTTP (301 o 302). Por defecto, curl guarda la propia respuesta de redirección — no el contenido final. Añade -L para seguir redirecciones automáticamente: curl -L -o archivo URL.

¿Cómo reanudo un archivo parcialmente descargado con curl?

Usa curl -C - -o nombre_archivo URL. El flag -C - detecta el tamaño del archivo existente y envía un encabezado Range para solicitar solo los bytes restantes. El servidor debe soportar solicitudes de rango para que esto funcione.

¿Cómo limito la velocidad de descarga en curl?

Usa --limit-rate con un valor y sufijo: curl --limit-rate 500k -o archivo URL limita la velocidad a 500 KB/s. Sufijos: k (KB/s), M (MB/s), G (GB/s).

¿Puede curl descargar múltiples archivos a la vez?

Sí. Usa múltiples flags -O: curl -O URL1 -O URL2 -O URL3. curl los descarga secuencialmente. Para descargas paralelas, pasa una lista de URLs a xargs -P 4 -I {} curl -O {}.

¿Cómo descargo un archivo que requiere autenticación?

Para HTTP Basic Auth: curl -u user:pass -o archivo URL. Para tokens Bearer: curl -H "Authorization: Bearer TOKEN" -o archivo URL. Para claves API en encabezados: curl -H "X-API-Key: KEY" -o archivo URL.

¿Cómo descargo archivos desde un servidor FTP con curl?

Usa curl -u user:pass -o archivo_local ftp://host/ruta/archivo. curl soporta FTP, FTPS (FTP sobre TLS) y SFTP (SSH FTP) de forma nativa. Para FTP anónimo, omite -u.

¿Cómo descargo archivos grandes de forma fiable con curl?

Combina -C - (reanudar en error), --retry 5 (reintento automático), --retry-delay 10 y -L (seguir redirecciones): curl -C - --retry 5 --retry-delay 10 -L -o archivo URL. Esto maneja automáticamente los problemas de red.

¿Cómo muestro una barra de progreso al descargar con curl?

Usa curl -# -o archivo URL para una barra de progreso simple. La salida predeterminada de curl ya muestra velocidad de transferencia, porcentaje y tiempo estimado. Para scripts, usa -s para suprimir toda la salida.

¿Puedo especificar un directorio de descarga en curl?

Con curl 7.73+, usa --output-dir /ruta/al/directorio combinado con -O. Para versiones anteriores, especifica la ruta completa con -o /ruta/al/directorio/nombre_archivo. Añade --create-dirs si el directorio aún no existe.

¿Debería usar curl o wget para descargar archivos?

Ambos son excelentes. wget es más simple para mirroring recursivo de sitios web y tiene lógica de reintento incorporada. curl soporta más de 25 protocolos (no solo HTTP/FTP), es mejor para llamadas API y scripting, soporta más métodos de autenticación y está disponible en prácticamente todos los sistemas operativos.

¿Cómo uso curl en un script bash para descargar archivos?

Usa curl -fsSL -o archivo URL: -f falla silenciosamente en errores HTTP (no se guarda página de error), -s silencioso, -S muestra errores incluso en modo silencioso, -L sigue redirecciones. Verifica el código de salida: if ! curl -fsSL -o archivo URL; then echo "Descarga fallida"; exit 1; fi.