Install & Compatibility
Where this runs
tested against v2.34.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.508s · 21.1MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 2.2s · import 0.447s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
requests
✓ import requests
# Always set a timeout
response = requests.get('https://example.com', timeout=30)
✗ import requests
response = requests.get('https://example.com') # no timeout — hangs forever on unresponsive hosts
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
✓ with requests.Session() as session:
response = session.get('https://example.com', timeout=30)
✗ session = requests.Session()
response = session.get('https://example.com')
# session never closed — connection pool leak
Use Session as a context manager to ensure connection pool cleanup. Session objects reuse connections automatically — always prefer Session over repeated requests.get() calls.
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()
Debug
Known issues
breakingNO 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.fixAlways pass timeout=(connect_timeout, read_timeout) or a single float: requests.get(url, timeout=30). For sessions: session.get(url, timeout=30).
affects: all
breakingverify=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.fixUpgrade to requests>=2.32.3. Avoid verify=False in production entirely.
affects: < 2.32.3
breakingHTTPAdapter._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().fixOverride 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.
affects: >= 2.32.0
breakingurllib3 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.fixOn affected systems, pin urllib3<2: pip install 'urllib3<2'. Or upgrade the OS/Python to one with OpenSSL 1.1.1+.
affects: all (when urllib3>=2.0 installed)
gotcharequests 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.fixUse 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).
affects: all
gotcharesponse.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.fixUse response.json() for JSON responses. Use response.content for binary. Use response.text only when you know the encoding or check response.encoding first.
affects: all
gotcharedirect 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.fixPass allow_redirects=False for sensitive POST requests. Check response.history to see if redirects occurred.
affects: all
breakingThe 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.fixFirst, 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.
affects: all
breakingDNS 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.fixVerify 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.
affects: all
Errors
Common errors & fixes
requests.exceptions.Timeout: Read timed out.
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.
fixAlways specify a `timeout` parameter (in seconds) in your `requests` calls to prevent indefinite hanging and handle the `Timeout` exception gracefully.
requests.exceptions.SSLError: CERTIFICATE_VERIFY_FAILED
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.
fixFor 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.
requests.exceptions.ConnectionError: Max retries exceeded
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.
fixVerify 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`.
ModuleNotFoundError: No module named 'request'
This error occurs when you attempt to import `request` (singular) instead of `requests` (plural), which is the correct name of the HTTP library.
fixCorrect the import statement by changing `import request` to `import requests`.
Upgrade
Version history
2.34.2latest on PyPI · released May 14, 2026
Audit
Dependencies
urllib3>=1.21.1,<3requiredHTTP connection pooling. Installed automatically. urllib3 2.x requires OpenSSL 1.1.1+.
certifi>=2017.4.17requiredCA certificate bundle. Installed automatically.
charset-normalizer>=2,<4requiredCharacter encoding detection. Installed automatically.
idna<4,>=2.5requiredInternationalized domain names. Installed automatically.