Como Descarregar Ficheiros com curl

Q: Qual e a diferenca entre curl -o e curl -O?

-o filename guarda o download com o nome de ficheiro exato que especificar. -O extrai o nome do ficheiro do URL e usa-o. Use -o quando quiser um nome ou caminho personalizado; use -O quando o nome do ficheiro remoto for adequado.

Q: Como retomo um ficheiro parcialmente descarregado com curl?

Use curl -C - -o filename URL. A opcao -C - deteta o tamanho do ficheiro existente e envia um cabecalho Range para solicitar apenas os bytes restantes. O servidor deve suportar pedidos de intervalo para que isto funcione.

Q: Como limito a velocidade de download no curl?

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

Q: O curl pode descarregar multiplos ficheiros de uma vez?

Sim. Use multiplas opcoes -O: curl -O URL1 -O URL2 -O URL3. O curl descarrega-os sequencialmente. Para downloads paralelos, encaminhe uma lista de URLs para xargs -P 4 -I {} curl -O {}.

Q: Como descarrego um ficheiro que requer autenticacao?

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

Q: Como descarrego ficheiros de um servidor FTP com curl?

Use curl -u user:pass -o localfile ftp://host/path/file. O curl suporta FTP, FTPS (FTP sobre TLS) e SFTP (SSH FTP) nativamente. Para FTP anonimo, omita -u.

Q: Como descarrego ficheiros grandes de forma fiavel com curl?

Combine -C - (retomar em caso de falha), --retry 5 (nova tentativa automatica), --retry-delay 10 e -L (seguir redirecionamentos): curl -C - --retry 5 --retry-delay 10 -L -o file URL. Isto lida automaticamente com interrupcoes de rede.

Q: Como mostro uma barra de progresso ao descarregar com curl?

Use curl -# -o file URL para uma barra de progresso simples. A saida predefinida do curl ja mostra velocidade de transferencia, percentagem e tempo estimado. Para scripts, use -s para suprimir toda a saida.

Q: Posso especificar um diretorio de download no curl?

Com curl 7.73+, use --output-dir /path/to/dir combinado com -O. Para versoes mais antigas, especifique o caminho completo com -o /path/to/dir/filename. Adicione --create-dirs se o diretorio ainda nao existir.

O curl e uma das ferramentas de linha de comandos mais versateis para descarregar ficheiros atraves de HTTP, HTTPS, FTP e dezenas de outros protocolos. Quer precise de guardar uma resposta de API num ficheiro ou automatizar downloads em massa num script shell, o curl tem uma opcao para isso. Este guia cobre todas as opcoes relacionadas com downloads — desde guardar ficheiros basicos com -o e -O ate retomar transferencias interrompidas com -C -, limitar a largura de banda com --limit-rate e mostrar barras de progresso. Cada opcao inclui uma explicacao clara, padroes de utilizacao comuns e um exemplo pronto a copiar.

Referencia Rapida das Opcoes de Download

Opcao	Descricao
-o	Escrever a saida num ficheiro com nome especificado em vez do stdout
-O	Escrever a saida num ficheiro com o nome do ficheiro remoto
-L	Seguir automaticamente redirecionamentos HTTP 3xx
-C -	Continuar/retomar uma transferencia de ficheiro anterior
--limit-rate	Limitar a velocidade de transferencia a uma taxa especificada
--max-filesize	Recusar descarregar ficheiros maiores do que o tamanho especificado
-J	Usar o cabecalho Content-Disposition para nomear o ficheiro
-#	Exibir o progresso da transferencia como uma barra de progresso simples
-u	Fornecer utilizador:palavra-passe para autenticacao no servidor
--retry	Tentar novamente a transferencia em erros transitorios (numero de vezes)
--retry-delay	Aguardar este numero de segundos entre tentativas
-T	Enviar um ficheiro local para um URL (PUT por defeito)
--create-dirs	Criar diretorios locais conforme necessario ao guardar a saida
-s	Suprimir o medidor de progresso e mensagens de erro
--output-dir	Guardar ficheiro(s) de saida no diretorio especificado (curl 7.73+)

-o

Escrever a saida num ficheiro com nome especificado em vez do stdout

-O

Escrever a saida num ficheiro com o nome do ficheiro remoto

-L

Seguir automaticamente redirecionamentos HTTP 3xx

-C -

Continuar/retomar uma transferencia de ficheiro anterior

--limit-rate

Limitar a velocidade de transferencia a uma taxa especificada

--max-filesize

Recusar descarregar ficheiros maiores do que o tamanho especificado

-J

Usar o cabecalho Content-Disposition para nomear o ficheiro

Exibir o progresso da transferencia como uma barra de progresso simples

-u

Fornecer utilizador:palavra-passe para autenticacao no servidor

--retry

Tentar novamente a transferencia em erros transitorios (numero de vezes)

--retry-delay

Aguardar este numero de segundos entre tentativas

-T

Enviar um ficheiro local para um URL (PUT por defeito)

--create-dirs

Criar diretorios locais conforme necessario ao guardar a saida

-s

Suprimir o medidor de progresso e mensagens de erro

--output-dir

Guardar ficheiro(s) de saida no diretorio especificado (curl 7.73+)

curl -o: Guardar com um Nome de Ficheiro Especifico

O que faz: A opcao -o (ou --output) indica ao curl para guardar o corpo da resposta num ficheiro que voce especifica. Sem ela, o curl imprime a resposta no stdout (o seu terminal). Pode usar qualquer nome de ficheiro e caminho — o curl criara o ficheiro ou substituira um existente.
Utilizacao comum: Use -o quando precisar de controlar o nome exato do ficheiro ou guardar num diretorio especifico. Funciona com qualquer protocolo — HTTP, HTTPS, FTP, SFTP e outros. Combine com -L para lidar com redirecionamentos e -s para operacao silenciosa em scripts.

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

curl -O: Guardar com o Nome de Ficheiro Remoto

O que faz: A opcao -O (ou --remote-name) guarda o ficheiro descarregado usando o nome extraido do URL. Por exemplo, se o URL terminar com /data.csv, o curl cria um ficheiro chamado data.csv no diretorio atual.
Utilizacao comum: Use -O quando o nome do ficheiro remoto for significativo e nao precisar de o renomear. Pode passar multiplas opcoes -O para descarregar varios ficheiros num so comando. Nota: se o URL nao contiver um nome de ficheiro (p. ex., terminar com /), o curl falhara — use -o em alternativa.

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

curl -L: Seguir Redirecionamentos

O que faz: A opcao -L (ou --location) faz com que o curl siga automaticamente redirecionamentos HTTP — 301 (Moved Permanently), 302 (Found), 307 e 308. Sem -L, o curl devolve a propria resposta de redirecionamento em vez do conteudo real.
Utilizacao comum: A maioria dos URLs de download redireciona pelo menos uma vez (p. ex., de HTTP para HTTPS, ou de um URL curto para o ficheiro real). Combine sempre -L com -o ou -O ao descarregar ficheiros. Por defeito, o curl segue ate 50 redirecionamentos; altere isto 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 opcao -C - (ou --continue-at -) indica ao curl para detetar automaticamente o tamanho do ficheiro parcial existente e retomar o download a partir do ponto onde parou. O servidor deve suportar o cabecalho HTTP Range para que isto funcione.
Utilizacao comum: Se um download grande foi interrompido por um problema de rede ou timeout, basta re-executar o mesmo comando com -C - adicionado. O curl enviara um cabecalho Range: bytes=OFFSET- e descarregara apenas os dados restantes. Isto e essencial para ficheiros grandes em ligacoes instáveis.

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

curl --limit-rate: Limitar a Velocidade de Download

O que faz: A opcao --limit-rate limita a velocidade de download (e upload) a taxa especificada. Aceita sufixos: k ou K para kilobytes/s, m ou M para megabytes/s, g ou G para gigabytes/s.
Utilizacao comum: Use --limit-rate para evitar saturar a sua largura de banda ao descarregar ficheiros grandes, especialmente em ligacoes partilhadas. Tambem e util para testar como a sua aplicacao lida com respostas lentas.

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

curl --max-filesize: Abortar se o Ficheiro For Demasiado Grande

O que faz: A opcao --max-filesize indica ao curl para abortar a transferencia se o tamanho esperado do ficheiro (do cabecalho Content-Length) exceder o limite especificado. O tamanho pode usar sufixos como k, M, G.
Utilizacao comum: Use em scripts para evitar que downloads inesperadamente grandes consumam espaco em disco. Note que nem todos os servidores enviam Content-Length — nesse caso, o curl nao pode impor este limite e o download prossegue normalmente.

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

curl -J: Usar o Nome de Ficheiro Sugerido pelo Servidor

O que faz: A opcao -J (ou --remote-header-name) indica ao curl para usar o nome de ficheiro especificado no cabecalho Content-Disposition do servidor em vez de o derivar do URL. Isto e comum em APIs de download que devolvem ficheiros com nomes significativos.
Utilizacao comum: Combine sempre -J com -O. Isto e util quando o URL e um endpoint de API (como /export?format=csv) mas o servidor devolve um nome de ficheiro adequado nos cabecalhos. Nota de seguranca: o servidor controla o nome do ficheiro, portanto use apenas com servidores de confianca.

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

curl -#: Mostrar uma Barra de Progresso

O que faz: A opcao -# (ou --progress-bar) substitui o medidor de progresso verboso predefinido por uma barra de progresso simples ###. E mais facil de ler para uso interativo.
Utilizacao comum: Use -# quando estiver a descarregar interativamente e quiser um indicador de progresso limpo. Para scripts, prefira -s (silencioso) ou o medidor de progresso predefinido. A saida predefinida do curl ja mostra velocidade, percentagem, tempo restante e tamanho total.

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

Opcoes de Download Adicionais

Opcao	Descricao
-u	Fornecer utilizador:palavra-passe para autenticacao no servidor
--retry	Tentar novamente a transferencia em erros transitorios (numero de vezes)
--retry-delay	Aguardar este numero de segundos entre tentativas
-T	Enviar um ficheiro local para um URL (PUT por defeito)
--create-dirs	Criar diretorios locais conforme necessario ao guardar a saida
-s	Suprimir o medidor de progresso e mensagens de erro
--output-dir	Guardar ficheiro(s) de saida no diretorio especificado (curl 7.73+)

-u

Fornecer utilizador:palavra-passe para autenticacao no servidor

--retry

Tentar novamente a transferencia em erros transitorios (numero de vezes)

--retry-delay

Aguardar este numero de segundos entre tentativas

-T

Enviar um ficheiro local para um URL (PUT por defeito)

--create-dirs

Criar diretorios locais conforme necessario ao guardar a saida

-s

Suprimir o medidor de progresso e mensagens de erro

--output-dir

Guardar ficheiro(s) de saida no diretorio especificado (curl 7.73+)

Cenarios Reais de Download

Estes exemplos combinam multiplas opcoes para lidar com tarefas comuns de download que encontrara no desenvolvimento e scripting do dia a dia.

Descarregar Multiplos Ficheiros de Uma Vez

Use multiplas opcoes -O para descarregar varios ficheiros num so comando. O curl processa-os 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

Descarregar 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 de ficheiro remoto.

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

Descarregar com Autenticacao

Use -u user:pass para Basic Auth, ou -H para passar um Bearer token 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 Fiavel com Retoma e Novas Tentativas

Combine -C - (retomar), --retry (nova tentativa automatica em caso de falha) e -L (seguir redirecionamentos) para downloads robustos que sobrevivem a interrupcoes 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 e a diferenca entre curl -o e curl -O?

-o filename guarda o download com o nome de ficheiro exato que especificar. -O extrai o nome do ficheiro do URL e usa-o. Use -o quando quiser um nome ou caminho personalizado; use -O quando o nome do ficheiro remoto for adequado.

Porque e que o curl descarrega um ficheiro vazio ou HTML em vez do ficheiro real?

O URL provavelmente devolve um redirecionamento HTTP (301 ou 302). Por defeito, o curl guarda a propria resposta de redirecionamento — nao o conteudo final. Adicione -L para seguir redirecionamentos automaticamente: curl -L -o file URL.

Como retomo um ficheiro parcialmente descarregado com curl?

Use curl -C - -o filename URL. A opcao -C - deteta o tamanho do ficheiro existente e envia um cabecalho Range para solicitar apenas os bytes restantes. O servidor deve suportar pedidos de intervalo para que isto funcione.

Como limito a velocidade de download no curl?

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

O curl pode descarregar multiplos ficheiros de uma vez?

Sim. Use multiplas opcoes -O: curl -O URL1 -O URL2 -O URL3. O curl descarrega-os sequencialmente. Para downloads paralelos, encaminhe uma lista de URLs para xargs -P 4 -I {} curl -O {}.

Como descarrego um ficheiro que requer autenticacao?

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

Como descarrego ficheiros de um servidor FTP com curl?

Use curl -u user:pass -o localfile ftp://host/path/file. O curl suporta FTP, FTPS (FTP sobre TLS) e SFTP (SSH FTP) nativamente. Para FTP anonimo, omita -u.

Como descarrego ficheiros grandes de forma fiavel com curl?

Combine -C - (retomar em caso de falha), --retry 5 (nova tentativa automatica), --retry-delay 10 e -L (seguir redirecionamentos): curl -C - --retry 5 --retry-delay 10 -L -o file URL. Isto lida automaticamente com interrupcoes de rede.

Como mostro uma barra de progresso ao descarregar com curl?

Use curl -# -o file URL para uma barra de progresso simples. A saida predefinida do curl ja mostra velocidade de transferencia, percentagem e tempo estimado. Para scripts, use -s para suprimir toda a saida.

Posso especificar um diretorio de download no curl?

Com curl 7.73+, use --output-dir /path/to/dir combinado com -O. Para versoes mais antigas, especifique o caminho completo com -o /path/to/dir/filename. Adicione --create-dirs se o diretorio ainda nao existir.

Devo usar curl ou wget para descarregar ficheiros?

Ambos sao excelentes. O wget e mais simples para espelhamento recursivo de websites e tem logica de nova tentativa integrada. O curl suporta mais de 25 protocolos (nao apenas HTTP/FTP), e melhor para chamadas de API e scripting, suporta mais metodos de autenticacao e esta disponivel em praticamente todos os sistemas operativos.

Como uso o curl num script bash para descarregar ficheiros?

Use curl -fsSL -o file URL: -f falha silenciosamente em erros HTTP (sem pagina de erro guardada), -s silencioso, -S mostra erros mesmo no modo silencioso, -L segue redirecionamentos. Verifique o codigo de saida: if ! curl -fsSL -o file URL; then echo "Download failed"; exit 1; fi.