Saltar para o conteúdo
Comece grátis
Voltar ao blogue

Como baixar arquivos com Python: guia prático

Gabriel CiociÚltima atualização em 16 min read
Como baixar arquivos com Python: guia prático
Resumo: este guia mostra como baixar arquivos com Python, de uma única linha de código até pipelines autenticados, retomáveis, paralelos e assíncronos. Você vai aprender quando usar urllib, requests, ThreadPoolExecutor ou aiohttp, como fazer streaming de conteúdos grandes, adicionar uma barra de progresso tqdm de verdade, repetir com backoff e verificar a integridade com checksums e Content-Length.

Se você já automatizou um backup, fez scraping de um conjunto de dados ou montou um pipeline de dados, sabe que baixar arquivos com Python é uma daquelas tarefas que parecem triviais até chegar à produção. Uma chamada urlretrieve de duas linhas funciona bem para um CSV de 100 KB no seu notebook. Ela desmorona no momento em que você precisa baixar um arquivo compactado de 5 GB por uma VPN instável, retomar uma transferência pela metade ou puxar mil imagens de produtos protegidas por login.

Este artigo é o guia que eu queria ter tido quando escrevi meu primeiro script de download que precisava rodar por uma semana. Vamos começar com o trecho de código mais simples possível e, depois, acrescentar streaming, barras de progresso, transferências retomáveis, threads, E/S assíncrona, autenticação, verificações de integridade e novas tentativas. Cada seção traz um exemplo executável que você pode colar em um virtualenv com Python 3.9 ou mais recente.

No fim, você deve conseguir olhar para uma URL, prever onde ela pode falhar, escolher a ferramenta certa e copiar um trecho de código que lide com essas falhas.

Por que aprender a baixar arquivos com Python (e quando não usar)

curl e wget são excelentes para downloads pontuais. Então por que aprender a baixar arquivos com Python? Por três motivos: programabilidade, portabilidade e integração. Quando um download vive dentro de um script Python, você pode encadeá-lo com o pandas, adicionar lógica de novas tentativas, interpretar cabeçalhos Content-Disposition, enviar o resultado para o S3 e rodar o mesmo código no macOS, Linux e Windows sem reescrever uma única linha.

Python nem sempre é a resposta certa. Para uma transferência única em um pipeline de shell, curl --fail --retry 5 exige menos digitação. Se você vai mover centenas de gigabytes entre dois servidores, aria2c ou rclone vão saturar sua conexão com mais eficiência. Python vence quando a próxima etapa do pipeline também está em Python, ou quando "baixar" na verdade significa "buscar, validar, transformar e encaminhar".

Para acompanhar, você vai precisar de Python 3.9+, pip e um virtualenv. Vamos instalar requests, aiohttp e tqdm ao longo do caminho.

O caminho mais rápido: downloads em uma linha com urllib.request.urlretrieve()

A forma mais rápida de aprender a baixar arquivos com Python é começar pela biblioteca padrão. O urllib vem com toda instalação do Python, então não há nada para instalar com pip. Sua função auxiliar de mais alto nível é urlretrieve, que copia uma URL direto para um caminho local:

from urllib.request import urlretrieve

url = "https://example.com/reports/q3.csv"
filename, headers = urlretrieve(url, "q3.csv")
print(filename, headers["Content-Type"])

A função retorna uma tupla (filename, HTTPMessage). O HTTPMessage é um contêiner parecido com um dicionário que guarda os cabeçalhos da resposta, útil quando você quer conferir Content-Type, Content-Length ou Last-Modified sem fazer uma segunda requisição.

Se você omitir o segundo argumento, o Python grava em um arquivo temporário (normalmente em /tmp/ no Unix ou no diretório temporário do usuário no Windows) e devolve o caminho gerado automaticamente. É útil em scripts descartáveis e perigoso em produção, onde arquivos temporários são removidos em momentos imprevisíveis.

As limitações que você precisa conhecer:

  • Sem streaming. urlretrieve lê todo o corpo da resposta na memória antes de gravar no disco. Qualquer coisa acima de algumas centenas de megabytes vai doer.
  • Modelo de erros fraco. Um 404 gera urllib.error.HTTPError, mas os timeouts aparecem como o URLError, mais genérico, e não há novas tentativas embutidas.
  • Sem reutilização de sessão. Cada chamada abre uma nova conexão TCP.

Para downloads pequenos e pontuais, o urlretrieve resolve. Para qualquer coisa mais exigente, você vai querer o requests.

Baixando com a biblioteca requests para ter mais controle

O requests é o cliente HTTP padrão de fato do Python e oferece uma API muito mais rica que o urllib. Instale uma vez:

pip install requests

O padrão básico de download tem três linhas:

import requests

resp = requests.get("https://example.com/files/sample.pdf", timeout=30)
resp.raise_for_status()
with open("sample.pdf", "wb") as f:
    f.write(resp.content)

Três pontos importam aqui. Primeiro, sempre passe timeout. Sem ele, um servidor lento pode travar seu worker indefinidamente. Segundo, raise_for_status() transforma qualquer resposta 4xx ou 5xx em exceção, para que você não grave silenciosamente uma página de erro HTML no disco. Terceiro, resp.content retorna bytes brutos, que é o que você quer para qualquer conteúdo binário. Use resp.text apenas quando o corpo for texto e você quiser decodificá-lo com o charset da resposta, e resp.json() só quando o servidor estiver retornando JSON.

Inspecionando códigos de status, cabeçalhos e Content-Type

Antes de gravar um único byte, confira a resposta. Um 200 significa sucesso, um 3xx já deveria ter sido seguido automaticamente pelo requests, e qualquer 4xx ou 5xx indica um bug ou uma instabilidade temporária. Leia resp.headers["Content-Type"] para confirmar que recebeu o tipo MIME esperado, e resp.headers.get("Content-Length") para saber o tamanho do arquivo. Se houver um cabeçalho Content-Disposition, interprete-o (requests.utils.parse_header_links ou uma pequena expressão regular) para obter o nome de arquivo sugerido pelo servidor, em vez de adivinhá-lo pelo caminho da URL.

Salvando a resposta: arquivos de texto, JSON, CSV e binários

Combine o modo de gravação com o tipo de conteúdo. Modos incompatíveis são, de longe, o motivo mais comum para um arquivo baixado parecer correto em um dump hexadecimal mas se recusar a abrir.

# Binary (PDF, ZIP, image, executable): always 'wb'
with open("report.pdf", "wb") as f:
    f.write(resp.content)

# Plain text: 'w' with an explicit encoding
with open("README.md", "w", encoding="utf-8") as f:
    f.write(resp.text)

# JSON: parse, then dump with indentation for diff-friendly storage
import json
with open("payload.json", "w", encoding="utf-8") as f:
    json.dump(resp.json(), f, indent=2, ensure_ascii=False)

# CSV from a remote URL: stream into the csv module
import csv, io
reader = csv.reader(io.StringIO(resp.text))
with open("rows.csv", "w", newline="", encoding="utf-8") as f:
    csv.writer(f).writerows(reader)

Fique atento a duas armadilhas de codificação. O requests deduz a codificação da resposta pelos cabeçalhos, e essa dedução às vezes está errada. Se aparecerem caracteres embaralhados (mojibake), defina resp.encoding = "utf-8" explicitamente antes de ler resp.text. E no Windows, abrir um arquivo de texto sem newline="" corrompe arquivos CSV, porque o módulo csv já emite quebras de linha \r\n.

Streaming de downloads grandes em blocos com requests

resp.content carrega a resposta inteira na RAM. Isso não é problema para um documento JSON de 200 KB, mas é um desastre para um arquivo de vários gigabytes. A solução é ativar o streaming e iterar. Esse é o padrão principal para baixar arquivos com Python em qualquer escala real:

import requests
from pathlib import Path

def download(url: str, dest: Path, chunk_size: int = 1024 * 64) -> Path:
    with requests.get(url, stream=True, timeout=(5, 30)) as resp:
        resp.raise_for_status()
        with dest.open("wb") as f:
            for chunk in resp.iter_content(chunk_size=chunk_size):
                if chunk:                # skip keep-alive empties
                    f.write(chunk)
    return dest

O que muda quando você passa stream=True? O requests envia o GET, lê apenas os cabeçalhos da resposta e deixa a conexão aberta. Em seguida, iter_content puxa os bytes do socket em buffers do tamanho de chunk_size. O uso de memória fica estável, seja qual for o tamanho do arquivo, e você pode processar os dados à medida que chegam, em vez de esperar o conteúdo completo.

Algumas observações práticas:

  • Escolha um tamanho de bloco entre 32 KB e 1 MB. Blocos minúsculos (1 KB) gastam CPU com o overhead do loop em Python, e blocos de vários megabytes anulam a vantagem do streaming. 64 KB é um padrão seguro, e de 256 KB a 1 MB fica mais rápido em conexões velozes.
  • Use um gerenciador de contexto. A forma with requests.get(...) garante que a conexão subjacente volte ao pool, mesmo que o seu loop de gravação gere uma exceção.
  • Não misture iter_content e resp.content. Ler .content depois do streaming coloca na memória tudo o que restou e elimina a economia.
  • Use um timeout em tupla. (connect, read) permite falhar rápido diante de um host fora do ar e, ao mesmo tempo, tolerar blocos lentos.

Se você não precisa de nenhum processamento por bloco, shutil.copyfileobj(resp.raw, f) é ainda mais enxuto, mas é preciso passar stream=True e chamar antes resp.raw.read = functools.partial(resp.raw.read, decode_content=True). Caso contrário, respostas codificadas com gzip são gravadas no disco ainda compactadas. Por isso, a maioria das equipes fica com o iter_content.

Adicionando uma barra de progresso com tqdm

Um download em streaming sem nenhum retorno visual parece travado, mesmo quando está funcionando. O tqdm resolve isso com três linhas a mais. O truque é dimensionar a barra com o cabeçalho Content-Length do servidor e atualizá-la com o tamanho de cada bloco:

import requests
from tqdm import tqdm

def download_with_bar(url: str, dest: str) -> None:
    with requests.get(url, stream=True, timeout=(5, 30)) as resp:
        resp.raise_for_status()
        total = int(resp.headers.get("Content-Length", 0)) or None
        with open(dest, "wb") as f, tqdm(
            total=total, unit="B", unit_scale=True, unit_divisor=1024,
            desc=dest,
        ) as bar:
            for chunk in resp.iter_content(chunk_size=64 * 1024):
                f.write(chunk)
                bar.update(len(chunk))

Dois detalhes costumam pegar as pessoas. Primeiro, Content-Length não é obrigatório. Servidores que usam chunked transfer encoding, ou proxies que recodificam o corpo, muitas vezes o omitem. O or None acima faz o tqdm exibir um indicador indeterminado, em vez de travar ou mostrar 0%. Segundo, unit_divisor=1024 faz a barra exibir valores em KiB e MiB. Remova-o se preferir unidades do SI. Confira os nomes exatos dos argumentos do tqdm na documentação do projeto antes de fixar uma versão, porque os kwargs mudaram entre versões.

Downloads retomáveis com requisições HTTP Range

Downloads retomáveis são o recurso que, discretamente, separa scripts amadores de ferramentas de produção. A especificação HTTP define um mecanismo de requisições Range que permite ao cliente pedir os bytes a partir de N, em vez da entidade inteira. Se o servidor tiver suporte, ele responde com 206 Partial Content e o trecho solicitado. Se não tiver, você recebe um 200 com o corpo completo, o sinal de que precisa recomeçar do zero.

import os, requests
from pathlib import Path

def download_resumable(url: str, dest: Path, chunk_size: int = 256 * 1024) -> Path:
    # Probe the server first
    head = requests.head(url, timeout=10, allow_redirects=True)
    head.raise_for_status()
    accepts_ranges = head.headers.get("Accept-Ranges", "").lower() == "bytes"
    total = int(head.headers.get("Content-Length", 0)) or None

    existing = dest.stat().st_size if dest.exists() else 0
    if total and existing == total:
        return dest                       # already complete
    if existing and not accepts_ranges:
        existing = 0                      # server cannot resume; restart
        dest.unlink(missing_ok=True)

    headers = {"Range": f"bytes={existing}-"} if existing else {}
    mode = "ab" if existing else "wb"

    with requests.get(url, headers=headers, stream=True, timeout=(5, 60)) as resp:
        if existing and resp.status_code != 206:
            raise RuntimeError("Server ignored Range header; restart from zero.")
        resp.raise_for_status()
        with dest.open(mode) as f:
            for chunk in resp.iter_content(chunk_size=chunk_size):
                f.write(chunk)
    return dest

Abra o arquivo no modo de anexação binária ("ab") ao retomar e confira se o servidor realmente retornou 206, porque algumas CDNs mal configuradas ignoram o cabeçalho Range e recomeçam silenciosamente. A URL de retomada precisa ser idêntica byte a byte entre as tentativas: uma query string diferente, uma URL pré-assinada reemitida ou um destino redirecionado podem quebrar a idempotência. Em tarefas críticas, guarde o ETag do arquivo final da resposta original e valide-o novamente ao retomar, para que uma mudança no servidor não corrompa o arquivo baixado pela metade.

Downloads paralelos com ThreadPoolExecutor e requests

Quando você tem uma lista de URLs e o gargalo é a latência de rede, e não a CPU, usar threads dá um ganho de velocidade de graça. Baixar arquivos é uma tarefa limitada por E/S: as threads passam quase todo o tempo bloqueadas em um socket, esperando bytes. Apesar do global interpreter lock (GIL) do Python, é justamente nesse tempo ocioso que as outras threads rodam, então um ThreadPoolExecutor com requests consegue buscar dezenas de arquivos ao mesmo tempo.

from concurrent.futures import ThreadPoolExecutor, as_completed
import requests
from pathlib import Path

def fetch(url: str, out_dir: Path) -> Path:
    dest = out_dir / Path(url).name
    with requests.get(url, stream=True, timeout=(5, 30)) as r:
        r.raise_for_status()
        with dest.open("wb") as f:
            for chunk in r.iter_content(64 * 1024):
                f.write(chunk)
    return dest

def fetch_many(urls, out_dir, max_workers=8):
    out_dir.mkdir(parents=True, exist_ok=True)
    with ThreadPoolExecutor(max_workers=max_workers) as ex:
        futures = {ex.submit(fetch, u, out_dir): u for u in urls}
        for fut in as_completed(futures):
            try:
                yield fut.result()
            except Exception as e:
                print(f"[fail] {futures[fut]}: {e}")

Ajuste max_workers com base no servidor de destino, não no número de núcleos da sua CPU. De 8 a 16 é um padrão sensato para a maioria das APIs públicas. Acima disso, muitos servidores começam a aplicar rate limiting. Se os seus downloads forem minúsculos (menos de ~50 KB cada), o overhead por requisição domina e as threads rendem menos do que você espera.

Evitando armadilhas comuns de multithreading

Três armadilhas pegam a maioria das equipes. Primeiro, duas threads gravando no mesmo caminho corrompem o arquivo. Gere o destino a partir de um hash da URL, e não só do nome base. Segundo, compartilhe uma única requests.Session entre as threads para reutilizar conexões TCP, mas nunca compartilhe o mesmo handle de arquivo aberto. Terceiro, as novas tentativas ficam dentro da função do worker, não em volta de executor.map, para que uma única URL instável não contamine o lote inteiro.

Downloads assíncronos com aiohttp e asyncio

Threads escalam tranquilamente até algumas dezenas de transferências simultâneas. Passando de cerca de 100 conexões ativas, a memória por thread e o custo de troca de contexto começam a pesar, e vale migrar para asyncio com aiohttp. O aiohttp é construído sobre o asyncio e usa um único event loop com corrotinas cooperativas, então disparar 500 downloads simultâneos quase não custa nada.

import asyncio, aiohttp
from pathlib import Path

async def fetch(session: aiohttp.ClientSession, url: str, out_dir: Path) -> Path:
    dest = out_dir / Path(url).name
    async with session.get(url, timeout=aiohttp.ClientTimeout(total=120)) as resp:
        resp.raise_for_status()
        with dest.open("wb") as f:
            async for chunk in resp.content.iter_chunked(64 * 1024):
                f.write(chunk)
    return dest

async def download_all(urls, out_dir: Path, concurrency: int = 32):
    out_dir.mkdir(parents=True, exist_ok=True)
    sem = asyncio.Semaphore(concurrency)
    connector = aiohttp.TCPConnector(limit=concurrency)
    async with aiohttp.ClientSession(connector=connector) as session:
        async def bound_fetch(u):
            async with sem:
                return await fetch(session, u, out_dir)
        return await asyncio.gather(*(bound_fetch(u) for u in urls),
                                    return_exceptions=True)

# asyncio.run(download_all(urls, Path("downloads")))

Algumas regras práticas. Reutilize uma única ClientSession para o lote inteiro. Criar uma por URL vaza conexões e derruba o desempenho. Combine um asyncio.Semaphore com o TCPConnector(limit=...) para que um limite de concorrência moderado valha tanto na camada da aplicação quanto na de transporte. return_exceptions=True faz uma URL com falha voltar como um valor, em vez de derrubar o gather inteiro.

Quando o assíncrono realmente supera as threads? Em linhas gerais: abaixo de 50 downloads simultâneos, threads são mais simples e igualmente rápidas. Entre 50 e algumas centenas, as duas abordagens funcionam e o assíncrono costuma usar menos memória. Acima disso, o assíncrono é a única opção realista. Confira iter_chunked e o formato do timeout na versão do aiohttp que você instalar, porque ambos mudaram ao longo das versões menores.

Baixando arquivos protegidos por login, cookies ou tokens

Muitos downloads do mundo real ficam atrás de autenticação. A forma certa de baixar arquivos com Python a partir de endpoints autenticados é pensar em três camadas: como as credenciais são anexadas, como a sessão persiste entre requisições e que tipo de expiração de token você precisa prever.

Tokens Bearer são os mais simples. A maioria das APIs modernas fornece um token e espera que você o envie em um cabeçalho Authorization:

import requests
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['API_TOKEN']}"
session.headers["User-Agent"] = "my-downloader/1.0"
resp = session.get("https://api.example.com/exports/123/data.csv", stream=True, timeout=30)

A autenticação HTTP Basic cabe em uma linha: requests.get(url, auth=("user", "password")). Busque as credenciais em variáveis de ambiente ou em um gerenciador de segredos, nunca em uma string fixa no código que vai para um repositório.

Logins baseados em cookies precisam de uma Session para lembrar os cookies definidos pela resposta do login. Envie o formulário de login com POST e reutilize a mesma sessão para a URL protegida:

session = requests.Session()
session.post(LOGIN_URL, data={"user": user, "pass": pw}, timeout=15)
resp = session.get(FILE_URL, stream=True, timeout=30)

URLs pré-assinadas, como as emitidas pelo AWS S3 ou pelo Google Cloud Storage, codificam as credenciais na query string e expiram após uma janela fixa (geralmente de 15 minutos a 1 hora). Trate-as como efêmeras: solicite uma URL nova logo antes do download, não as armazene em cache e nunca as registre em log, já que a assinatura concede acesso temporário. Se você também precisar passar por um proxy ou rotacionar IPs (comum em scraping com autenticação), defina session.proxies e pronto. Temos um guia mais completo sobre como usar um servidor proxy com o módulo requests, caso você precise de uma introdução.

Verificando downloads: checksums, tamanho e Content-Type

Um arquivo cujo download terminou não é a mesma coisa que um arquivo baixado corretamente. Três verificações baratas detectam a maior parte das corrupções.

import hashlib

def sha256_of(path, chunk=1024 * 1024):
    h = hashlib.sha256()
    with open(path, "rb") as f:
        for buf in iter(lambda: f.read(chunk), b""):
            h.update(buf)
    return h.hexdigest()

# 1. Checksum match (gold standard if the publisher provides one)
assert sha256_of("data.zip") == published_sha256

# 2. Size match (fast sanity check against Content-Length)
declared = int(resp.headers["Content-Length"])
actual = Path("data.zip").stat().st_size
assert declared == actual, f"size mismatch: {declared} vs {actual}"

# 3. MIME or magic-number sniffing
import mimetypes, magic   # python-magic; pip install python-magic
assert magic.from_file("data.zip", mime=True) == "application/zip"

Use-as em camadas. O Content-Length detecta transferências truncadas e não custa nada, já que você normalmente já tem o cabeçalho. A detecção de MIME pega o caso em que o servidor retornou uma página de erro HTML com status 200, algo surpreendentemente comum em CDNs mal configuradas. O SHA-256 é a única verificação que detecta adulteração durante a transferência ou corrupção silenciosa no disco, e é obrigatória sempre que o publicador fornecer um arquivo de checksum junto com o artefato.

Tratamento robusto de erros, timeouts e novas tentativas automáticas

Downloads em produção precisam de três coisas que os exemplos básicos não têm: timeouts explícitos, novas tentativas automáticas com backoff e um modelo de exceções coerente. O requests junto com o urllib3 já oferece tudo isso, basta conectar as peças:

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def make_session() -> requests.Session:
    s = requests.Session()
    retry = Retry(
        total=5,
        connect=3,
        read=3,
        backoff_factor=1.5,                       # 0, 1.5, 3, 6, 12 seconds
        status_forcelist=(429, 500, 502, 503, 504),
        allowed_methods=frozenset(["GET", "HEAD"]),
        raise_on_status=False,
    )
    adapter = HTTPAdapter(max_retries=retry, pool_connections=20, pool_maxsize=20)
    s.mount("https://", adapter)
    s.mount("http://", adapter)
    return s

session = make_session()
try:
    resp = session.get(url, stream=True, timeout=(5, 60))
    resp.raise_for_status()
except requests.exceptions.SSLError as e:
    log.error("SSL handshake failed: %s", e)
except requests.exceptions.ConnectionError as e:    # DNS, refused, dropped
    log.error("network unreachable: %s", e)
except requests.exceptions.HTTPError as e:
    log.error("HTTP %s on %s", resp.status_code, url)

Confira os nomes dos parâmetros na documentação de urllib3.Retry e HTTPAdapter para a versão que você instalar: allowed_methods substituiu o antigo method_whitelist, e alguns valores padrão mudaram. O timeout em tupla (connect, read) é a linha de maior impacto de todo o trecho: o timeout de conexão falha rápido em hosts fora do ar, e o timeout de leitura protege contra um servidor que abre a conexão e nunca envia um byte.

Como baixar arquivos com Python: escolhendo entre urllib, requests, aiohttp e wget

A resposta honesta para "qual biblioteca devo usar?" é "depende de cinco coisas". Esta é a matriz de decisão que eu deixo colada em um post-it:

Cenário

Melhor ferramenta

Por quê

Um arquivo, script descartável, sem permissão para pip

urllib.request.urlretrieve

Biblioteca padrão, nada para instalar, código trivial.

Um ou poucos arquivos, com timeouts e novas tentativas

requests + Session + Retry

API mais limpa, ecossistema maduro.

Um único arquivo >500 MB

requests com stream=True + tqdm + retomada via Range

Memória constante, transferências recuperáveis.

De 10 a ~100 URLs em paralelo

ThreadPoolExecutor + requests

Limitado por E/S, threads bastam, o código continua síncrono.

De centenas a milhares de URLs em paralelo

aiohttp + asyncio

Menos memória por conexão, melhor latência de cauda.

Autenticado, baseado em cookies, em várias etapas

requests.Session (ou aiohttp.ClientSession)

Suporte nativo a sessões e cookie jar.

Chamada a partir de um pipeline de shell

wget ou curl, não Python

Se o Python não agrega valor, não use.

Wrapper Python para o wget

python-wget

Serve para uso retomável no estilo CLI, com menos recursos que o requests.

Algumas regras gerais. Fixe um tamanho de bloco entre 32 KB e 1 MB e raramente vai precisar revisitá-lo. Sempre defina timeout. Sempre compare o Content-Length com os bytes gravados. Reutilize sessões em requisições ao mesmo host. E resista à vontade de partir para o assíncrono, a menos que você tenha de fato centenas de transferências simultâneas. Threads são mais simples, fáceis de depurar e quase sempre rápidas o suficiente.

Se o seu gargalo não é a biblioteca, mas o site de destino se defendendo com CAPTCHAs, bloqueios de IP ou fingerprinting de navegador, a questão já não é como baixar arquivos com Python. Trata-se de rotear suas requisições por IPs residenciais, rotacionar user agents e desbloquear a página antes mesmo de chamar iter_content. Esse é outro problema, abordado nos nossos guias focados em scraping.

Principais pontos

  • Para arquivos pequenos e pontuais, urllib.request.urlretrieve resolve em uma linha e sem dependências. Para todo o resto, use requests.
  • Sempre faça streaming de arquivos grandes com stream=True mais iter_content, escolha um tamanho de bloco entre 32 KB e 1 MB e compare os bytes gravados com o Content-Length.
  • Downloads retomáveis precisam de um cabeçalho HTTP Range, do modo de anexação binária e de uma verificação de que o servidor realmente respondeu 206 Partial Content.
  • Threads cobrem o paralelismo limitado por E/S até ~100 URLs. Passe para aiohttp e asyncio quando ultrapassar esse limite.
  • Downloads em produção devem incluir um timeout em tupla, um Retry do urllib3 com backoff e uma verificação de integridade (SHA-256, tamanho ou MIME).

FAQ

Como baixar um arquivo com Python sem instalar bibliotecas de terceiros?

Use o urllib.request da biblioteca padrão. urlretrieve(url, path) é a forma mais curta, e urlopen(url) com um loop de gravação shutil.copyfileobj é o equivalente compatível com streaming. Isso é útil em ambientes restritos, layers do AWS Lambda ou contêineres de vida curta, onde adicionar o requests seria exagero ou simplesmente impossível.

Como retomar um arquivo baixado parcialmente em Python?

Se o servidor não aceita requisições Range, não é possível retomar no sentido estrito. A alternativa é o download segmentado: divida o arquivo em N intervalos de bytes logo de início, baixe cada um em um arquivo .partN e concatene todos depois que as partes terminarem. Se isso também falhar, guarde o ETag original e só baixe de novo quando ele mudar; caso contrário, mantenha o que você já tem.

Como baixar um arquivo que exige login ou token de API?

Além de anexar as credenciais, planeje a rotação de tokens. Encapsule o cabeçalho de autenticação em um callable que busque um token novo ao receber 401 Unauthorized, guarde os refresh tokens no chaveiro do sistema operacional em vez de um arquivo simples e, se você usa OAuth, restrinja os scopes do token ao mínimo necessário para os downloads. Em lotes longos, renove o token de forma proativa antes de expirar, em vez de reagir depois.

Como verificar se um arquivo baixado não está corrompido?

Além dos checksums, faça uma verificação específica para o formato. Abra arquivos ZIP com zipfile.ZipFile.testzip(), valide JSON com json.loads e use pdfminer ou pypdf para confirmar que um PDF tem um trailer legível. Essas verificações pegam os casos em que os bytes batem com um checksum de referência que estava errado, ou em que o publicador substituiu silenciosamente o artefato por uma versão quebrada.

Devo usar requests, aiohttp ou wget para downloads grandes?

"Grande" depende da quantidade, não só do tamanho. Para um único arquivo grande, requests com streaming e retomada via Range vence, porque é mais fácil de depurar. Para muitos arquivos grandes em paralelo, o aiohttp mantém a memória estável. Só vale chamar o wget a partir do Python quando você precisa especificamente do modo espelho ou da recuperação recursiva; caso contrário, chame o wget em um script de shell e evite o overhead do subprocesso.

Conclusão e próximos passos

Baixar arquivos com Python do jeito certo é, acima de tudo, combinar a biblioteca com a carga de trabalho e não pular as partes chatas: timeouts, novas tentativas, verificações de integridade e transferências retomáveis. Comece com urlretrieve em protótipos, passe para o requests assim que precisar de controle, faça streaming de tudo que passar de algumas centenas de megabytes e só recorra ao aiohttp quando tiver um problema real de concorrência.

Um bom projeto para continuar: crie uma pequena CLI que receba uma lista de URLs, distribua os downloads por um ThreadPoolExecutor, grave um manifesto SHA-256 ao longo do processo e retome a partir dele ao reiniciar. Esse único script exercita quase tudo deste guia e vira a espinha dorsal de todo pipeline de download que você escrever depois.

Quando um trabalho exigir HTTP/2, transferências paralelas ou downloads retomáveis, nosso comparativo de alternativas ao wget compara curl, aria2, HTTPie e ferramentas parecidas.

Se os seus downloads estão sendo bloqueados por CAPTCHAs, rate limiting agressivo ou restrições geográficas, e não pelo seu próprio código, esse é o momento em que uma camada gerenciada de desbloqueio se paga. A Scraper API da WebScrapingAPI cuida da rotação de proxies, dos desafios anti-bot e das novas tentativas por trás de um único endpoint, para que você mantenha os padrões de download em Python deste artigo e troque apenas a camada de busca quando precisar. Escolha a ferramenta mais leve que realmente funciona e acrescente robustez à medida que o seu tráfego e os seus dados exigirem.

Sobre o autor

Gabriel Cioci, Desenvolvedor Full-Stack @ WebScrapingAPI

Gabriel Cioci

Desenvolvedor Full-Stack

Gabriel Cioci é um programador Full Stack na WebScrapingAPI, responsável pela criação e manutenção dos sites, do painel do utilizador e das principais funcionalidades da plataforma destinadas aos utilizadores.

Web Scraping com AWS Lambda: Guia para Python e Java 2026
Guias

Web Scraping com AWS Lambda: Guia para Python e Java 2026

TL;DR: Resumo: A extração de dados da Web com o AWS Lambda funciona melhor quando cada invocação é curta, delimitada e pode ser repetida de forma independente. Comece com HTTP direto, AWS SAM e S3 e, só depois, adicione SQS, contentores, renderização no navegador, proxies ou uma camada de recuperação gerida, apenas quando a carga de trabalho demonstrar que precisa deles.

Suciu Dan32 min read
Ler artigo
Como utilizar o GoSpider: rastrear, limpar URLs e extrair dados
Guias

Como utilizar o GoSpider: rastrear, limpar URLs e extrair dados

TL;DR: Resumo: O GoSpider é um rastreador de linha de comandos destinado a descobrir URLs, não um extrator completo de dados estruturados. Este guia sobre como utilizar o GoSpider mostra como realizar um rastreio limitado, gerir resultados de forma organizada, fazer a transferência de dados do Colly para CSV e seguir um percurso de diagnóstico para respostas 403 ou páginas que exijam renderização em JavaScript.

Suciu Dan23 min read
Ler artigo
Como fazer o Scrape Redfin: Guia Python para Dados de Propriedade
Guias

Como fazer o Scrape Redfin: Guia Python para Dados de Propriedade

TL;DR: A Redfin expõe pontos de extremidade de API ocultos que retornam JSON estruturado para listagens de propriedades, tornando possível ignorar totalmente a análise HTML frágil. Este guia orienta-o na construção de um scraper Python que extrai dados de aluguer e venda, pesquisa por localização, monitoriza novas listagens através de sitemaps XML e exporta resultados limpos para CSV ou JSON.

Suciu Dan14 min read
Ler artigo

Comece a construir

Pronto para expandir a sua recolha de dados?

Junte-se a mais de 2.000 empresas que utilizam a WebScrapingAPI para extrair dados da Web à escala empresarial, sem quaisquer custos de infraestrutura.