Install & Compatibility
Where this runs
tested against v0.28.1 · 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.925 runs
installs and imports cleanly · install 0.0s · import 0.252s · 36.5MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 2.8s · import 0.238s · 45MB
39MB installed
● package 39MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
httpx
✓ import httpx
Top-level module import. All public symbols (Client, AsyncClient, Request, Response, etc.) are available under httpx.*
httpx.Client
✓ with httpx.Client() as client:
r = client.get('https://example.com')
✗ client = httpx.Client()
r = client.get('https://example.com')
# never call client.close() manually forgotten
Always use Client as a context manager (with statement) to ensure connections are properly closed and pooled.
httpx.AsyncClient
✓ async with httpx.AsyncClient() as client:
r = await client.get('https://example.com')
✗ client = httpx.AsyncClient()
r = await client.get('https://example.com')
Always use AsyncClient as an async context manager. Failing to do so leaks connections. Do not instantiate a new AsyncClient per request — reuse one instance.
httpx.Timeout
✓ httpx.Client(timeout=httpx.Timeout(5.0, connect=2.0))
✗ httpx.Client(timeout=5)
Passing a plain number sets all timeout phases equally. Use httpx.Timeout() for granular control of connect, read, write, and pool timeouts.
httpx.BasicAuth / httpx.Auth
✓ httpx.Client(auth=('user', 'pass'))
# or
httpx.Client(auth=httpx.BasicAuth('user', 'pass'))
Auth can be a (user, pass) tuple or an httpx.Auth subclass. NetRC auth is no longer automatic; use httpx.NetRCAuth() explicitly.
Minimal sync and async HTTP GET requests using httpx 0.28.x. Uses Client/AsyncClient as context managers for proper connection management.
import httpx
# One-off request (new connection each time — fine for scripts)
r = httpx.get('https://httpbin.org/get', timeout=10.0)
r.raise_for_status()
print(r.status_code) # 200
print(r.json()) # parsed JSON body
# Recommended: reuse a Client for multiple requests (connection pooling)
with httpx.Client(base_url='https://httpbin.org', timeout=10.0) as client:
resp = client.get('/get', params={'key': 'value'})
resp.raise_for_status()
print(resp.json())
# Async variant
import asyncio
async def main():
async with httpx.AsyncClient(base_url='https://httpbin.org', timeout=10.0) as client:
resp = await client.get('/get')
resp.raise_for_status()
print(resp.json())
asyncio.run(main())
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'httpx'
The 'httpx' library is not installed in your current Python environment.
fixInstall the library using pip: `pip install httpx`
TypeError: AsyncClient.__init__() got an unexpected keyword argument 'proxies'
In `httpx` versions 0.28.0 and later, the `proxies` argument was removed from `AsyncClient`'s constructor, leading to this error if older code or dependent libraries (e.g., `openai`) still try to pass it.
fixUpgrade the dependent library to a version compatible with `httpx` 0.28.x, or configure proxies using environment variables (HTTP_PROXY, HTTPS_PROXY), or downgrade `httpx` to a version prior to 0.28.0, such as `pip install httpx==0.27.2`.
RuntimeError: Attempted to send an sync request with an AsyncClient instance.
You are trying to call a synchronous request method (e.g., `client.get()`) on an `httpx.AsyncClient` instance without awaiting it, or within a synchronous context.
fixEnsure that all calls to `AsyncClient` methods are `await`ed and that the code runs within an `async` function and an `asyncio` event loop: `async with httpx.AsyncClient() as client: await client.get('https://example.com')` httpx.TimeoutException
A network operation (connection, read, or write) took longer than the configured timeout duration.
fixIncrease the timeout value when making the request or initializing the client: `httpx.get('https://example.com', timeout=10.0)` or `client = httpx.Client(timeout=httpx.Timeout(5.0, connect=10.0, read=20.0))`. httpx.UnsupportedProtocol
The URL provided is missing a protocol scheme (like 'http://' or 'https://') or uses a scheme not supported by `httpx`.
fixEnsure the URL includes a valid scheme: `httpx.get('https://www.example.com/')` instead of `httpx.get('www.example.com/')`. Upgrade
Version history
0.28.1latest on PyPI · released Dec 6, 2024
Audit
Dependencies
httpx[http2]optionalRequired to enable HTTP/2. Not included by default. Pass http2=True to Client or AsyncClient after installing.
httpx[cli]optionalInstalls the httpx command-line client. Optional development/debugging tool.
httpx[brotli]optionalEnables Brotli response content decoding via brotlipy.
httpx[zstd]optionalEnables Zstandard (zstd) response content decoding via the zstandard package.