Saltar al contenido
Empezar gratis
Volver al blog

Cómo descargar archivos con Python: guía práctica

Gabriel CiociÚltima actualización el 17 min read
Cómo descargar archivos con Python: guía práctica
En resumen: esta guía muestra cómo descargar archivos con Python, desde una sola línea de código hasta pipelines autenticados, reanudables, paralelos y asíncronos. Aprenderás cuándo recurrir a urllib, requests, ThreadPoolExecutor o aiohttp, cómo hacer streaming de contenidos grandes, añadir una barra de progreso tqdm de verdad, reintentar con backoff y verificar la integridad con checksums y Content-Length.

Si alguna vez has automatizado una copia de seguridad, has hecho scraping de un conjunto de datos o has montado un pipeline de datos, ya sabes que descargar archivos con Python es una de esas tareas que parecen triviales hasta que llegan a producción. Una llamada a urlretrieve de dos líneas funciona bien para un CSV de 100 KB en tu portátil. Se viene abajo en cuanto necesitas bajar un archivo comprimido de 5 GB por una VPN inestable, reanudar una transferencia a medias o descargar mil imágenes de productos protegidas por un inicio de sesión.

Este artículo es la guía que me habría gustado tener cuando escribí mi primer script de descarga que debía funcionar durante una semana. Empezaremos con el fragmento más sencillo posible y, después, iremos añadiendo streaming, barras de progreso, transferencias reanudables, hilos, E/S asíncrona, autenticación, comprobaciones de integridad y reintentos. Cada sección es un ejemplo ejecutable que puedes pegar en un virtualenv con Python 3.9 o posterior.

Al terminar, deberías poder mirar una URL, prever cómo puede fallar, elegir la herramienta adecuada y copiar un fragmento que gestione esos fallos.

Por qué aprender a descargar archivos con Python (y cuándo no hacerlo)

curl y wget son excelentes para descargas puntuales. Entonces, ¿para qué aprender a descargar archivos con Python? Por tres motivos: programabilidad, portabilidad e integración. En cuanto una descarga vive dentro de un script de Python, puedes encadenarla con pandas, añadirle lógica de reintentos, analizar las cabeceras Content-Disposition, dejar el resultado en S3 y ejecutar el mismo código en macOS, Linux y Windows sin reescribir ni una línea.

Python no siempre es la respuesta correcta. Para una transferencia única dentro de un pipeline de shell, curl --fail --retry 5 requiere menos pulsaciones. Si vas a mover cientos de gigabytes entre dos servidores, aria2c o rclone saturarán tu conexión con más eficiencia. Python gana cuando el paso siguiente del pipeline también está en Python, o cuando «descargar» en realidad significa «obtener, validar, transformar y encaminar».

Para seguir la guía necesitas Python 3.9+, pip y un virtualenv. Instalaremos requests, aiohttp y tqdm sobre la marcha.

La vía más rápida: descargas en una línea con urllib.request.urlretrieve()

La forma más rápida de aprender a descargar archivos con Python es empezar por la biblioteca estándar. urllib viene incluido en todas las instalaciones de Python, así que no hay nada que instalar con pip. Su función auxiliar de más alto nivel es urlretrieve, que copia una URL directamente a una ruta local:

from urllib.request import urlretrieve

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

La función devuelve una tupla (filename, HTTPMessage). HTTPMessage es un contenedor similar a un diccionario con las cabeceras de la respuesta, muy útil cuando quieres consultar Content-Type, Content-Length o Last-Modified sin hacer una segunda petición.

Si omites el segundo argumento, Python escribe en un archivo temporal (normalmente en /tmp/ en Unix o en el directorio temporal del usuario en Windows) y te devuelve la ruta generada automáticamente. Es útil para scripts desechables y peligroso en producción, donde los archivos temporales se eliminan en momentos imprevisibles.

Las limitaciones que debes conocer:

  • Sin streaming. urlretrieve lee todo el cuerpo en memoria antes de escribir en disco. Cualquier cosa por encima de unos cientos de megabytes dolerá.
  • Modelo de errores pobre. Un 404 lanza urllib.error.HTTPError, pero los timeouts aparecen como el más genérico URLError, y no hay reintentos integrados.
  • Sin reutilización de sesión. Cada llamada abre una conexión TCP nueva.

Para descargas pequeñas y puntuales, urlretrieve basta. Para cualquier cosa más exigente, te conviene requests.

Descargar con la biblioteca requests para tener más control

requests es el cliente HTTP de facto en Python y ofrece una API mucho más rica que urllib. Instálalo una vez:

pip install requests

El patrón básico de descarga ocupa tres líneas:

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)

Aquí importan tres cosas. Primero, pasa siempre timeout. Sin él, un servidor lento puede bloquear tu worker indefinidamente. Segundo, raise_for_status() convierte cualquier respuesta 4xx o 5xx en una excepción para que no escribas en disco, sin darte cuenta, una página de error HTML. Tercero, resp.content devuelve bytes sin procesar, que es justo lo que necesitas para cualquier contenido binario. Usa resp.text solo cuando el cuerpo sea texto y quieras decodificarlo con el charset de la respuesta, y resp.json() solo cuando el servidor devuelva JSON.

Inspeccionar códigos de estado, cabeceras y Content-Type

Antes de escribir un solo byte, revisa la respuesta. Un 200 significa éxito, requests debería haber seguido automáticamente cualquier 3xx, y todo 4xx o 5xx es un bug o una caída temporal. Lee resp.headers["Content-Type"] para confirmar que recibiste el tipo MIME esperado y resp.headers.get("Content-Length") para conocer el tamaño del archivo. Si hay una cabecera Content-Disposition, analízala (requests.utils.parse_header_links o una pequeña expresión regular) para obtener el nombre de archivo que sugiere el servidor en lugar de adivinarlo a partir de la ruta de la URL.

Guardar la respuesta: archivos de texto, JSON, CSV y binarios

Ajusta el modo de escritura al contenido. Un modo incorrecto es, con diferencia, el motivo más habitual por el que un archivo descargado parece correcto en un volcado hexadecimal pero no se puede 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)

Vigila dos trampas de codificación. requests deduce la codificación de la respuesta a partir de las cabeceras, y a veces se equivoca. Si ves caracteres corruptos (mojibake), define explícitamente resp.encoding = "utf-8" antes de leer resp.text. Y en Windows, abrir un archivo de texto sin newline="" corrompe los archivos CSV, porque el módulo csv ya emite finales de línea \r\n.

Streaming de descargas grandes por bloques con requests

resp.content carga toda la respuesta en la RAM. Eso está bien para un documento JSON de 200 KB y es un desastre para un archivo de varios gigabytes. La solución es activar el streaming e iterar. Este es el patrón de referencia para descargar archivos con Python a cualquier 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

¿Qué cambia al pasar stream=True? requests envía el GET, lee solo las cabeceras de la respuesta y deja la conexión abierta. Después, iter_content va sacando bytes del socket en búferes del tamaño de chunk_size. El consumo de memoria se mantiene estable sea cual sea el tamaño del archivo, y puedes procesar los datos a medida que llegan en vez de esperar al contenido completo.

Algunas notas prácticas:

  • Elige un tamaño de bloque entre 32 KB y 1 MB. Los bloques diminutos (1 KB) consumen CPU por la sobrecarga del bucle de Python, y los bloques de varios megabytes anulan la ventaja del streaming. 64 KB es un valor por defecto seguro, y de 256 KB a 1 MB va más rápido en conexiones veloces.
  • Usa un gestor de contexto. La forma with requests.get(...) garantiza que la conexión subyacente vuelva al pool aunque tu bucle de escritura lance una excepción.
  • No mezcles iter_content y resp.content. Leer .content después del streaming carga en memoria todo lo que quede y elimina el ahorro.
  • Usa un timeout en forma de tupla. (connect, read) te permite fallar rápido ante un host caído y, a la vez, tolerar bloques lentos.

Si no necesitas procesar cada bloque, shutil.copyfileobj(resp.raw, f) es todavía más compacto, pero debes pasar stream=True y llamar antes a resp.raw.read = functools.partial(resp.raw.read, decode_content=True). De lo contrario, las respuestas codificadas con gzip se escriben en disco todavía comprimidas. Por eso la mayoría de los equipos se quedan con iter_content.

Añadir una barra de progreso con tqdm

Una descarga en streaming sin ninguna señal de avance parece rota aunque esté funcionando. tqdm lo resuelve con tres líneas más. El truco consiste en dimensionar la barra con la cabecera Content-Length del servidor y actualizarla con el tamaño de cada bloque:

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))

Hay dos detalles que suelen confundir. Primero, Content-Length no es obligatorio. Los servidores que usan chunked transfer encoding, o los proxies que vuelven a codificar el cuerpo, a menudo lo omiten. El or None de arriba indica a tqdm que muestre un indicador indeterminado en lugar de fallar o mostrar 0 %. Segundo, unit_divisor=1024 hace que la barra muestre KiB y MiB. Quítalo si prefieres unidades del SI. Comprueba los nombres exactos de los argumentos de tqdm en la documentación del proyecto antes de fijar una versión, ya que los kwargs han cambiado entre versiones.

Descargas reanudables con peticiones HTTP Range

Las descargas reanudables son la funcionalidad que, sin hacer ruido, separa los scripts de aficionado de las herramientas de producción. La especificación HTTP define un mecanismo de peticiones Range que permite a un cliente pedir los bytes a partir de N en lugar de la entidad completa. Si el servidor lo admite, responde con 206 Partial Content y el fragmento solicitado. Si no, recibes un 200 con el cuerpo completo, la señal de que debes empezar de cero.

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

Abre el archivo en modo de anexión binaria ("ab") al reanudar y comprueba que el servidor haya devuelto realmente 206, porque algunas CDN mal configuradas ignoran la cabecera Range y reinician sin avisar. La URL de reanudación debe ser idéntica byte a byte entre intentos: una query string distinta, una URL prefirmada reemitida o un destino redirigido pueden romper la idempotencia. En trabajos críticos, guarda el ETag del archivo final de la respuesta original y vuelve a validarlo al reanudar, para que un cambio en el servidor no corrompa tu archivo descargado a medias.

Descargas en paralelo con ThreadPoolExecutor y requests

Cuando tienes una lista de URL y el cuello de botella es la latencia de red y no la CPU, los hilos te dan una mejora de velocidad gratis. Descargar es una tarea limitada por E/S: los hilos pasan casi todo el tiempo bloqueados en un socket esperando bytes. Pese al global interpreter lock (GIL) de Python, ese tiempo muerto es justo cuando se ejecutan los demás hilos, así que un ThreadPoolExecutor con requests puede obtener decenas de archivos a la vez.

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}")

Ajusta max_workers según el servidor de destino, no según el número de núcleos de tu CPU. Entre 8 y 16 es un valor razonable para la mayoría de las API públicas. Por encima de eso, muchos servidores empiezan a aplicar rate limiting. Si tus descargas son diminutas (menos de ~50 KB cada una), la sobrecarga por petición domina y los hilos aportan menos de lo que esperas.

Evitar las trampas habituales del multihilo

La mayoría de los equipos cae en tres trampas. Primero, dos hilos que escriben en la misma ruta corrompen el archivo. Genera el destino a partir de un hash de la URL, no solo del nombre base. Segundo, comparte una única requests.Session entre los hilos para reutilizar conexiones TCP, pero nunca compartas un mismo descriptor de archivo abierto. Tercero, los reintentos deben ir dentro de la función del worker, no alrededor de executor.map, para que una sola URL problemática no contamine todo el lote.

Descargas asíncronas con aiohttp y asyncio

Los hilos escalan sin problema hasta unas pocas decenas de transferencias simultáneas. A partir de unas 100 conexiones activas, la memoria por hilo y el coste de los cambios de contexto empiezan a notarse, y conviene pasarse a asyncio con aiohttp. aiohttp se basa en asyncio y usa un único bucle de eventos con corrutinas cooperativas, de modo que lanzar 500 descargas simultáneas no cuesta casi 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")))

Algunas reglas prácticas. Reutiliza una única ClientSession para todo el lote. Crear una por URL provoca fugas de conexiones y hunde el rendimiento. Combina un asyncio.Semaphore con TCPConnector(limit=...) para que el límite de concurrencia razonable se aplique tanto en la capa de aplicación como en la de transporte. return_exceptions=True hace que una URL fallida vuelva como un valor en lugar de tumbar todo el gather.

¿Cuándo supera de verdad lo asíncrono a los hilos? A grandes rasgos: por debajo de 50 descargas simultáneas, los hilos son más sencillos e igual de rápidos. Entre 50 y unos cientos, ambos funcionan y lo asíncrono suele consumir menos memoria. Por encima de eso, lo asíncrono es la única opción realista. Comprueba iter_chunked y la forma del timeout en la versión de aiohttp que instales, porque ambos han cambiado entre versiones menores.

Descargar archivos protegidos por inicio de sesión, cookies o tokens

Muchas descargas reales están detrás de una autenticación. La forma correcta de descargar archivos con Python desde endpoints autenticados es pensar en tres capas: cómo se adjuntan las credenciales, cómo persiste la sesión entre peticiones y qué tipo de caducidad de token debes prever.

Los tokens Bearer son los más sencillos. La mayoría de las API modernas te dan un token y esperan que lo envíes en una cabecera 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)

La autenticación HTTP Basic cabe en una línea: requests.get(url, auth=("user", "password")). Obtén las credenciales de variables de entorno o de un gestor de secretos, nunca de una cadena literal en un código que acabe en un repositorio.

Los inicios de sesión basados en cookies necesitan una Session que recuerde las cookies que estableció la respuesta del login. Envía el formulario de inicio de sesión por POST y reutiliza la misma sesión para la 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)

Las URL prefirmadas, como las que emiten AWS S3 o Google Cloud Storage, codifican las credenciales en la query string y caducan tras un plazo fijo (a menudo de 15 minutos a 1 hora). Trátalas como efímeras: solicita una URL nueva justo antes de la descarga, no las guardes en caché y nunca las registres en logs, ya que la firma concede acceso temporal. Si además necesitas pasar por un proxy o rotar IP (algo habitual al hacer scraping con autenticación), define session.proxies y listo. Tenemos una guía más extensa sobre cómo usar un servidor proxy con el módulo requests si necesitas una introducción.

Verificar las descargas: checksums, tamaño y Content-Type

Que una descarga haya terminado no significa que el archivo se haya descargado correctamente. Tres comprobaciones baratas detectan la mayoría de los casos de corrupción.

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"

Úsalas por capas. Content-Length detecta transferencias truncadas y no cuesta nada, porque normalmente ya tienes la cabecera. La detección del tipo MIME descubre los casos en los que un servidor devolvió una página de error HTML con estado 200, algo sorprendentemente frecuente con CDN mal configuradas. SHA-256 es la única comprobación que detecta manipulaciones durante la transferencia o corrupción silenciosa del disco, y es obligatoria siempre que el editor proporcione un archivo de checksum junto con el artefacto.

Gestión robusta de errores, timeouts y reintentos automáticos

Las descargas en producción necesitan tres cosas que los fragmentos básicos no tienen: timeouts explícitos, reintentos automáticos con backoff y un modelo de excepciones coherente. requests junto con urllib3 ya te lo dan todo en cuanto los conectas bien:

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)

Contrasta los nombres de los parámetros con la documentación de urllib3.Retry y HTTPAdapter para la versión que instales: allowed_methods sustituyó al antiguo method_whitelist, y algunos valores por defecto han cambiado. El timeout en tupla (connect, read) es la línea más rentable de todo el fragmento: el timeout de conexión falla rápido con hosts caídos, y el de lectura te protege de un servidor que abre la conexión y nunca envía un byte.

Cómo descargar archivos con Python: elegir entre urllib, requests, aiohttp y wget

La respuesta honesta a «¿qué biblioteca debo usar?» es «depende de cinco cosas». Esta es la matriz de decisión que tengo en un pósit:

Escenario

Mejor herramienta

Por qué

Un archivo, script desechable, sin permiso para pip

urllib.request.urlretrieve

Biblioteca estándar, sin instalación, código trivial.

Uno o pocos archivos, con timeouts y reintentos

requests + Session + Retry

La API más limpia, ecosistema maduro.

Un solo archivo de >500 MB

requests con stream=True + tqdm + reanudación con Range

Memoria constante, transferencias recuperables.

De 10 a ~100 URL en paralelo

ThreadPoolExecutor + requests

Limitado por E/S, los hilos bastan, el código sigue siendo síncrono.

De cientos a miles de URL en paralelo

aiohttp + asyncio

Menos memoria por conexión, mejor latencia de cola.

Autenticado, basado en cookies, en varios pasos

requests.Session (o aiohttp.ClientSession)

Soporte nativo de sesiones y cookie jar.

Llamada desde un pipeline de shell

wget o curl, no Python

Si Python no aporta valor, no lo uses.

Wrapper de Python para wget

python-wget

Sirve para un uso reanudable al estilo CLI, con menos funciones que requests.

Algunas reglas generales. Fija un tamaño de bloque entre 32 KB y 1 MB y rara vez tendrás que revisarlo. Define siempre timeout. Compara siempre Content-Length con los bytes escritos. Reutiliza las sesiones en las peticiones al mismo host. Y resiste la tentación de recurrir a lo asíncrono salvo que tengas de verdad cientos de transferencias simultáneas. Los hilos son más sencillos, se depuran mejor y casi siempre son lo bastante rápidos.

Si tu cuello de botella no es la biblioteca, sino el sitio de destino, que se defiende con CAPTCHA, bloqueos de IP o fingerprinting del navegador, la cuestión ya no es cómo descargar archivos con Python. Se trata de enrutar tus peticiones a través de IP residenciales, rotar los user agents y desbloquear la página antes siquiera de llamar a iter_content. Es otro problema, que tratamos en nuestras guías centradas en scraping.

Puntos clave

  • Para archivos pequeños y puntuales, urllib.request.urlretrieve cabe en una línea y no tiene dependencias. Para todo lo demás, usa requests.
  • Haz siempre streaming de los archivos grandes con stream=True más iter_content, elige un tamaño de bloque entre 32 KB y 1 MB y compara los bytes escritos con Content-Length.
  • Las descargas reanudables necesitan una cabecera HTTP Range, el modo de anexión binaria y una comprobación de que el servidor respondió realmente 206 Partial Content.
  • Los hilos cubren el paralelismo limitado por E/S hasta ~100 URL. Pasa a aiohttp y asyncio cuando superes ese umbral.
  • Las descargas en producción deben incluir un timeout en tupla, un Retry de urllib3 con backoff y una comprobación de integridad (SHA-256, tamaño o MIME).

FAQ

¿Cómo descargo un archivo con Python sin instalar bibliotecas de terceros?

Usa urllib.request de la biblioteca estándar. urlretrieve(url, path) es la forma más corta, y urlopen(url) con un bucle de escritura shutil.copyfileobj es el equivalente compatible con streaming. Esto importa en entornos restringidos, capas de AWS Lambda o contenedores de vida corta, donde añadir requests sería excesivo o directamente imposible.

¿Cómo reanudo en Python un archivo descargado parcialmente?

Si el servidor no admite peticiones Range, no puedes reanudar en sentido estricto. La alternativa es la descarga segmentada: divide el archivo de antemano en N rangos de bytes, descarga cada uno en un archivo .partN y concaténalos cuando hayan terminado todas las partes. Si eso también falla, guarda el ETag original y vuelve a descargar solo cuando cambie; de lo contrario, quédate con lo que tienes.

¿Cómo descargo un archivo que requiere inicio de sesión o un token de API?

Además de adjuntar las credenciales, planifica la rotación de tokens. Envuelve la cabecera de autenticación en un callable que obtenga un token nuevo al recibir 401 Unauthorized, guarda los refresh tokens en el llavero del sistema operativo en lugar de en un archivo plano y, si usas OAuth, limita los scopes del token al mínimo necesario para las descargas. En lotes largos, renueva el token de forma proactiva antes de que caduque en lugar de reaccionar después.

¿Cómo puedo verificar que un archivo descargado no está corrupto?

Además de los checksums, haz una comprobación específica del formato. Abre los ZIP con zipfile.ZipFile.testzip(), valida el JSON con json.loads y usa pdfminer o pypdf para confirmar que un PDF tiene un trailer legible. Así detectas los casos en los que los bytes coinciden con un checksum de referencia que ya estaba mal, o en los que el editor volvió a subir sin avisar un artefacto roto.

¿Debo usar requests, aiohttp o wget para descargas grandes?

«Grande» depende de la cantidad, no solo del tamaño. Para un único archivo grande, gana requests con streaming y reanudación con Range, porque es más fácil de depurar. Para muchos archivos grandes en paralelo, aiohttp mantiene estable el consumo de memoria. Solo merece la pena invocar wget desde Python cuando necesitas específicamente su modo espejo o la descarga recursiva; si no, llama a wget desde un script de shell y ahórrate la sobrecarga del subproceso.

Conclusión y próximos pasos

Descargar bien archivos con Python consiste sobre todo en ajustar la biblioteca a la carga de trabajo y no saltarse las partes aburridas: timeouts, reintentos, comprobaciones de integridad y transferencias reanudables. Empieza con urlretrieve para los prototipos, pasa a requests en cuanto necesites control, haz streaming de todo lo que supere unos cientos de megabytes y recurre a aiohttp solo cuando tengas un problema real de concurrencia.

Un buen proyecto para seguir: crea una pequeña CLI que reciba una lista de URL, las reparta mediante un ThreadPoolExecutor, escriba un manifiesto SHA-256 sobre la marcha y se reanude a partir de él al reiniciar. Ese único script pone en práctica casi todo lo que cubre esta guía y se convertirá en la columna vertebral de todos los pipelines de descarga que escribas después.

Cuando un trabajo requiera HTTP/2, transferencias paralelas o descargas reanudables, nuestra comparativa de alternativas a wget compara curl, aria2, HTTPie y herramientas similares.

Si lo que bloquea tus descargas son los CAPTCHA, un rate limiting agresivo o las restricciones geográficas, y no tu propio código, ese es el momento en que una capa de desbloqueo gestionada merece la pena. La Scraper API de WebScrapingAPI se encarga de la rotación de proxies, los desafíos antibot y los reintentos detrás de un único endpoint, para que puedas mantener los patrones de descarga en Python de este artículo y cambiar solo la capa de obtención cuando lo necesites. Elige la herramienta más ligera que realmente funcione y añade robustez a medida que tu tráfico y tus datos lo exijan.

Acerca del autor

Gabriel Cioci, Desarrollador full-stack @ WebScrapingAPI

Gabriel Cioci

Desarrollador full-stack

Gabriel Cioci es desarrollador full stack en WebScrapingAPI, donde se encarga de crear y mantener los sitios web, el panel de usuario y los componentes principales de la plataforma destinados a los usuarios.

Extracción de datos web con AWS Lambda: guía para Python y Java 2026
Guías

Extracción de datos web con AWS Lambda: guía para Python y Java 2026

TL;DR: En resumen: el web scraping con AWS Lambda funciona mejor cuando cada invocación es breve, está delimitada y se puede reintentar de forma independiente. Empieza con HTTP directo, AWS SAM y S3, y añade SQS, contenedores, renderización en navegador, proxies o una capa de recuperación gestionada solo cuando la carga de trabajo demuestre que los necesita.

Suciu Dan33 min read
Leer artículo
Cómo utilizar GoSpider: rastrear, depurar URL y extraer datos
Guías

Cómo utilizar GoSpider: rastrear, depurar URL y extraer datos

TL;DR: En resumen: GoSpider es un rastreador de línea de comandos diseñado para descubrir URL, no un extractor completo de datos estructurados. Esta guía sobre cómo utilizar GoSpider muestra cómo realizar un rastreo limitado, gestionar correctamente los resultados, pasar los datos de Colly a CSV y seguir una ruta de diagnóstico para respuestas 403 o páginas que requieren renderización con JavaScript.

Suciu Dan24 min read
Leer artículo
Cómo raspar Redfin: Guía Python de Datos Inmobiliarios
Guías

Cómo raspar Redfin: Guía Python de Datos Inmobiliarios

TL;DR: Redfin expone puntos finales de API ocultos que devuelven JSON estructurado para los listados de propiedades, lo que permite omitir por completo el frágil análisis HTML. Esta guía te guía a través de la construcción de un raspador de Python que extrae datos de alquiler y venta, busca por ubicación, supervisa los nuevos listados a través de mapas de sitio XML y exporta resultados limpios a CSV o JSON.

Suciu Dan14 min read
Leer artículo

Empieza a crear

¿Estás listo para ampliar tu recopilación de datos?

Únete a más de 2000 empresas que utilizan WebScrapingAPI para extraer datos de la web a escala empresarial sin ningún gasto de infraestructura.