Como baixar arquivos com curl

Q: Qual a diferença entre curl -o e curl -O?

-o nomedoarquivo salva o download com o nome exato que você especifica. -O extrai o nome do arquivo da URL e usa esse. Use -o quando quiser um nome ou caminho personalizado; use -O quando o nome do arquivo remoto for adequado.

Q: Como retomar um arquivo parcialmente baixado com curl?

Use curl -C - -o nomedoarquivo URL. A flag -C - detecta o tamanho do arquivo existente e envia um header Range para solicitar apenas os bytes restantes. O servidor deve suportar requisições de range para isso funcionar.

Q: Como limitar a velocidade de download no curl?

Use --limit-rate com um valor e sufixo: curl --limit-rate 500k -o arquivo URL limita a velocidade a 500 KB/s. Sufixos: k (KB/s), M (MB/s), G (GB/s).

Q: O curl pode baixar múltiplos arquivos de uma vez?

Sim. Use múltiplas flags -O: curl -O URL1 -O URL2 -O URL3. O curl baixa sequencialmente. Para downloads paralelos, encaminhe uma lista de URLs para xargs -P 4 -I {} curl -O {}.

Q: Como baixar um arquivo que requer autenticação?

Para HTTP Basic Auth: curl -u user:pass -o arquivo URL. Para tokens Bearer: curl -H "Authorization: Bearer TOKEN" -o arquivo URL. Para chaves de API em headers: curl -H "X-API-Key: KEY" -o arquivo URL.

Q: Como baixar arquivos de um servidor FTP com curl?

Use curl -u user:pass -o arquivolocal ftp://host/caminho/arquivo. O curl suporta FTP, FTPS (FTP sobre TLS) e SFTP (SSH FTP) nativamente. Para FTP anônimo, omita -u.

Q: Como baixar arquivos grandes de forma confiável com curl?

Combine -C - (retomar em caso de falha), --retry 5 (nova tentativa automática), --retry-delay 10 e -L (seguir redirecionamentos): curl -C - --retry 5 --retry-delay 10 -L -o arquivo URL. Isso lida automaticamente com problemas de rede.

Q: Como mostrar uma barra de progresso ao baixar com curl?

Use curl -# -o arquivo URL para uma barra de progresso simples. A saída padrão do curl já mostra velocidade de transferência, porcentagem e tempo estimado. Para scripts, use -s para suprimir toda a saída.

Q: Posso especificar um diretório de download no curl?

Com curl 7.73+, use --output-dir /caminho/para/diretorio combinado com -O. Para versões mais antigas, especifique o caminho completo com -o /caminho/para/diretorio/nomedoarquivo. Adicione --create-dirs se o diretório ainda não existir.

curl é uma das ferramentas de linha de comando mais versáteis para baixar arquivos via HTTP, HTTPS, FTP e dezenas de outros protocolos. Seja para salvar uma única resposta de API em um arquivo ou automatizar downloads em lote em um script shell, o curl tem uma flag para isso. Este guia cobre todas as opções relacionadas a download — desde o salvamento básico de arquivos com -o e -O até a retomada de transferências interrompidas com -C -, limitação de largura de banda com --limit-rate e exibição de barras de progresso. Cada flag inclui uma explicação clara, padrões de uso comuns e um exemplo pronto para copiar.

Referência rápida de flags de download

Flag	Descrição
-o	Gravar saída em um arquivo nomeado em vez de stdout
-O	Gravar saída em um arquivo com o mesmo nome do arquivo remoto
-L	Seguir redirecionamentos HTTP 3xx automaticamente
-C -	Continuar/retomar uma transferência de arquivo anterior
--limit-rate	Limitar a velocidade de transferência à taxa especificada
--max-filesize	Recusar o download de arquivos maiores que o tamanho especificado
-J	Usar o header Content-Disposition para nomear o arquivo
-#	Exibir progresso da transferência como uma barra de progresso simples
-u	Fornecer usuário:senha para autenticação no servidor
--retry	Tentar novamente a transferência em erros transitórios (número de vezes)
--retry-delay	Esperar este número de segundos entre tentativas
-T	Enviar um arquivo local para uma URL (PUT por padrão)
--create-dirs	Criar diretórios locais conforme necessário ao salvar a saída
-s	Suprimir medidor de progresso e mensagens de erro
--output-dir	Salvar arquivo(s) de saída no diretório especificado (curl 7.73+)

-o

Gravar saída em um arquivo nomeado em vez de stdout

-O

Gravar saída em um arquivo com o mesmo nome do arquivo remoto

-L

Seguir redirecionamentos HTTP 3xx automaticamente

-C -

Continuar/retomar uma transferência de arquivo anterior

--limit-rate

Limitar a velocidade de transferência à taxa especificada

--max-filesize

Recusar o download de arquivos maiores que o tamanho especificado

-J

Usar o header Content-Disposition para nomear o arquivo

Exibir progresso da transferência como uma barra de progresso simples

-u

Fornecer usuário:senha para autenticação no servidor

--retry

Tentar novamente a transferência em erros transitórios (número de vezes)

--retry-delay

Esperar este número de segundos entre tentativas

-T

Enviar um arquivo local para uma URL (PUT por padrão)

--create-dirs

Criar diretórios locais conforme necessário ao salvar a saída

-s

Suprimir medidor de progresso e mensagens de erro

--output-dir

Salvar arquivo(s) de saída no diretório especificado (curl 7.73+)

curl -o: Salvar com um nome de arquivo específico

O que faz: A flag -o (ou --output) instrui o curl a salvar o corpo da resposta em um arquivo que você especifica. Sem ela, o curl imprime a resposta no stdout (seu terminal). Você pode usar qualquer nome de arquivo e caminho — o curl criará o arquivo ou sobrescreverá um existente.
Uso comum: Use -o quando precisar controlar o nome exato do arquivo ou salvar em um diretório específico. Funciona com qualquer protocolo — HTTP, HTTPS, FTP, SFTP e mais. Combine com -L para lidar com redirecionamentos e -s para operação silenciosa em scripts.

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

curl -O: Salvar com o nome do arquivo remoto

O que faz: A flag -O (ou --remote-name) salva o arquivo baixado usando o nome extraído da URL. Por exemplo, se a URL termina com /data.csv, o curl cria um arquivo chamado data.csv no diretório atual.
Uso comum: Use -O quando o nome do arquivo remoto é significativo e você não precisa renomeá-lo. Você pode passar múltiplas flags -O para baixar vários arquivos em um único comando. Nota: se a URL não contém um nome de arquivo (ex: termina com /), o curl falhará — use -o em vez disso.

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

curl -L: Seguir redirecionamentos

O que faz: A flag -L (ou --location) faz o curl seguir automaticamente redirecionamentos HTTP — 301 (Movido Permanentemente), 302 (Encontrado), 307 e 308. Sem -L, o curl retorna a resposta de redirecionamento em si, em vez do conteúdo real.
Uso comum: A maioria das URLs de download redireciona pelo menos uma vez (ex: de HTTP para HTTPS, ou de uma URL curta para o arquivo real). Sempre combine -L com -o ou -O ao baixar arquivos. Por padrão, o curl segue até 50 redirecionamentos; altere com --max-redirs.

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

curl -C -: Retomar downloads interrompidos

O que faz: A flag -C - (ou --continue-at -) instrui o curl a detectar automaticamente o tamanho do arquivo parcial existente e retomar o download de onde parou. O servidor deve suportar o header HTTP Range para isso funcionar.
Uso comum: Se um download grande foi interrompido por um problema de rede ou timeout, simplesmente execute o mesmo comando novamente com -C - adicionado. O curl enviará um header Range: bytes=OFFSET- e baixará apenas os dados restantes. Isso é essencial para arquivos grandes em conexões instáveis.

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

curl --limit-rate: Limitar velocidade de download

O que faz: A flag --limit-rate limita a velocidade de download (e upload) à taxa especificada. Aceita sufixos: k ou K para kilobytes/s, m ou M para megabytes/s, g ou G para gigabytes/s.
Uso comum: Use --limit-rate para evitar saturar sua largura de banda ao baixar arquivos grandes, especialmente em conexões compartilhadas. Também é útil para testar como sua aplicação lida com respostas lentas.

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

curl --max-filesize: Abortar se o arquivo for muito grande

O que faz: A flag --max-filesize instrui o curl a abortar a transferência se o tamanho esperado do arquivo (do header Content-Length) exceder o limite especificado. O tamanho pode usar sufixos como k, M, G.
Uso comum: Use em scripts para evitar que downloads inesperadamente grandes consumam espaço em disco. Note que nem todos os servidores enviam Content-Length — nesse caso, o curl não pode aplicar este limite e o download prossegue normalmente.

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

curl -J: Usar nome de arquivo sugerido pelo servidor

O que faz: A flag -J (ou --remote-header-name) instrui o curl a usar o nome de arquivo especificado no header Content-Disposition do servidor, em vez de extraí-lo da URL. Isso é comum em APIs de download que retornam arquivos com nomes significativos.
Uso comum: Sempre combine -J com -O. Isso é útil quando a URL é um endpoint de API (como /export?format=csv) mas o servidor retorna um nome de arquivo adequado nos headers. Nota de segurança: o servidor controla o nome do arquivo, então use apenas com servidores confiáveis.

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

curl -#: Mostrar barra de progresso

O que faz: A flag -# (ou --progress-bar) substitui o medidor de progresso detalhado padrão por uma barra de progresso simples ###. É mais fácil de ler para uso interativo.
Uso comum: Use -# ao baixar interativamente quando quiser um indicador de progresso limpo. Para scripts, prefira -s (silencioso) ou o medidor de progresso padrão. A saída padrão do curl já mostra velocidade, porcentagem, tempo restante e tamanho total.

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

Opções adicionais de download

Flag	Descrição
-u	Fornecer usuário:senha para autenticação no servidor
--retry	Tentar novamente a transferência em erros transitórios (número de vezes)
--retry-delay	Esperar este número de segundos entre tentativas
-T	Enviar um arquivo local para uma URL (PUT por padrão)
--create-dirs	Criar diretórios locais conforme necessário ao salvar a saída
-s	Suprimir medidor de progresso e mensagens de erro
--output-dir	Salvar arquivo(s) de saída no diretório especificado (curl 7.73+)

-u

Fornecer usuário:senha para autenticação no servidor

--retry

Tentar novamente a transferência em erros transitórios (número de vezes)

--retry-delay

Esperar este número de segundos entre tentativas

-T

Enviar um arquivo local para uma URL (PUT por padrão)

--create-dirs

Criar diretórios locais conforme necessário ao salvar a saída

-s

Suprimir medidor de progresso e mensagens de erro

--output-dir

Salvar arquivo(s) de saída no diretório especificado (curl 7.73+)

Cenários reais de download

Estes exemplos combinam múltiplas flags para lidar com tarefas comuns de download que você encontrará no desenvolvimento e scripting do dia a dia.

Baixar múltiplos arquivos de uma vez

Use múltiplas flags -O para baixar vários arquivos em um único comando. O curl os processa sequencialmente. Para downloads paralelos, use xargs ou GNU parallel.

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

Baixar de um servidor FTP

O curl suporta FTP, FTPS e SFTP nativamente. Adicione -u user:password para acesso autenticado. Use -O para manter o nome do arquivo remoto.

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

Download com autenticação

Use -u user:pass para Basic Auth, ou -H para passar um token Bearer ou chave de API. Combine com -L e -o para um download completo.

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

Download confiável com retomada e novas tentativas

Combine -C - (retomar), --retry (nova tentativa automática em caso de falha) e -L (seguir redirecionamentos) para downloads robustos que sobrevivem a interrupções de rede.

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

Perguntas frequentes sobre download com curl

Qual a diferença entre curl -o e curl -O?

-o nomedoarquivo salva o download com o nome exato que você especifica. -O extrai o nome do arquivo da URL e usa esse. Use -o quando quiser um nome ou caminho personalizado; use -O quando o nome do arquivo remoto for adequado.

Por que o curl baixa um arquivo vazio ou HTML em vez do arquivo real?

A URL provavelmente retorna um redirecionamento HTTP (301 ou 302). Por padrão, o curl salva a resposta de redirecionamento em si — não o conteúdo final. Adicione -L para seguir redirecionamentos automaticamente: curl -L -o arquivo URL.

Como retomar um arquivo parcialmente baixado com curl?

Use curl -C - -o nomedoarquivo URL. A flag -C - detecta o tamanho do arquivo existente e envia um header Range para solicitar apenas os bytes restantes. O servidor deve suportar requisições de range para isso funcionar.

Como limitar a velocidade de download no curl?

Use --limit-rate com um valor e sufixo: curl --limit-rate 500k -o arquivo URL limita a velocidade a 500 KB/s. Sufixos: k (KB/s), M (MB/s), G (GB/s).

O curl pode baixar múltiplos arquivos de uma vez?

Sim. Use múltiplas flags -O: curl -O URL1 -O URL2 -O URL3. O curl baixa sequencialmente. Para downloads paralelos, encaminhe uma lista de URLs para xargs -P 4 -I {} curl -O {}.

Como baixar um arquivo que requer autenticação?

Para HTTP Basic Auth: curl -u user:pass -o arquivo URL. Para tokens Bearer: curl -H "Authorization: Bearer TOKEN" -o arquivo URL. Para chaves de API em headers: curl -H "X-API-Key: KEY" -o arquivo URL.

Como baixar arquivos de um servidor FTP com curl?

Use curl -u user:pass -o arquivolocal ftp://host/caminho/arquivo. O curl suporta FTP, FTPS (FTP sobre TLS) e SFTP (SSH FTP) nativamente. Para FTP anônimo, omita -u.

Como baixar arquivos grandes de forma confiável com curl?

Combine -C - (retomar em caso de falha), --retry 5 (nova tentativa automática), --retry-delay 10 e -L (seguir redirecionamentos): curl -C - --retry 5 --retry-delay 10 -L -o arquivo URL. Isso lida automaticamente com problemas de rede.

Como mostrar uma barra de progresso ao baixar com curl?

Use curl -# -o arquivo URL para uma barra de progresso simples. A saída padrão do curl já mostra velocidade de transferência, porcentagem e tempo estimado. Para scripts, use -s para suprimir toda a saída.

Posso especificar um diretório de download no curl?

Com curl 7.73+, use --output-dir /caminho/para/diretorio combinado com -O. Para versões mais antigas, especifique o caminho completo com -o /caminho/para/diretorio/nomedoarquivo. Adicione --create-dirs se o diretório ainda não existir.

Devo usar curl ou wget para baixar arquivos?

Ambos são excelentes. wget é mais simples para espelhamento recursivo de sites e tem lógica de nova tentativa integrada. curl suporta mais de 25 protocolos (não apenas HTTP/FTP), é melhor para chamadas de API e scripting, suporta mais métodos de autenticação e está disponível em praticamente todos os sistemas operacionais.

Como usar curl em um script bash para baixar arquivos?

Use curl -fsSL -o arquivo URL: -f falha silenciosamente em erros HTTP (nenhuma página de erro salva), -s silencioso, -S mostra erros mesmo em modo silencioso, -L segue redirecionamentos. Verifique o código de saída: if ! curl -fsSL -o arquivo URL; then echo "Download falhou"; exit 1; fi.