Install & Compatibility
Where this runs
tested against v2.24.905 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.424s · 41.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.9s · import 0.410s · 40MB
39MB installed
● package 39MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PoolManager
✓ from urllib3 import PoolManager
✗ import urllib3.future as urllib3
AsyncPoolManager
✓ from urllib3 import AsyncPoolManager
✗ import urllib3.future as urllib3
AsyncHTTPConnectionPool
✓ from urllib3 import AsyncHTTPConnectionPool
✗ import urllib3.future as urllib3
Demonstrates both asynchronous and synchronous usage patterns with `AsyncConnectionPool` and `ConnectionPool` respectively, fetching data from `httpbin.org`. The async example is run via `asyncio.run()`, and the sync example is called directly.
import urllib3.future as urllib3
import asyncio
import os
# Asynchronous example
async def async_example():
# No authentication needed for httpbin.org
pool = urllib3.AsyncConnectionPool("https://httpbin.org")
try:
print("\n--- Async Example ---")
resp = await pool.request("GET", "/get")
print(f"Status: {resp.status}")
# Decode data and truncate for cleaner output
print(f"Data: {resp.data.decode('utf-8')[:200]}...")
except Exception as e:
print(f"Async request failed: {e}")
finally:
await pool.close()
# Synchronous example
def sync_example():
pool = urllib3.ConnectionPool("https://httpbin.org")
try:
print("\n--- Sync Example ---")
resp = pool.request("GET", "/get")
print(f"Status: {resp.status}")
print(f"Data: {resp.data.decode('utf-8')[:200]}...")
except Exception as e:
print(f"Sync request failed: {e}")
finally:
pool.close()
# Run the examples
if __name__ == "__main__":
asyncio.run(async_example())
sync_example() # Synchronous call, not within async loop
Debug
Known issues
gotchaHeader precedence behavior was subject to confusing changes between versions 2.19.902 and 2.19.903. While the intent is for user-supplied headers to take precedence over extension defaults (e.g., for SSE), the exact behavior during this period was ambiguous due to conflicting release notes.fixFor critical applications, explicitly test header behavior if upgrading from or using versions in this range. The current (2.19.903+) expectation is that user-supplied headers should take precedence, but verify for your specific use case.
affects: 2.19.902, 2.19.903
gotcha`urllib3-future` is a distinct library, not a drop-in replacement or a fork of the standard `urllib3`. While it shares similar API patterns, it may introduce differences, especially around asynchronous features, HTTP/2/3, and specific connection management. Direct compatibility is not guaranteed for all `urllib3` use cases.fixAlways import as `import urllib3.future as urllib3` to clearly differentiate from the standard library. Refer to the specific `urllib3-future` documentation for API details and behavioral nuances rather than assuming parity with `urllib3`.
affects: All versions
gotchaThe project exhibits a rapid release cadence (daily/weekly) and uses high patch version numbers (e.g., `.905`) within a `2.x` major version. This signifies active and rapid development, where minor behavioral changes or API tweaks could occur even in what appear to be 'patch' releases.fixFor production deployments, pin exact package versions (`urllib3-future==X.Y.Z`) to avoid unexpected changes from new releases. Review release notes diligently for any changes that might affect your application.
affects: All versions
gotchaInstalling the `[rtls]` extra automatically switches the underlying TLS backend to Rustls. While Rustls is lauded for memory safety and security, it is a different implementation than OpenSSL (used by default in CPython and standard `urllib3`). This may lead to subtle behavioral differences, particularly with advanced SSL/TLS configurations or specific certificate authorities.fixIf encountering unexpected SSL/TLS errors or certificate issues, first test without the `[rtls]` extra. When passing `stdlib` `ssl.SSLContext` objects, be aware that the conversion to `rtls.SSLContext` is a 'best effort' as of 2.19.905 and might not perfectly map all configurations.
affects: All versions with `[rtls]` extra installed
Upgrade
Version history
2.24.905latest on PyPI · released Aug 28, 2026
Audit
Dependencies
rtlsoptionalOptional memory-safe TLS backend for enhanced security.