Requests (Python) Cheat Sheet

01Setup & Importinstall once

$ pip install requests
The only install you need; pulls in urllib3, charset-normalizer, idna, certifi.
import requests★
One flat namespace — no client to construct for simple calls.
requests.__version__
Check the installed version, e.g. '2.34.2'.
r = requests.get("https://httpbin.org/get")
The canonical one-liner. httpbin.org echoes your request — handy for testing.

02The HTTP Verbsone function each

requests.get(url, params=…)★
Read a resource. Safe & idempotent.
requests.post(url, json=…)★
Create / submit. Body carries the payload.
requests.put(url, json=…)
Replace a resource wholesale (idempotent).
requests.patch(url, json=…)
Partial update.
requests.delete(url)
Remove a resource.
requests.head(url)
Headers only, no body — cheap existence / size check.
requests.options(url)
Ask which methods / CORS the server allows.
requests.request("GET", url, **kw)
Generic form — the verb as a string. All the above delegate here.

03Query Parametersthe ?key=value string

get(url, params={"q": "x", "n": 2})★
Dict → ?q=x&n=2, URL-encoded & escaped for you.
params={"id": [1, 2]}
List value repeats the key → ?id=1&id=2.
params=[("k", "a"), ("k", "b")]
List of tuples when you need ordered / duplicate keys.
params="q=x&n=2"
A raw string is passed through verbatim.
r.url★
See the final URL that was actually requested — the best debug check.
requests.utils.quote("a b/c")
Percent-encode a single value by hand if you must.

04Sending a Bodydata vs json vs files

post(url, json={"a": 1})★
Serializes to JSON and sets Content-Type: application/json. The API default.
post(url, data={"a": 1})★
Dict → form-encoded (application/x-www-form-urlencoded), like an HTML form.
post(url, data='raw string')
A str / bytes body is sent as-is — no Content-Type added.
post(url, data=[("k","a"),("k","b")])
List of tuples for repeated form fields.
post(url, files={"f": open("a.png","rb")})
Multipart upload (multipart/form-data). See card 17.
json= ignored if data= or files=gotcha
Pass exactly one body kwarg. Mixing silently drops json=.

05Custom Headersdict in, dict out

get(url, headers={"User-Agent": "app/1.0"})★
Pass any request headers as a plain dict.
headers={"Authorization": "Bearer <tok>"}★
The usual way to send an API token (see card 14).
headers={"Accept": "application/json"}
Tell the server which representation you want back.
r.headers["Content-Type"]
Response headers are case-insensitive: r.headers["content-type"] works too.
r.request.headers
Inspect the headers that were actually sent.
custom headers = lower precedencenote
auth=, cookies=, redirects & .netrc can override a header you set.

06The Response Objecteverything on r

r.status_code★
200, 404, … as an int.
r.ok★
True for < 400. Quick success test.
r.text★
Body decoded to str using r.encoding.
r.content★
Body as raw bytes — use for images / binaries.
r.json()★
Parse a JSON body → dict / list.
r.headers
Case-insensitive dict of response headers.
r.url
Final URL (after params & redirects).
r.encoding
Charset used by .text; set it to override the guess.
r.elapsed
timedelta from send to headers-received.
r.reason
Text status, e.g. "Not Found".
r.cookies
Cookies the server set (a jar).

07Status & raise_for_statuserrors don't raise

# 404/500 do NOT raise on their ownkey
A bad status is still a valid Response. You must check it.
r.raise_for_status()★
Raises HTTPError for 4xx/5xx; no-op on success. The idiomatic guard.
if r.ok: …★
Truthy for any 1xx/2xx/3xx status.
r.status_code == requests.codes.ok
codes.ok == 200 — readable named constants.
requests.codes.not_found
404. Also codes.NOT_FOUND / codes["not_found"].
200 <= r.status_code < 300
Explicit range test when ok is too loose (it allows 3xx).

08Working with JSONthe API workhorse

data = r.json()★
Decode the response body into Python objects.
post(url, json=payload)★
Encode & send; sets the JSON Content-Type. Preferred over hand-dumping.
r.json() → JSONDecodeErrorgotcha
Raises if the body isn't valid JSON (e.g. an HTML error page). Guard with try / raise_for_status first.
from requests.exceptions import JSONDecodeError
Catch the parse failure specifically.
import json; data=json.dumps(x)note
Manual dump does not set the header — that's why json= exists.

09Cookiessend & receive

r.cookies["session"]
Read a cookie the server set on the response.
get(url, cookies={"session": "abc"})
Send cookies with a single call.
s = requests.Session()★
A Session persists cookies automatically — log in once, stay logged in.
s.cookies.set("k", "v")
Add a cookie to the jar for all later requests.
jar = requests.cookies.RequestsCookieJar()
Build a jar for domain/path-scoped cookies.

10Redirects & Historythe 3xx trail

r.history
List of the Responses that were redirected through, oldest first.
r.url
Where you ended up after all hops.
get(url, allow_redirects=False)
Stop at the first response; don't follow 3xx.
r.is_redirect · r.next
r.next is the PreparedRequest for the next hop.
head() defaults allow_redirects=Falsegotcha
Only HEAD differs — every other verb follows redirects by default.
auth & cookies stripped cross-hostnote
On a redirect to a different host, sensitive headers are dropped for safety.

11Timeoutsnever omit this

# NO timeout by default → can hang forevercritical
The #1 cause of stuck scripts. Always pass timeout=.
get(url, timeout=10)★
Seconds to wait for each of connect & read (a single float applies to both).
get(url, timeout=(3.05, 27))
(connect, read) tuple — fail fast on dial, allow slow bodies.
except requests.Timeout:
Covers both ConnectTimeout and ReadTimeout.
# timeout is per-attempt, not total
It bounds inactivity, not the full download time.

12Errors & Exceptionsall under one root

except requests.RequestException:★
Root of the tree — catch this to handle any requests failure.
except requests.ConnectionError:
DNS failure, refused connection, network down.
except requests.HTTPError:
Raised by raise_for_status() for 4xx/5xx.
except requests.Timeout:
Connect or read timed out.
except requests.TooManyRedirects:
Exceeded session.max_redirects (30).
except requests.exceptions.SSLError:
Certificate verification failed (subclass of ConnectionError).
e.response · e.request
On a caught error, inspect what was sent / received.

13Session Objectsreuse & persist

s = requests.Session()★
Reuses TCP connections (keep-alive) & persists cookies across calls.
with requests.Session() as s: …★
Context manager cleanly closes pooled sockets.
s.headers.update({"Authorization": …})★
Default headers sent on every request from this Session.
s.auth = ("user", "pass")
Set default auth once for all calls.
s.params = {"key": "<apikey>"}
Query params merged into every request.
r = s.get(url); r = s.post(url)
Same verb methods as the top-level API.

14Authenticationprove who you are

get(url, auth=("user", "pass"))★
Shorthand for HTTP Basic auth.
headers={"Authorization": "Bearer <tok>"}★
Bearer / API tokens go in a header, not auth=.
from requests.auth import HTTPBasicAuth
auth=HTTPBasicAuth("u","p") — the explicit form.
from requests.auth import HTTPDigestAuth
Digest auth: auth=HTTPDigestAuth("u","p").
class MyAuth(requests.auth.AuthBase):
Subclass AuthBase & define __call__(r) for custom schemes.

15Retries & Adaptersrequests won't retry

# requests never retries on its ownkey
Wire up a urllib3 Retry on an adapter.
from requests.adapters import HTTPAdapter, Retry★
Retry is re-exported here — no deep urllib3 import needed.
r = Retry(total=3, backoff_factor=0.5,
Exponential backoff: waits 0s, 0.5s, 1s, 2s…
status_forcelist=[429,500,502,503,504])★
Which statuses to retry — empty by default, so you must list them.
s.mount("https://", HTTPAdapter(max_retries=r))★
Attach to a Session for https:// (and mount http:// too).
allowed_methods=… # not method_whitelistgotcha
urllib3 v2 renamed it. Old cheat sheets using method_whitelist break.

16Streaming & Downloadsdon't load it all

get(url, stream=True)★
Defer the body — headers arrive, content stays on the wire until you read it.
for chunk in r.iter_content(chunk_size=8192):★
Stream bytes to disk; auto-decodes gzip/deflate.
for line in r.iter_lines():
Iterate a streaming text / NDJSON body line by line.
with requests.get(url, stream=True) as r:
Use a with block so the connection is released.
r.raw.read() # raw urllib3 stream
raw is undecoded bytes; prefer iter_content unless you truly need raw.
# body buffers in RAM unless stream=Truenote
Big downloads without streaming can exhaust memory.

17File Uploadsmultipart/form-data

post(url, files={"f": open("r.xls","rb")})★
Open in binary mode; the field name is the dict key.
files={"f": ("name.csv", fh, "text/csv")}
Tuple sets filename & content-type explicitly.
files={"f": ("a.txt", "in-memory text")}
A string/bytes value uploads without a real file on disk.
post(url, files=files, data={"caption": "x"})
Mix files + form fields in one multipart body.
# requests loads the whole file into memorynote
For huge uploads use a streaming body or a helper like requests-toolbelt.

18TLS / SSL & Proxiesverify & route

# verify=True by default (certifi CA bundle)★
Certificates are validated out of the box.
get(url, verify=False)danger
Disables TLS checks & only warns — never in production.
get(url, verify="/path/ca-bundle.pem")
Point at a custom CA bundle for internal / self-signed certs.
get(url, cert=("client.pem", "key.pem"))
Client-side certificate (mutual TLS).
get(url, proxies={"https": "http://10.0.0.1:8080"})★
Route by scheme through a proxy.
# respects HTTP_PROXY / HTTPS_PROXY env
Set trust_env=False on a Session to ignore them.

19Prepared Requests & Hooksthe escape hatch

req = requests.Request("GET", url, params=…)
Build a request without sending it.
p = s.prepare_request(req)
Fold in Session state → a PreparedRequest you can inspect / tweak.
r = s.send(p, timeout=10)
Fire the prepared request. Full control over the exact bytes sent.
p.body · p.headers · p.url
Examine or modify before sending.
get(url, hooks={"response": fn})
Run fn(r) on every response — logging, metrics, validation.

requests cheat sheet

Four pictures that make the API click

1 · Anatomy of a round trip

2 · Which body kwarg sets which Content-Type

3 · The exception hierarchy

4 · One body — four ways to read it

Worth memorizing