{"id":3310,"library":"urllib3-future","title":"urllib3-future: HTTP/1.1, 2, and 3 Client (Sync & Async)","description":"urllib3.future is a powerful HTTP 1.1, 2, and 3 client with both synchronous and asynchronous interfaces, designed to be forward-looking. It provides a robust alternative to the standard urllib3 library, offering support for modern HTTP protocols and optional memory-safe TLS backends like Rustls. The project is under active and rapid development, with frequent releases.","status":"active","version":"2.19.905","language":"en","source_language":"en","source_url":"https://github.com/jawah/urllib3.future","tags":["http client","async","sync","http/1.1","http/2","http/3","networking","tls","rustls"],"install":[{"cmd":"pip install urllib3-future","lang":"bash","label":"Standard Install"},{"cmd":"pip install urllib3-future[rtls]","lang":"bash","label":"Install with Rustls TLS Backend"}],"dependencies":[{"reason":"Optional memory-safe TLS backend for enhanced security.","package":"rtls","optional":true}],"imports":[{"note":"The 'urllib3.future' package is typically imported with an alias to avoid conflicts with the standard 'urllib3' package and maintain clarity. Direct import from 'urllib3' may refer to the standard library.","wrong":"from urllib3 import AsyncConnectionPool","symbol":"AsyncConnectionPool","correct":"import urllib3.future as urllib3\npool = urllib3.AsyncConnectionPool(...)"},{"note":"The 'urllib3.future' package is typically imported with an alias to avoid conflicts with the standard 'urllib3' package and maintain clarity. Direct import from 'urllib3' may refer to the standard library.","wrong":"from urllib3 import ConnectionPool","symbol":"ConnectionPool","correct":"import urllib3.future as urllib3\npool = urllib3.ConnectionPool(...)"},{"note":"While 'PoolManager' exists, 'ConnectionPool' and 'AsyncConnectionPool' are the primary high-level interfaces highlighted in `urllib3.future` examples for direct usage.","symbol":"PoolManager","correct":"import urllib3.future as urllib3\nmanager = urllib3.PoolManager(...)"}],"quickstart":{"code":"import urllib3.future as urllib3\nimport asyncio\nimport os\n\n# Asynchronous example\nasync def async_example():\n    # No authentication needed for httpbin.org\n    pool = urllib3.AsyncConnectionPool(\"https://httpbin.org\")\n    try:\n        print(\"\\n--- Async Example ---\")\n        resp = await pool.request(\"GET\", \"/get\")\n        print(f\"Status: {resp.status}\")\n        # Decode data and truncate for cleaner output\n        print(f\"Data: {resp.data.decode('utf-8')[:200]}...\")\n    except Exception as e:\n        print(f\"Async request failed: {e}\")\n    finally:\n        await pool.close()\n\n# Synchronous example\ndef sync_example():\n    pool = urllib3.ConnectionPool(\"https://httpbin.org\")\n    try:\n        print(\"\\n--- Sync Example ---\")\n        resp = pool.request(\"GET\", \"/get\")\n        print(f\"Status: {resp.status}\")\n        print(f\"Data: {resp.data.decode('utf-8')[:200]}...\")\n    except Exception as e:\n        print(f\"Sync request failed: {e}\")\n    finally:\n        pool.close()\n\n# Run the examples\nif __name__ == \"__main__\":\n    asyncio.run(async_example())\n    sync_example() # Synchronous call, not within async loop","lang":"python","description":"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."},"warnings":[{"fix":"For 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.","message":"Header 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.","severity":"gotcha","affected_versions":"2.19.902, 2.19.903"},{"fix":"Always 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`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For 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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If 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.","message":"Installing 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.","severity":"gotcha","affected_versions":"All versions with `[rtls]` extra installed"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}