Zum Inhalt springen
Zurück zum Blog

Dateien mit Python herunterladen: Das Praxis-Playbook

Gabriel CiociZuletzt aktualisiert am 15 min read
Dateien mit Python herunterladen: Das Praxis-Playbook
Kurz gesagt: Dieser Leitfaden zeigt, wie Sie Dateien mit Python herunterladen – vom einfachen Einzeiler bis zu authentifizierten, fortsetzbaren, parallelen und asynchronen Pipelines. Sie erfahren, wann Sie zu urllib, requests, ThreadPoolExecutor oder aiohttp greifen, wie Sie große Datenmengen streamen, einen echten tqdm-Fortschrittsbalken einbauen, mit Backoff wiederholen und die Integrität per Prüfsumme und Content-Length verifizieren.

Wer schon einmal einen Backup-Job geskriptet, einen Datensatz gescrapt oder eine Datenpipeline zusammengebaut hat, weiß: Dateien mit Python herunterzuladen gehört zu den Aufgaben, die trivial wirken, bis die Produktion zuschlägt. Ein zweizeiliger urlretrieve-Aufruf funktioniert für eine 100-KB-CSV auf dem Laptop tadellos. Er bricht zusammen, sobald Sie ein 5-GB-Archiv über ein wackeliges VPN holen, eine halb fertige Übertragung fortsetzen oder tausend Produktbilder hinter einem Login abrufen müssen.

Dieser Artikel ist das Playbook, das ich mir gewünscht hätte, als ich mein erstes Download-Skript schrieb, das eine Woche lang durchlaufen sollte. Wir beginnen mit dem einfachsten möglichen Snippet und ergänzen dann Schritt für Schritt Streaming, Fortschrittsbalken, fortsetzbare Übertragungen, Threading, asynchrone I/O, Authentifizierung, Integritätsprüfungen und Retries. Jeder Abschnitt ist ein lauffähiges Beispiel, das Sie in ein virtualenv mit Python 3.9 oder neuer einfügen können.

Am Ende sollten Sie eine URL ansehen, ihre Fehlerquellen vorhersagen, das richtige Werkzeug wählen und ein Snippet kopieren können, das damit umgeht.

Warum Sie lernen sollten, Dateien mit Python herunterzuladen (und wann nicht)

curl und wget eignen sich hervorragend für spontane Downloads. Warum also überhaupt lernen, Dateien mit Python herunterzuladen? Drei Gründe: Programmierbarkeit, Portabilität und Integration. Sobald ein Download in einem Python-Skript steckt, können Sie ihn mit pandas verketten, Retry-Logik ergänzen, Content-Disposition-Header parsen, das Ergebnis in S3 ablegen und denselben Code unter macOS, Linux und Windows ausführen, ohne eine einzige Zeile umzuschreiben.

Python ist nicht immer die richtige Antwort. Für eine einmalige Übertragung in einer Shell-Pipeline braucht curl --fail --retry 5 weniger Tastenanschläge. Wenn Sie Hunderte Gigabyte zwischen zwei Servern verschieben, lasten aria2c oder rclone Ihre Leitung effizienter aus. Python gewinnt, wenn auch der nächste Schritt der Pipeline in Python lebt oder wenn „Download“ eigentlich „abrufen, validieren, transformieren und weiterleiten“ bedeutet.

Zum Mitmachen brauchen Sie Python 3.9+, pip und ein virtualenv. requests, aiohttp und tqdm installieren wir unterwegs.

Der schnellste Weg: Downloads in einer Zeile mit urllib.request.urlretrieve()

Am schnellsten lernen Sie, Dateien mit Python herunterzuladen, wenn Sie mit der Standardbibliothek beginnen. urllib ist in jeder Python-Installation enthalten, Sie müssen also nichts per pip install nachinstallieren. Die komfortabelste Hilfsfunktion ist urlretrieve, die eine URL direkt in einen lokalen Pfad kopiert:

from urllib.request import urlretrieve

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

Die Funktion gibt ein Tupel (filename, HTTPMessage) zurück. HTTPMessage ist ein dict-ähnlicher Container mit den Response-Headern. Das ist praktisch, wenn Sie Content-Type, Content-Length oder Last-Modified prüfen wollen, ohne eine zweite Anfrage zu senden.

Lassen Sie das zweite Argument weg, schreibt Python in eine temporäre Datei (unter Unix meist in /tmp/, unter Windows in Ihr Benutzer-Temp-Verzeichnis) und gibt Ihnen den automatisch erzeugten Pfad zurück. Nützlich für Wegwerf-Skripte, gefährlich in der Produktion, wo temporäre Dateien zu unvorhersehbaren Zeitpunkten aufgeräumt werden.

Die Kompromisse, die Sie kennen sollten:

  • Kein Streaming. urlretrieve liest den gesamten Body in den Speicher, bevor es auf die Festplatte schreibt. Ab einigen Hundert Megabyte tut das weh.
  • Schwaches Fehlermodell. Ein 404 löst urllib.error.HTTPError aus, Timeouts erscheinen aber als allgemeinerer URLError, und es gibt keine eingebauten Retries.
  • Keine Session-Wiederverwendung. Jeder Aufruf öffnet eine neue TCP-Verbindung.

Für kleine einmalige Downloads reicht urlretrieve. Für alles Anspruchsvollere sollten Sie zu requests greifen.

Downloads mit der requests-Bibliothek für mehr Kontrolle

requests ist der De-facto-Standard unter den HTTP-Clients für Python und bietet eine deutlich reichhaltigere API als urllib. Einmal installieren:

pip install requests

Das grundlegende Download-Muster besteht aus drei Zeilen:

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)

Drei Dinge sind hier wichtig. Erstens: Übergeben Sie immer timeout. Ohne diesen Parameter kann ein langsamer Server Ihren Worker unbegrenzt blockieren. Zweitens: raise_for_status() verwandelt jede 4xx- oder 5xx-Antwort in eine Exception, damit Sie nicht stillschweigend eine HTML-Fehlerseite auf die Festplatte schreiben. Drittens: resp.content liefert rohe Bytes, also genau das, was Sie für binäre Inhalte brauchen. Verwenden Sie resp.text nur, wenn der Body Text ist und Sie ihn mit dem Zeichensatz der Antwort dekodieren wollen, und resp.json() nur, wenn der Server JSON zurückgibt.

Statuscodes, Header und Content-Type prüfen

Bevor Sie auch nur ein Byte schreiben, prüfen Sie die Antwort. 200 bedeutet Erfolg, einem 3xx hätte requests automatisch folgen sollen, und jedes 4xx oder 5xx ist ein Bug oder ein vorübergehender Ausfall. Lesen Sie resp.headers["Content-Type"], um den erwarteten MIME-Typ zu bestätigen, und resp.headers.get("Content-Length"), um die Dateigröße zu ermitteln. Ist ein Content-Disposition-Header vorhanden, parsen Sie ihn (requests.utils.parse_header_links oder ein kleiner regulärer Ausdruck), um den vom Server vorgeschlagenen Dateinamen zu übernehmen, statt ihn aus dem URL-Pfad zu erraten.

Die Antwort speichern: Text-, JSON-, CSV- und Binärdateien

Passen Sie den Schreibmodus an den Inhalt an. Ein falscher Modus ist mit Abstand der häufigste Grund, warum eine heruntergeladene Datei im Hex-Dump korrekt aussieht, sich aber nicht öffnen lässt.

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

Zwei Encoding-Fallen sollten Sie im Blick behalten. requests errät das Encoding der Antwort anhand der Header, und diese Vermutung liegt manchmal daneben. Sehen Sie Zeichensalat (Mojibake), setzen Sie vor dem Lesen von resp.text explizit resp.encoding = "utf-8". Und unter Windows beschädigt das Öffnen einer Textdatei ohne newline="" CSV-Dateien, weil das csv-Modul bereits \r\n-Zeilenenden ausgibt.

Große Downloads mit requests in Chunks streamen

resp.content lädt die gesamte Antwort in den RAM. Für ein 200-KB-JSON-Dokument ist das in Ordnung, für ein Archiv mit mehreren Gigabyte eine Katastrophe. Die Lösung: Streaming aktivieren und iterieren. Das ist das Standardmuster, wenn Sie Dateien mit Python in realem Maßstab herunterladen:

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

Was ändert sich mit stream=True? requests sendet den GET, liest nur die Response-Header und lässt die Verbindung offen. iter_content holt die Bytes dann in Puffern der Größe chunk_size vom Socket. Der Speicherverbrauch bleibt unabhängig von der Dateigröße konstant, und Sie können Daten verarbeiten, sobald sie eintreffen, statt auf den vollständigen Inhalt zu warten.

Einige praktische Hinweise:

  • Wählen Sie eine Chunk-Größe zwischen 32 KB und 1 MB. Winzige Chunks (1 KB) verbrennen CPU durch den Overhead der Python-Schleife, und Chunks mit mehreren Megabyte machen den Sinn des Streamings zunichte. 64 KB ist ein sicherer Standardwert, 256 KB bis 1 MB sind auf schnellen Leitungen flotter.
  • Verwenden Sie einen Context Manager. Die Form with requests.get(...) garantiert, dass die zugrunde liegende Verbindung an den Pool zurückgegeben wird, selbst wenn Ihre Schreibschleife eine Exception auslöst.
  • Mischen Sie iter_content und resp.content nicht. Wer nach dem Streaming .content liest, puffert den Rest in den Speicher und verspielt die Ersparnis.
  • Verwenden Sie einen Tupel-Timeout. (connect, read) lässt Sie bei einem toten Host schnell scheitern und toleriert trotzdem langsame Chunks.

Brauchen Sie keine Verarbeitung pro Chunk, ist shutil.copyfileobj(resp.raw, f) noch kompakter. Dann müssen Sie aber stream=True übergeben und vorher resp.raw.read = functools.partial(resp.raw.read, decode_content=True) aufrufen, sonst landen gzip-kodierte Antworten weiterhin komprimiert auf der Festplatte. Aus diesem Grund bleiben die meisten Teams bei iter_content.

Einen Fortschrittsbalken mit tqdm hinzufügen

Ein Streaming-Download ohne jedes Feedback wirkt kaputt, selbst wenn er funktioniert. tqdm behebt das mit drei zusätzlichen Zeilen. Der Trick: Sie dimensionieren den Balken mit dem Content-Length-Header des Servers und erhöhen ihn um die Größe jedes Chunks:

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

Zwei Details bringen viele ins Stolpern. Erstens ist Content-Length nicht verpflichtend. Server mit Chunked Transfer Encoding oder Proxys, die den Body neu kodieren, lassen den Header oft weg. Das or None oben sorgt dafür, dass tqdm eine unbestimmte Anzeige rendert, statt abzustürzen oder 0 % anzuzeigen. Zweitens lässt unit_divisor=1024 den Balken in KiB und MiB anzeigen. Entfernen Sie den Parameter, wenn Sie SI-Einheiten bevorzugen. Prüfen Sie die genauen tqdm-Schlüsselwortnamen in der Projektdokumentation, bevor Sie eine Version festschreiben, denn die kwargs haben sich zwischen Releases verändert.

Fortsetzbare Downloads mit HTTP-Range-Requests

Fortsetzbare Downloads sind die Funktion, die Hobby-Skripte unauffällig von Produktionswerkzeugen trennt. Die HTTP-Spezifikation definiert einen Range-Request-Mechanismus, mit dem ein Client ab Byte N statt der gesamten Ressource anfragen kann. Unterstützt der Server das, antwortet er mit 206 Partial Content und dem angeforderten Ausschnitt. Andernfalls erhalten Sie 200 und den vollständigen Body. Das ist Ihr Signal, von vorn zu beginnen.

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

Öffnen Sie die Datei beim Fortsetzen im Binär-Anhängemodus ("ab") und prüfen Sie, dass der Server tatsächlich 206 zurückgegeben hat, denn manche falsch konfigurierten CDNs ignorieren den Range-Header und beginnen stillschweigend neu. Die URL für die Fortsetzung muss zwischen den Versuchen Byte für Byte identisch sein: Ein anderer Query-String, eine neu ausgestellte Pre-Signed URL oder ein umgeleitetes Ziel können die Idempotenz zerstören. Speichern Sie bei geschäftskritischen Jobs das ETag der finalen Datei aus der ursprünglichen Antwort und validieren Sie es beim Fortsetzen erneut, damit eine serverseitige Änderung Ihre halb heruntergeladene Datei nicht beschädigt.

Parallele Downloads mit ThreadPoolExecutor und requests

Haben Sie eine Liste von URLs und ist der Engpass die Netzwerklatenz statt der CPU, verschafft Ihnen Threading einen kostenlosen Geschwindigkeitsschub. Herunterladen ist eine I/O-gebundene Arbeit: Threads verbringen fast ihre gesamte Zeit blockiert an einem Socket und warten auf Bytes. Trotz des Global Interpreter Lock (GIL) von Python laufen genau in dieser Leerlaufzeit andere Threads, sodass ein ThreadPoolExecutor mit requests Dutzende Dateien gleichzeitig abrufen kann.

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

Richten Sie max_workers nach dem Zielserver aus, nicht nach der Anzahl Ihrer CPU-Kerne. 8 bis 16 ist für die meisten öffentlichen APIs ein vernünftiger Standardwert. Darüber beginnen viele Server mit Rate Limiting. Sind Ihre Downloads winzig (unter ~50 KB pro Datei), dominiert der Overhead pro Anfrage, und Threading bringt weniger als erwartet.

Typische Multithreading-Fallen vermeiden

Drei Fallen erwischen die meisten Teams. Erstens beschädigen zwei Threads, die in denselben Pfad schreiben, die Datei. Leiten Sie das Ziel deshalb aus einem Hash der URL ab, nicht nur aus dem Dateinamen. Zweitens: Teilen Sie eine einzige requests.Session über alle Threads, um TCP-Verbindungen wiederzuverwenden, aber teilen Sie niemals ein einzelnes geöffnetes Datei-Handle. Drittens gehören Retries in die Worker-Funktion, nicht um executor.map herum, damit eine einzelne unzuverlässige URL nicht den ganzen Batch vergiftet.

Asynchrone Downloads mit aiohttp und asyncio

Threads skalieren problemlos auf einige Dutzend gleichzeitige Übertragungen. Ab etwa 100 offenen Verbindungen machen sich Speicher pro Thread und Kontextwechsel bemerkbar, und Sie sollten auf asyncio plus aiohttp umsteigen. aiohttp baut auf asyncio auf und nutzt eine einzige Event-Loop mit kooperativen Coroutinen, sodass 500 gleichzeitige Downloads fast nichts kosten.

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

Ein paar Faustregeln. Verwenden Sie eine einzige ClientSession für den gesamten Batch. Wer pro URL eine neue erzeugt, verursacht Verbindungslecks und ruiniert die Performance. Kombinieren Sie ein asyncio.Semaphore mit TCPConnector(limit=...), damit die höfliche Obergrenze für Parallelität sowohl auf Anwendungs- als auch auf Transportebene greift. return_exceptions=True lässt eine einzelne fehlgeschlagene URL als Wert zurückkommen, statt das gesamte gather abstürzen zu lassen.

Wann schlägt Async Threads wirklich? Grob gesagt: Unter 50 gleichzeitigen Downloads sind Threads einfacher und genauso schnell. Zwischen 50 und einigen Hundert funktionieren beide, und Async braucht meist weniger Speicher. Darüber ist Async die einzige realistische Option. Prüfen Sie iter_chunked und die Form des Timeouts für die aiohttp-Version, die Sie installieren, denn beides hat sich über Minor-Releases hinweg verändert.

Dateien hinter Login, Cookies oder Tokens herunterladen

Viele reale Downloads liegen hinter einer Authentifizierung. Um Dateien mit Python von authentifizierten Endpunkten richtig herunterzuladen, denken Sie in drei Ebenen: wie die Zugangsdaten angehängt werden, wie die Session zwischen Anfragen bestehen bleibt und mit welcher Art von Token-Ablauf Sie planen müssen.

Bearer-Tokens sind am einfachsten. Die meisten modernen APIs geben Ihnen ein Token und erwarten, dass Sie es in einem Authorization-Header mitsenden:

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)

HTTP-Basic-Auth ist ein Einzeiler: requests.get(url, auth=("user", "password")). Beziehen Sie die Zugangsdaten aus Umgebungsvariablen oder einem Secrets Manager, niemals aus einem String-Literal in Code, der in ein Repository wandert.

Cookie-basierte Logins brauchen eine Session, die sich die Cookies merkt, die eine Login-Antwort gesetzt hat. Senden Sie das Login-Formular per POST und verwenden Sie dieselbe Session anschließend für die geschützte URL:

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

Pre-Signed URLs, wie sie AWS S3 oder Google Cloud Storage ausstellen, kodieren die Zugangsdaten im Query-String und laufen nach einem festen Zeitfenster ab (oft 15 Minuten bis 1 Stunde). Behandeln Sie sie als flüchtig: Fordern Sie direkt vor dem Download eine frische URL an, cachen Sie sie nicht und loggen Sie sie niemals, da die Signatur vorübergehenden Zugriff gewährt. Müssen Sie zusätzlich über einen Proxy gehen oder IPs rotieren (beim Scraping mit Authentifizierung üblich), setzen Sie einfach session.proxies. Wenn Sie eine Einführung brauchen: Wir haben einen ausführlicheren Leitfaden zur Nutzung eines Proxyservers mit dem requests-Modul.

Downloads verifizieren: Prüfsummen, Größe und Content-Type

Eine Datei, deren Download abgeschlossen ist, ist nicht dasselbe wie eine Datei, die korrekt heruntergeladen wurde. Drei günstige Prüfungen fangen die meisten Beschädigungen ab.

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"

Setzen Sie sie in Schichten ein. Content-Length erkennt abgeschnittene Übertragungen und kostet nichts, da Sie den Header ohnehin meist haben. Die MIME-Prüfung erkennt den Fall, dass ein Server eine HTML-Fehlerseite mit Status 200 zurückgegeben hat. Das passiert bei schlecht konfigurierten CDNs erstaunlich häufig. SHA-256 ist die einzige Prüfung, die Manipulationen während der Übertragung oder stille Festplattenfehler erkennt, und sie ist Pflicht, sobald der Herausgeber eine Prüfsummendatei zusammen mit dem Artefakt bereitstellt.

Robuste Fehlerbehandlung, Timeouts und automatische Retries

Downloads in der Produktion brauchen drei Dinge, die den einfachen Snippets fehlen: explizite Timeouts, automatische Retries mit Backoff und ein sinnvolles Exception-Modell. requests und urllib3 liefern das alles bereits, sobald Sie sie richtig verdrahten:

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)

Gleichen Sie die Parameternamen mit der Dokumentation von urllib3.Retry und HTTPAdapter für Ihre installierte Version ab: allowed_methods hat das ältere method_whitelist ersetzt, und einige Standardwerte haben sich verschoben. Der Tupel-Timeout (connect, read) ist die wirkungsvollste Zeile im gesamten Snippet: Der Connect-Timeout scheitert schnell an toten Hosts, und der Read-Timeout schützt vor einem Server, der die Verbindung öffnet und dann nie ein Byte sendet.

Dateien mit Python herunterladen: urllib, requests, aiohttp oder wget?

Die ehrliche Antwort auf „Welche Bibliothek soll ich nehmen?“ lautet: „Das hängt von fünf Dingen ab.“ Hier ist die Entscheidungsmatrix, die ich auf einem Notizzettel neben dem Bildschirm habe:

Szenario

Bestes Werkzeug

Warum

Eine Datei, Wegwerf-Skript, kein pip erlaubt

urllib.request.urlretrieve

Standardbibliothek, keine Installation, trivialer Code.

Eine bis wenige Dateien, mit Timeouts und Retries

requests + Session + Retry

Sauberste API, ausgereiftes Ökosystem.

Einzelne Datei >500 MB

requests mit stream=True + tqdm + Range-Fortsetzung

Konstanter Speicher, wiederaufnehmbare Übertragungen.

10 bis ~100 URLs parallel

ThreadPoolExecutor + requests

I/O-gebunden, Threads reichen, der Code bleibt synchron.

Hunderte bis Tausende URLs parallel

aiohttp + asyncio

Weniger Speicher pro Verbindung, bessere Tail-Latenz.

Authentifiziert, cookie-basiert, mehrstufig

requests.Session (oder aiohttp.ClientSession)

Erstklassige Unterstützung für Sessions und Cookie-Jar.

Aufruf aus einer Shell-Pipeline

wget oder curl, nicht Python

Wenn Python keinen Mehrwert bringt, verwenden Sie es nicht.

Python-Wrapper um wget

python-wget

Gut für fortsetzbare Nutzung im CLI-Stil, weniger Funktionen als requests.

Ein paar übergreifende Regeln. Legen Sie eine Chunk-Größe zwischen 32 KB und 1 MB fest, dann müssen Sie selten wieder daran drehen. Setzen Sie immer timeout. Vergleichen Sie immer Content-Length mit den geschriebenen Bytes. Verwenden Sie Sessions für Anfragen an denselben Host wieder. Und widerstehen Sie der Versuchung, zu Async zu greifen, solange Sie nicht wirklich Hunderte gleichzeitige Übertragungen haben. Threads sind einfacher, leichter zu debuggen und fast immer schnell genug.

Liegt der Engpass nicht an der Bibliothek, sondern daran, dass sich die Zielseite mit CAPTCHAs, IP-Sperren oder Browser-Fingerprinting wehrt, geht es nicht mehr darum, wie Sie Dateien mit Python herunterladen. Dann müssen Sie Ihre Anfragen über Residential-IPs leiten, User-Agents rotieren und die Seite entsperren, bevor Sie überhaupt iter_content aufrufen. Das ist ein anderes Problem, das unsere Scraping-Leitfäden behandeln.

Das Wichtigste in Kürze

  • Für kleine einmalige Dateien ist urllib.request.urlretrieve ein Einzeiler ohne Abhängigkeiten. Für alles andere greifen Sie zu requests.
  • Streamen Sie große Dateien immer mit stream=True plus iter_content, wählen Sie eine Chunk-Größe zwischen 32 KB und 1 MB und vergleichen Sie die geschriebenen Bytes mit Content-Length.
  • Fortsetzbare Downloads brauchen einen HTTP-Range-Header, den Binär-Anhängemodus und eine Prüfung, ob der Server tatsächlich mit 206 Partial Content geantwortet hat.
  • Threads decken I/O-gebundene Parallelität bis etwa 100 URLs ab. Oberhalb dieser Schwelle wechseln Sie zu aiohttp und asyncio.
  • Downloads in der Produktion müssen einen Tupel-timeout, ein urllib3-Retry mit Backoff und eine Integritätsprüfung (SHA-256, Größe oder MIME) enthalten.

FAQ

Wie lade ich mit Python eine Datei herunter, ohne Bibliotheken von Drittanbietern zu installieren?

Verwenden Sie urllib.request aus der Standardbibliothek. urlretrieve(url, path) ist die kürzeste Form, und urlopen(url) mit einer shutil.copyfileobj-Schreibschleife ist das streamingfreundliche Gegenstück. Das ist wichtig in abgeschotteten Umgebungen, AWS Lambda-Layern oder kurzlebigen Containern, in denen requests überdimensioniert oder gar nicht installierbar wäre.

Wie setze ich eine teilweise heruntergeladene Datei in Python fort?

Unterstützt der Server keine Range-Requests, können Sie im strengen Sinne nicht fortsetzen. Die Ausweichlösung ist der segmentierte Download: Teilen Sie die Datei vorab in N Byte-Bereiche auf, laden Sie jeden in eine .partN-Datei und fügen Sie sie zusammen, wenn alle Teile fertig sind. Schlägt auch das fehl, speichern Sie das ursprüngliche ETag und laden nur dann neu herunter, wenn es sich ändert; andernfalls behalten Sie, was Sie haben.

Wie lade ich eine Datei herunter, die einen Login oder ein API-Token erfordert?

Neben dem Anhängen der Zugangsdaten sollten Sie die Token-Rotation einplanen. Kapseln Sie den Auth-Header in ein Callable, das bei 401 Unauthorized ein frisches Token holt, speichern Sie Refresh-Tokens im Schlüsselbund des Betriebssystems statt in einer einfachen Datei, und beschränken Sie bei OAuth die Scopes des Tokens auf das für Downloads nötige Minimum. Erneuern Sie das Token bei langen Batches proaktiv vor dem Ablauf, statt erst zu reagieren.

Wie prüfe ich, ob eine heruntergeladene Datei nicht beschädigt ist?

Führen Sie zusätzlich zu Prüfsummen eine formatspezifische Plausibilitätsprüfung durch. Öffnen Sie ZIPs mit zipfile.ZipFile.testzip(), validieren Sie JSON mit json.loads und nutzen Sie pdfminer oder pypdf, um zu bestätigen, dass ein PDF einen parsebaren Trailer hat. So erkennen Sie Fälle, in denen die Bytes zwar zu einer Referenzprüfsumme passen, diese aber selbst falsch war, oder in denen der Herausgeber stillschweigend ein defektes Artefakt neu hochgeladen hat.

Sollte ich für große Downloads requests, aiohttp oder wget verwenden?

„Groß“ hängt von der Anzahl ab, nicht nur von der Größe. Für eine große Datei gewinnt requests mit Streaming und Range-Fortsetzung, weil es leichter zu debuggen ist. Für viele große Dateien parallel hält aiohttp den Speicherverbrauch konstant. wget aus Python aufzurufen lohnt sich nur, wenn Sie gezielt seinen Mirror-Modus oder den rekursiven Abruf brauchen; ansonsten rufen Sie wget aus einem Shell-Skript auf und sparen sich den Overhead des Subprozesses.

Fazit und nächste Schritte

Dateien mit Python gut herunterzuladen bedeutet vor allem, die Bibliothek zur Arbeitslast passend zu wählen und die langweiligen Teile nicht zu überspringen: Timeouts, Retries, Integritätsprüfungen und fortsetzbare Übertragungen. Beginnen Sie bei Prototypen mit urlretrieve, steigen Sie auf requests um, sobald Sie Kontrolle brauchen, streamen Sie alles über einige Hundert Megabyte und greifen Sie erst zu aiohttp, wenn Sie ein echtes Parallelitätsproblem haben.

Ein gutes Folgeprojekt: Bauen Sie ein kleines CLI, das eine Liste von URLs entgegennimmt, sie über einen ThreadPoolExecutor verteilt, laufend ein SHA-256-Manifest schreibt und beim Neustart anhand des Manifests fortsetzt. Dieses eine Skript deckt fast alles aus diesem Leitfaden ab und wird zum Rückgrat jeder Download-Pipeline, die Sie danach schreiben.

Wenn ein Job HTTP/2, parallele Übertragungen oder fortsetzbare Downloads erfordert, vergleicht unsere Übersicht über wget-Alternativen curl, aria2, HTTPie und ähnliche Werkzeuge.

Werden Ihre Downloads nicht durch Ihren eigenen Code, sondern durch CAPTCHAs, aggressives Rate Limiting oder Geo-Sperren blockiert, ist der Punkt erreicht, an dem sich eine verwaltete Unblocking-Schicht bezahlt macht. Die Scraper API von WebScrapingAPI übernimmt Proxy-Rotation, Anti-Bot-Challenges und Retries hinter einem einzigen Endpunkt. So behalten Sie die Python-Download-Muster aus diesem Artikel und tauschen bei Bedarf nur die Abrufschicht aus. Wählen Sie das leichteste Werkzeug, das tatsächlich funktioniert, und ergänzen Sie Robustheit, wenn Ihr Traffic und Ihre Daten es verlangen.

Über den Autor

Gabriel Cioci, Full-Stack-Entwickler @ WebScrapingAPI

Gabriel Cioci

Full-Stack-Entwickler

Gabriel Cioci ist Full-Stack-Entwickler bei WebScrapingAPI und verantwortlich für die Entwicklung und Wartung der Websites, des Benutzerportals sowie der wichtigsten benutzerseitigen Komponenten der Plattform.

Web-Scraping mit AWS Lambda: Leitfaden für Python und Java 2026
Anleitungen

Web-Scraping mit AWS Lambda: Leitfaden für Python und Java 2026

TL;DR: Kurz gesagt: Web-Scraping mit AWS Lambda funktioniert am besten, wenn jeder Aufruf kurz, begrenzt und unabhängig wiederholbar ist. Beginnen Sie mit direktem HTTP, AWS SAM und S3 und fügen Sie erst dann SQS, Container, Browser-Rendering, Proxys oder eine verwaltete Abrufebene hinzu, wenn sich im Rahmen der Arbeitslast herausstellt, dass diese erforderlich sind.

Suciu Dan26 min read
Artikel lesen
So verwenden Sie GoSpider: Crawlen, URLs bereinigen und Daten extrahieren
Anleitungen

So verwenden Sie GoSpider: Crawlen, URLs bereinigen und Daten extrahieren

TL;DR: GoSpider ist ein Befehlszeilen-Crawler zum Auffinden von URLs, kein vollständiger Scraper für strukturierte Daten. Diese Anleitung zur Verwendung von GoSpider zeigt einen begrenzten Crawl, die saubere Verarbeitung der Ausgabe, die Übergabe von Colly an CSV sowie einen Diagnosepfad für 403-Antworten oder Seiten, die eine JavaScript-Darstellung erfordern.

Suciu Dan20 min read
Artikel lesen
Wie man Redfin scrappt: Python-Leitfaden für Immobiliendaten
Anleitungen

Wie man Redfin scrappt: Python-Leitfaden für Immobiliendaten

TL;DR: Redfin stellt versteckte API-Endpunkte zur Verfügung, die strukturiertes JSON für Immobilienangebote zurückgeben, wodurch das fragile HTML-Parsing vollständig übersprungen werden kann. Diese Anleitung führt Sie durch den Aufbau eines Python-Scrapers, der Miet- und Verkaufsdaten extrahiert, nach Standort sucht, neue Angebote über XML-Sitemaps überwacht und saubere Ergebnisse in CSV oder JSON exportiert.

Suciu Dan11 min read
Artikel lesen

Los geht’s

Sind Sie bereit, Ihre Datenerfassung zu erweitern?

Schließen Sie sich den über 2.000 Unternehmen an, die WebScrapingAPI nutzen, um Webdaten im Unternehmensmaßstab ohne zusätzlichen Infrastrukturaufwand zu extrahieren.