Wie man cURL mit Python im Jahr 2026 verwendet

Wenn Sie Python programmieren und HTTP-APIs nutzen, ist Ihnen das wahrscheinlich schon einmal begegnet: Eine API-Dokumentation oder die Schaltfläche „Als cURL kopieren“ Ihres Browsers liefert Ihnen einen Einzeiler, der mit curl -X POST ..., und nun benötigen Sie diesen innerhalb eines Python-Skripts. Herauszufinden, wie man cURL mit Python verwendet, klingt einfach, hat aber mehr als eine richtige Antwort.

cURL selbst ist ein Befehlszeilentool zur Datenübertragung über Netzwerkprotokolle (HTTP, HTTPS, FTP). Von Python aus kannst du die curl-Binärdatei als externen Prozess aufrufen, die zugrunde liegende C-Bibliothek (libcurl) über PycURL steuern oder die Requests-Bibliothek als Python-Alternative nutzen. Jede Option hat Vor- und Nachteile hinsichtlich Geschwindigkeit, Kontrolle und Wartbarkeit.

Dieser Leitfaden richtet sich an Backend-, Daten- und Scraping-Entwickler, die bereits Python beherrschen und nach einer sauberen Methode suchen, um beliebige cURL-Schnipsel in funktionierenden Code zu übersetzen. Wir behandeln alle drei Methoden anhand lauffähiger Beispiele, ordnen gängige cURL-Flags ihren Python-Entsprechungen zu, bauen eine kleine Scraping-Pipeline auf und schließen mit der Fehlerbehebung ab, damit Sie den Code ausliefern können, anstatt mit Ihren Tools zu kämpfen.

Die meisten Teams stehen aus demselben Grund vor der Frage „cURL in Python“: Jemand hat ihnen einen cURL-Befehl gegeben. API-Dokumentationen liefern Request-Beispiele als curl Aufrufe, Browser-Entwicklertools exportieren Netzwerkaufrufe im gleichen Format, und mit Postman und Insomnia können Sie jede Anfrage als curl kopieren. Dieser Snippet ist die Quelle der Wahrheit, und Sie möchten, dass sich Ihr Python-Code identisch verhält.

Wenn du cURL in Python ausführst, kannst du zuerst genau diese Anfrage debuggen und dann zu einer idiomatischeren Lösung übergehen. Ein per subprocess beweist, dass der Endpunkt funktioniert. Von dort aus können Sie den Aufruf in PycURL oder Requests umschreiben, mit der Gewissheit, dass Sie das Datenformat nicht verändert haben. Diese kurze Feedbackschleife ist der eigentliche Grund, warum Entwickler wissen wollen, wie man cURL mit Python verwendet, und nicht curl für sich allein.

Wenn Entwickler fragen, wie man cURL mit Python verwendet, meinen sie in der Regel einen von drei konkreten Ansätzen. Bevor Sie Code schreiben, wählen Sie den Ansatz, der zur Aufgabe passt. Die drei Optionen sind nicht austauschbar, und die Wahl des falschen Ansatzes bedeutet in der Regel, dass der Aufruf später neu geschrieben werden muss.

Verwende subprocess als Ihren Übersetzungsschritt, PycURL als Ihr Power-Tool und Requests als Ihre Standardeinstellung. Der Großteil des Python-Produktionscodes landet bei Requests; die anderen beiden decken die Randfälle ab.

Das subprocess Modul ist Teil der Python-Standardbibliothek, sodass Sie curl aufrufen können, ohne etwas Neues installieren zu müssen. Dies ist die wörtlichste Interpretation von „cURL mit Python verwenden“ und wirklich nützlich, wenn Sie einen Befehl genau so ausführen möchten, wie er in der API-Dokumentation steht.

Eine unverzichtbare Sicherheitsregel: Übergeben Sie den Befehl als Liste von Argumenten, nicht als einzelne Shell-Zeichenkette. Zeichenketten laden Shell-Injection geradezu ein, wenn irgendein Teil der Anfrage aus Benutzereingaben stammt. Die Form als Argumentliste umgeht die Shell vollständig. Die Python-Dokumentation zu „subprocess“ behandelt das Sicherheitsmodell ausführlich.

Nehmen Sie einen Curl-Einzeiler, teilen Sie ihn in Token auf und übergeben Sie die Liste an subprocess.run. Setze capture_output=True so ein, dass stdout und stderr an Sie zurückgegeben werden, und text=True damit du Strings statt Bytes erhältst.

import subprocess

cmd = [
    "curl", "-s",
    "-H", "Accept: application/json",
    "https://httpbin.org/get?lang=python",
]

result = subprocess.run(cmd, capture_output=True, text=True, timeout=15)
print(result.stdout)

Das -s Flag schaltet die Fortschrittsanzeige von curl aus, sodass stdout nur der Antworttext enthalten ist. Das timeout=15 Argument löst subprocess.TimeoutExpired , wenn curl hängt, was genau das ist, was Sie in einem Skript wollen, das nicht endlos blockieren soll. Behalten Sie diese Form für die Übersetzung bei: Sobald es funktioniert, haben Sie eine verifizierte Basis, die Sie auf PycURL oder Requests portieren können.

Standardmäßig löst subprocess.run löst keine Ausnahme aus, wenn curl mit einem Wert ungleich Null beendet wird. Sie müssen den Rückgabecode selbst überprüfen oder explizit eine Ausnahme aktivieren.

import json, subprocess

result = subprocess.run(cmd, capture_output=True, text=True, timeout=15)

if result.returncode != 0:
    raise RuntimeError(f"curl failed ({result.returncode}): {result.stderr.strip()}")

try:
    payload = json.loads(result.stdout)
except json.JSONDecodeError as exc:
    raise RuntimeError(f"non-JSON response: {result.stdout[:200]}") from exc

print(payload["args"])

Sie können auch result.check_returncode()aufrufen, was CalledProcessError bei jedem Beendigungswert ungleich Null auslöst. In jedem Fall sollten Sie result.stderr , wenn der Aufruf fehlschlägt. Curl schreibt seine Diagnoseausgabe dorthin, und diese Meldung reicht in der Regel aus, um einen DNS-Fehler von einem TLS-Fehler oder einer 4xx-Antwort zu unterscheiden.

PycURL ist eine Python-Schnittstelle zu libcurl, derselben C-Bibliothek, auf der auch die curl-Binärdatei selbst basiert. Sie bietet Low-Level-Optionen für Timeouts, SSL-Konfiguration, Header, Cookies, Weiterleitungen und Protokolle jenseits von HTTP. Wenn es auf Durchsatz oder feinsteuerbare Kontrolle ankommt, ist PycURL die richtige Wahl.

Installieren Sie es mit pip install pycurl. Das Python-Paket ist ein schlanker Wrapper, daher benötigst du zusätzlich libcurl und OpenSSL-Entwicklungs-Header auf dem System. Unter Debian/Ubuntu ist das apt install libcurl4-openssl-dev libssl-dev; unter macOS brew install curl openssl. Wir werden die OpenSSL-Fehler beim Verknüpfen im Abschnitt zur Fehlerbehebung behandeln, da sie der häufigste Grund für das Scheitern einer Neuinstallation sind.

PycURL folgt dem libcurl-Muster: Handle erstellen, Optionen festlegen, ausführen, dann schließen. Schreibvorgänge erfolgen in einen dateiähnlichen Puffer, der in der Regel ein BytesIO.

import json, pycurl
from io import BytesIO
from urllib.parse import urlencode

# GET
buf = BytesIO()
c = pycurl.Curl()
c.setopt(c.URL, "https://httpbin.org/get?lang=python")
c.setopt(c.WRITEDATA, buf)
c.perform()
status = c.getinfo(pycurl.RESPONSE_CODE)
c.close()
print(status, buf.getvalue().decode("utf-8"))

Für einen form-encoded POST setzen POSTFIELDS auf einen URL-kodierten Body. Für JSON geben Sie das Dict aus und setzen die richtige Content-Type.

# POST form
form = urlencode({"a": 1, "b": "two"})
buf = BytesIO()
c = pycurl.Curl()
c.setopt(c.URL, "https://httpbin.org/post")
c.setopt(c.POSTFIELDS, form)
c.setopt(c.WRITEDATA, buf)
c.perform(); c.close()

# POST JSON
body = json.dumps({"hello": "world"})
buf = BytesIO()
c = pycurl.Curl()
c.setopt(c.URL, "https://httpbin.org/post")
c.setopt(c.HTTPHEADER, ["Content-Type: application/json"])
c.setopt(c.POSTFIELDS, body)
c.setopt(c.WRITEDATA, buf)
c.perform(); c.close()

Einstellung HTTPHEADER steuern Sie Content-Type, Accept, Authorization und alle anderen Request-Header. Darauf bauen wir als Nächstes auf.

HTTPHEADER erwartet eine Liste von "Name: value" Zeichenfolgen entgegen. Cookies können als Cookie Header bei einmaligen Aufrufen mitgesendet werden, oder Sie können libcurl einen Cookie-Speicher mit COOKIEFILE und COOKIEJAR.

c.setopt(c.HTTPHEADER, [
    "Accept: application/json",
    "Authorization: Bearer eyJhbGciOi...",
    "Cookie: session=abc123; theme=dark",
])

# Or use a cookie jar to persist Set-Cookie across requests
c.setopt(c.COOKIEFILE, "cookies.txt")
c.setopt(c.COOKIEJAR, "cookies.txt")

Für Weiterleitungen aktivieren Sie FOLLOWLOCATION (entspricht curl -L) und begrenzen Sie die Kette mit MAXREDIRS damit ein fehlerhafter Server Sie nicht endlos in eine Schleife führt.

c.setopt(c.FOLLOWLOCATION, True)
c.setopt(c.MAXREDIRS, 5)

Wenn Sie nur Antwort-Header benötigen (eine curl -I Anfrage im Stil von), setzen Sie NOBODY auf True und leiten Sie den Header-Stream über HEADERFUNCTION. Dieser Callback wird einmal pro Header-Zeile ausgeführt, was praktisch ist, wenn du nach Dingen wie Last-Modified oder Metadaten zur Ratenbegrenzung. Für ausführlichere Anleitungen siehe unsere Übersicht über HTTP-Antwort-Header in cURL.

WRITEDATA akzeptiert jedes dateiähnliche Objekt, sodass ein Download mit einer einzigen Zeile geändert werden kann: Öffne eine Datei im binären Schreibmodus und verweise libcurl darauf. Der Speicherverbrauch bleibt unabhängig von der Größe der Nutzdaten konstant.

import os, pycurl

url = "https://example.com/large.iso"
out = "large.iso"

mode = "ab" if os.path.exists(out) else "wb"
offset = os.path.getsize(out) if mode == "ab" else 0

with open(out, mode) as fp:
    c = pycurl.Curl()
    c.setopt(c.URL, url)
    c.setopt(c.WRITEDATA, fp)
    c.setopt(c.FOLLOWLOCATION, True)
    if offset:
        c.setopt(c.RANGE, f"{offset}-")  # resume from byte offset
    c.perform(); c.close()

Der Range: bytes={offset}- Header weist den Server an, nur den fehlenden Teil am Ende zu senden – genau so curl -C - unterbrochene Downloads fortgesetzt werden. Der Server muss Range-Anfragen unterstützen (die meisten CDNs tun dies).

Für die meisten alltäglichen Aufgaben ist Requests die Lösung. Es ist nicht im Lieferumfang von Python enthalten (Installation mit pip install requests), aber die API entspricht genau der Semantik von curl: Abfrageparameter, Header, Cookies, JSON-Inhalte und Timeouts sind allesamt Schlüsselwortargumente.

import requests

# GET with query params
r = requests.get(
    "https://httpbin.org/get",
    params={"lang": "python"},
    headers={"Accept": "application/json"},
    timeout=15,
)
r.raise_for_status()
print(r.json())

# POST JSON
r = requests.post(
    "https://httpbin.org/post",
    json={"hello": "world"},
    headers={"Authorization": "Bearer ..."},
    timeout=15,
)

raise_for_status() ist dein Freund: Es wandelt jeden 4xx/5xx-Fehler in einen requests.HTTPError, sodass der Unterschied zwischen Netzwerkfehlern (requests.ConnectionError, requests.Timeout) und HTTP-Fehlern bleibt in Ihrem Code klar erkennbar.

Wählen Sie standardmäßig Requests, wenn der Aufruf einer von vielen in einem Python-Programm ist, Sie einen Session-Status benötigen oder Ihr Team den Code warten wird. Wählen Sie PycURL, wenn Sie einen echten Engpass festgestellt haben oder Optionen benötigen, die nur libcurl bieten. Einen ausführlicheren Vergleich von Python-HTTP-Clients finden Sie in unserer Zusammenfassung zu diesem Thema.

Sobald Sie wissen, wie man cURL mit Python in allen drei Varianten verwendet, ist der schnellste Weg, einen neuen Befehl zu portieren, die Flags nacheinander zu übersetzen. Diese Tabelle enthält die Flags, die Sie in 95 % der API-Dokumentationen und Devtools-Exporte finden.

Wenn du lieber nicht von Hand übersetzen möchtest, gibt es öffentliche Curl-zu-Python-Konverter (der Konverter von ScrapingBee ist ein bekannter), die einen Curl-Befehl entgegennehmen und einen Requests-Aufruf mit ausgefüllten Headern, Parametern und Daten ausgeben. Nutze sie zum Starten und überprüfe dann die Ausgabe anhand dieser Tabelle auf Korrektheit.

Ein häufiger Grund, den Umgang mit cURL in Python zu erlernen, ist das Web-Scraping. Hier ist das Muster, das wir beim Prototyping eines kleinen Scrapers verwenden: HTML mit PycURL aus Geschwindigkeitsgründen abrufen, es mit BeautifulSoup parsen und dann das Ergebnis speichern. Das Ganze umfasst weniger als 40 Zeilen und deckt Statusprüfungen, Kodierung und das Schreiben in eine CSV-Datei ab.

import csv, json, pycurl
from io import BytesIO
from bs4 import BeautifulSoup

URL = "https://books.toscrape.com/catalogue/page-1.html"

def fetch(url: str) -> str:
    buf = BytesIO()
    c = pycurl.Curl()
    c.setopt(c.URL, url)
    c.setopt(c.WRITEDATA, buf)
    c.setopt(c.FOLLOWLOCATION, True)
    c.setopt(c.TIMEOUT, 20)
    c.setopt(c.HTTPHEADER, ["User-Agent: scraping-pipeline/1.0"])
    c.perform()
    code = c.getinfo(pycurl.RESPONSE_CODE)
    c.close()
    if code != 200:
        raise RuntimeError(f"unexpected status {code} for {url}")
    return buf.getvalue().decode("utf-8")

def parse(html: str) -> list[dict]:
    soup = BeautifulSoup(html, "html.parser")
    rows = []
    for card in soup.select("article.product_pod"):
        rows.append({
            "title": card.h3.a["title"],
            "price": card.select_one(".price_color").text.strip(),
            "stock": card.select_one(".availability").text.strip(),
        })
    return rows

def main():
    rows = parse(fetch(URL))
    with open("books.csv", "w", newline="") as fp:
        writer = csv.DictWriter(fp, fieldnames=rows[0].keys())
        writer.writeheader(); writer.writerows(rows)
    print(json.dumps(rows[:2], indent=2))

if __name__ == "__main__":
    main()

Ersetze PycURL durch subprocess , wenn Sie einen cURL-Befehl wortwörtlich ausführen möchten, oder durch Requests, wenn Sie den Sitzungsstatus benötigen. Sobald Sie auf reale Websites mit Ratenbeschränkungen und Anti-Bot-Abwehrmaßnahmen stoßen, werden Sie vor diesem Abrufschritt eine Proxy-Ebene benötigen.

Die meisten Schwierigkeiten beim Erlernen der Verwendung von cURL mit Python entstehen durch eine kleine Reihe wiederkehrender Fehler. Hier ist eine kurze Liste und wie man jeden einzelnen behebt.

• PycURL ImportError: pycurl: libcurl link-time ssl backend (...) is different from compile-time ssl backend (...). Ihr PycURL-Wheel wurde mit einem anderen SSL-Backend erstellt als die libcurl auf Ihrem System. Zum Zeitpunkt der Erstellung dieses Artikels ist die zuverlässigste Lösung unter macOS die Installation von OpenSSL über Homebrew und die Neuinstallation von PycURL aus dem Quellcode; unter Windows installieren Sie OpenSSL 1.1.x-Binärdateien und setzen PYCURL_SSL_LIBRARY, LIBund INCLUDE vorher pip install pycurl --no-binary :all:. Überprüfen Sie die PycURL-Installationshinweise für Ihre Plattform erneut, da sich die genauen Umgebungsvariablen über die verschiedenen Releases hinweg geändert haben.
• UnicodeEncodeError von PycURL bei POST-Body-Daten. PycURL erwartet Bytes für POSTFIELDS. Kodieren Sie Nicht-ASCII-Daten explizit: c.setopt(c.POSTFIELDS, body.encode("utf-8")).
• subprocess.TimeoutExpired. Übergeben Sie immer timeout= an subprocess.run. Behandeln Sie die Ausnahme als Netzwerkfehler, nicht als Fehler.
• TLS-Fehler und selbstsignierte Zertifikate. PycURL: c.setopt(c.SSL_VERIFYPEER, 0); Requests: verify=False. Tun Sie dies nur in vertrauenswürdigen Umgebungen und bevorzugen Sie in der Produktion das Pinning eines CA-Bundles.
• Unterscheidung zwischen HTTP- und Transportfehlern. Mit Requests sollten requests.HTTPError separat von requests.ConnectionError. Bei subprocess ist ein Wert ungleich Null returncode ein Fehler auf Transportebene; ein HTTP-4xx-Fehler gibt weiterhin 0 zurück, es sei denn, Sie übergeben --fail.

Sobald Sie alle drei Werkzeuge zur Verfügung haben, hängt die Wahl von der jeweiligen Situation ab.

• Debugging einer API oder Reproduzieren eines Fehlerberichts. Greifen Sie zuerst zu subprocess zuerst. Das Ausführen des wörtlichen curl-Befehls schließt „mein Python-Client ist das Problem“ als Ursache aus.
• Einmalige Skripte und CI-Jobs. Requests. Es ist lesbar, gut dokumentiert und für den nächsten Entwickler leicht zu warten.
• Lang laufende Scraper, hohe Anforderungsvolumina oder Protokolle jenseits von HTTP. PycURL. Du profitierst von der Wiederverwendung von Verbindungen durch libcurl, einer fein abgestimmten TLS-Steuerung und einem geringeren Overhead pro Anfrage.
• Cookies und Anmeldeabläufe. Requests Session ist der Weg des geringsten Widerstands; PycURLs Cookie-Jar ist die Alternative, wenn du bereits libcurl verwendest.

Bei der Verwendung von cURL mit Python geht es weniger darum, einen Gewinner zu wählen, als vielmehr darum, das richtige Werkzeug für die jeweilige Anfrage zu finden.

• Drei echte Optionen für die Kombination von curl mit Python: subprocess (die Binärdatei ausführen), PycURL (libcurl-Bindings) und Requests. Wählen Sie bewusst, nicht aus Gewohnheit.
• Verwenden Sie subprocess als Übersetzungsschicht: Überprüfen Sie das Wire-Format mit dem Befehl „literal“, und portieren Sie dann sicher zu PycURL oder Requests.
• Ordnen Sie curl-Flags systematisch Python-Befehlen zu: -H wird zu Headern, -d wird zu „data“ oder „json“, -G wird zu „params“, -F wird zu „files“, -L wird zu Follow-Redirects, -o wird zu einem gestreamten Schreibvorgang.
• Legen Sie immer Timeouts fest, überprüfen Sie immer die Statuscodes und behandeln Sie HTTP-Fehler als eine von Transportfehlern getrennte Kategorie.
• Bei Scraping mit hohem Datenaufkommen oder Downloads mit Wiederaufnahme-Unterstützung macht sich PycURL bezahlt. Für alles andere verwende standardmäßig Requests.

Beides. „cURL ausführen“ bedeutet in der Regel, die curl aus Python über subprocess, wofür curl in Ihrem PATH stehen muss. „Eine Python-Bibliothek verwenden“ bedeutet, PycURL (einen Wrapper um libcurl) oder Requests (einen reinen Python-HTTP-Client) zu importieren und die Binärdatei nie anzurühren. Die Netzwerk-Anfragen sehen für den Server identisch aus; nur der aufrufende Code unterscheidet sich.

PycURL ist in synthetischen Benchmarks im Allgemeinen schneller, da es die HTTP-Arbeit an libcurl in C auslagert. In realen Workloads schrumpft der Abstand: Netzwerklatenz, TLS-Handshakes und Parsing dominieren meist. PycURL hat bei Tausenden von gleichzeitigen Verbindungen, bei denen sich der Overhead pro Anfrage summiert, weiterhin die Nase vorn. Bei den meisten Skripten ist der Unterschied nicht messbar.

Fügen Sie den curl-Befehl in einen curl-zu-Python-Konverter ein (es gibt mehrere kostenlose Online-Varianten), wählen Sie die Requests-Ausgabe und überprüfen Sie den generierten Code anhand der Flag-Übersetzungstabelle in diesem Leitfaden. Der Konverter verarbeitet Header, Parameter und Daten automatisch. Sie sollten dennoch timeout, raise_for_status()und eine ordnungsgemäße Ausnahmebehandlung hinzufügen, bevor Sie den Code ausliefern.

Verwenden Sie in Requests das files Schlüsselwort: requests.post(url, files={"upload": open("data.csv", "rb")}). Für zusätzliche Kontrolle über Dateinamen und Content-Type übergeben Sie ein Tupel: files={"upload": ("data.csv", fp, "text/csv")}. In PycURL setzen Sie die HTTPPOST Option mit einer Liste von Tupeln, die jedes Formularfeld beschreiben, einschließlich eines pycurl.FORM_FILE Eintrag für den Pfad auf der Festplatte.

Dieser Fehler bedeutet, dass das Wheel gegen ein SSL-Backend erstellt wurde, das nicht mit Ihrer System-libcurl übereinstimmt. Die Lösung besteht darin, PycURL aus dem Quellcode gegen Ihre lokale libcurl neu zu installieren: pip install --no-binary :all: pycurl nach der Installation der libcurl- und OpenSSL-Entwicklungs-Header (brew install curl openssl unter macOS; die entsprechenden Entwicklerpakete unter Linux). Unter Windows müssen Sie vor der Neuinstallation die OpenSSL-Pfade über Umgebungsvariablen festlegen.

Zu wissen, wie man cURL mit Python verwendet, umfasst eigentlich drei Fähigkeiten in einer: den Aufruf der curl-Binärdatei mit subprocess, die Steuerung von libcurl über PycURL und das Schreiben idiomatischen Requests-Codes. Jede hat ihre Aufgabe. subprocess ist Ihr Übersetzungsschritt von der API-Dokumentation zu verifiziertem Code. PycURL ist Ihr Leistungswerkzeug für Scraper und Downloads mit hohem Durchsatz. Requests ist der Standard für alles andere, da es auch bei wachsendem Projektumfang lesbar bleibt.

Die Flag-zu-Python-Tabelle, das Rezept für Streaming-Downloads und die Liste zur Fehlerbehebung oben decken die meisten Ecken und Kanten ab. Was noch bleibt, ist das, was Ihr Zielserver mit Nicht-Browser-Traffic macht: Ratenbegrenzungen, CAPTCHAs, JavaScript-Herausforderungen und IP-Sperren treffen Sie irgendwann, egal wie sauber Ihr Python-Code ist.

Das ist die Ebene, auf die wir uns bei WebScrapingAPI konzentrieren. Wenn Sie mehr Zeit damit verbringen, Anti-Bot-Abwehrmaßnahmen zu umgehen, als Ihren Scraper zu schreiben, nimmt unsere Scraper-API eine Anfrage im Curl-Stil entgegen und gibt den rohen HTML-Code zurück, wobei sie Proxy-Rotation, CAPTCHA-Lösung und Wiederholungsversuche selbst übernimmt, sodass Sie Ihren Subprocess-, PycURL- oder Requests-Code genau so belassen können, wie er ist, und lediglich den Endpunkt austauschen müssen. Wählen Sie die Curl-Methode, die zu Ihrer Aufgabe passt, und überlassen Sie die Netzwerkebene anderen.