Requests

2.32.5 verified Tue May 12 auth: no python install: verified quickstart: stale

The de facto standard synchronous HTTP client for Python. Current version is 2.32.5 (Aug 2025). Stable, slow-moving library. Primary footgun: no default timeout — hangs forever by default. No async support — use httpx or aiohttp for async contexts.

pip install requests

Common errors

error requests.exceptions.Timeout: Read timed out. ↓

cause The request took longer than the specified `timeout` duration to receive a response from the server, or no timeout was specified causing the request to hang indefinitely.

fix

Always specify a timeout parameter (in seconds) in your requests calls to prevent indefinite hanging and handle the Timeout exception gracefully.

error requests.exceptions.SSLError: CERTIFICATE_VERIFY_FAILED ↓

cause The `requests` library failed to verify the SSL/TLS certificate presented by the server, often due to self-signed certificates, an untrusted CA, or an outdated certificate authority bundle on the client system.

fix

For trusted internal services or development, you can disable SSL verification with verify=False (use with caution for untrusted sites). For proper handling, ensure your system's CA certificates are up-to-date or provide a path to a custom certificate bundle using the verify parameter.

error requests.exceptions.ConnectionError: Max retries exceeded ↓

cause The `requests` library could not establish a connection to the target server, typically because the server is offline, the hostname or IP address is incorrect, or a network issue (like a firewall or DNS problem) is preventing access.

fix

Verify that the URL is correct, ensure the target server is running and accessible, check for any firewall restrictions, and confirm your network connectivity. Implement robust error handling for ConnectionError.

error ModuleNotFoundError: No module named 'request' ↓

cause This error occurs when you attempt to import `request` (singular) instead of `requests` (plural), which is the correct name of the HTTP library.

fix

Correct the import statement by changing import request to import requests.

Warnings

breaking NO default timeout. requests.get(url) without timeout= hangs indefinitely if the server is slow or unresponsive. This is the #1 production incident cause in requests-based code. LLMs almost never include timeout in generated code. ↓

fix Always pass timeout=(connect_timeout, read_timeout) or a single float: requests.get(url, timeout=30). For sessions: session.get(url, timeout=30).

breaking verify=False on first request in a Session leaked to all subsequent requests to the same origin (security bug fixed in 2.32.3 / GHSA-9wx4-h78v-vm56). If using older versions, verify=False permanently disabled SSL for that origin in the session. ↓

fix Upgrade to requests>=2.32.3. Avoid verify=False in production entirely.

breaking HTTPAdapter._get_connection() is deprecated since 2.32.0 following CVE-2024-35195. Custom HTTPAdapter subclasses that override _get_connection must migrate to get_connection_with_tls_context(). ↓

fix Override get_connection_with_tls_context(url, verify, cert, proxies) instead of _get_connection(). See requests 2.32.2 release notes for a minimal 2-line migration example.

breaking urllib3 2.x requires OpenSSL 1.1.1+. On Amazon Linux 2, RHEL 7, or Python builds using older OpenSSL: ImportError: urllib3 v2 only supports OpenSSL 1.1.1+. Upgrading requests pulls in urllib3 2.x which breaks these environments. ↓

fix On affected systems, pin urllib3<2: pip install 'urllib3<2'. Or upgrade the OS/Python to one with OpenSSL 1.1.1+.

gotcha requests has NO async support. Using requests in async code (asyncio, FastAPI, Starlette) blocks the entire event loop. requests.get() in an async def handler will freeze all concurrent requests. ↓

fix Use httpx.AsyncClient or aiohttp.ClientSession for async contexts. If you must use requests in async code, wrap in asyncio.to_thread(): await asyncio.to_thread(requests.get, url, timeout=30).

gotcha response.text uses charset detected from the response, which may be wrong. For JSON APIs, always use response.json() or response.content (bytes) rather than response.text to avoid encoding issues. ↓

fix Use response.json() for JSON responses. Use response.content for binary. Use response.text only when you know the encoding or check response.encoding first.

gotcha redirect follows are enabled by default (allow_redirects=True). Requests will silently follow redirects, including redirecting POST to GET (HTTP 302 behavior). Sensitive POST data may be sent to an unexpected URL. ↓

fix Pass allow_redirects=False for sensitive POST requests. Check response.history to see if redirects occurred.

breaking The TLS/SSL connection was unexpectedly closed by the peer (EOF) during or immediately after the handshake, leading to `SSLZeroReturnError`. This commonly indicates a server-side issue, an aggressive network intermediary, or a TLS version/cipher suite incompatibility where the server terminates the connection without a proper TLS alert. This is not typically a bug in requests/urllib3 itself, but an interaction problem. ↓

fix First, inspect the server's logs for TLS handshake errors. Use `curl -vvv <your_url>` to get detailed information about the TLS negotiation (client/server supported versions, ciphers) and see if `curl` succeeds. Ensure no network proxies or firewalls are prematurely terminating the connection. As a diagnostic step, ensure `requests` and `urllib3` are updated to their latest versions to benefit from the most recent TLS capabilities.

breaking DNS resolution failed. The hostname could not be resolved to an IP address (e.g., 'Name has no usable address' or 'Temporary failure in name resolution'). This typically indicates an environmental issue such as incorrect DNS server configuration, a firewall blocking DNS queries, or a typo in the hostname being requested. ↓

fix Verify the target hostname is spelled correctly. Ensure the execution environment (container, VM, host machine) has proper DNS server configuration and network connectivity to resolve external domain names.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.54s 21.1M

3.10 slim (glibc) - - 0.36s 22M

3.11 alpine (musl) - - 0.72s 23.2M

3.11 slim (glibc) - - 0.58s 24M

3.12 alpine (musl) - - 0.65s 15.0M

3.12 slim (glibc) - - 0.65s 15M

3.13 alpine (musl) - - 0.64s 14.6M

3.13 slim (glibc) - - 0.61s 15M

3.9 alpine (musl) - - 0.47s 20.4M

3.9 slim (glibc) - - 0.41s 21M

Imports

requests

wrong

import requests
response = requests.get('https://example.com')  # no timeout — hangs forever on unresponsive hosts

correct

import requests

# Always set a timeout
response = requests.get('https://example.com', timeout=30)

requests has NO default timeout. Omitting timeout= causes the request to block indefinitely on slow or unresponsive servers. This is the single most common production issue with requests.

Session

wrong

session = requests.Session()
response = session.get('https://example.com')
# session never closed — connection pool leak

correct

with requests.Session() as session:
    response = session.get('https://example.com', timeout=30)

Use Session as a context manager to ensure connection pool cleanup. Session objects reuse connections automatically — always prefer Session over repeated requests.get() calls.

Quickstart stale last tested: 2026-04-23

Always pass timeout=. Use Session for multiple requests to same host.

import requests

# One-shot (no connection reuse)
response = requests.get('https://httpbin.org/get', timeout=30)
response.raise_for_status()
data = response.json()

# Session (connection reuse, recommended)
with requests.Session() as session:
    session.headers.update({'Authorization': 'Bearer token'})
    r = session.get('https://api.example.com/users', timeout=30)
    r.raise_for_status()
    users = r.json()