HTTPX for Python: an async-capable HTTP client that also ships a CLI

What HTTPX solves for Python code that talks to HTTP services

Python has had a comfortable HTTP client for years, and HTTPX does not pretend otherwise. The README states that it builds on the usability of requests and offers a broadly requests-compatible API. The problem it addresses is the gap that opens when a project outgrows that single style: you want the same ergonomics in an async service, or you want to call into a WSGI or ASGI application without going over a socket, or you want HTTP/2, and you would rather not maintain three different client stacks.

HTTPX is for Python 3 developers writing services, scripts or test harnesses that make outbound HTTP calls. The pyproject.toml declares Python 3.9 and newer, and classifies the project under AsyncIO and Trio, which tells you the async story is not an afterthought. The package description in pyproject.toml is simply "The next generation HTTP client." The classifier still says Development Status 4 - Beta, which is worth noting before you treat any API detail as frozen.

Sync and async share one API surface

The mechanism is a client object with two faces. The README gives the module-level shortcut first: import httpx, call httpx.get, and read status_code, headers and text off the response. That is the requests shape, and it is synchronous.

Async support is exposed through the same vocabulary. The README links to a dedicated async support page in the documentation, and lists async support if you need it as a feature. The underlying transport is httpcore, which the README names as the transport implementation, with h11 handling HTTP/1.1. The dependency list in pyproject.toml also includes anyio and sniffio; sniffio is described in the README as async library autodetection, so the client can work out which async framework is running rather than forcing one on you.

Two design choices stand out. Timeouts are strict everywhere according to the README, which is the opposite of the permissive default many Python developers are used to, and it means a forgotten timeout is less likely to hang a worker. The library is fully type annotated, so type checkers see the shapes of responses and clients rather than Any. Neither property is free: strict timeouts change behaviour when you port existing code, and full annotation is a maintenance burden the project has accepted.

Installing HTTPX and making a first request

The README gives pip as the installation route. The base install pulls in certifi, httpcore, anyio and idna according to pyproject.toml.

pip install httpx

After that, the README's own example is a module-level call. Run it in a REPL and you should see a Response object, a 200 status code, a content-type header and the page text.

>>> import httpx
>>> r = httpx.get('https://www.example.org/')
>>> r
<Response [200 OK]>
>>> r.status_code
200
>>> r.headers['content-type']
'text/html; charset=UTF-8'

If you want the command line client, the README shows that it is an optional dependency installed through an extra. The pyproject.toml entry point maps the httpx command to httpx:main, and the cli extra pulls in click, pygments and rich.

pip install 'httpx[cli]'

The README's CLI screenshots show the help output and a request to http://httpbin.org/json. HTTP/2 is likewise an extra, and the README is explicit that you install it with httpx[http2], which brings in h2. SOCKS proxy support comes from the socks extra, brotli and zstd decoding from their own extras.

Calling a WSGI or ASGI app without a network hop

One of the more distinctive features in the README is the ability to make requests directly to WSGI applications or ASGI applications, documented under advanced usage transports. This is the part that separates HTTPX from a plain HTTP client in test suites: you can exercise an application object in-process, keeping the request and response API identical to the networked path.

The trade-off is that the transport layer becomes something you configure rather than something you ignore. The default transport speaks to real sockets; the WSGI and ASGI transports do not. If your tests pass against an in-process transport and fail against a real server, the difference is in the transport, not in your assertion code. The README does not present this as a replacement for end-to-end testing, and it should not be treated as one.

Where HTTPX is the wrong tool, and what it costs

The clearest limitation is stated by the project itself: the API is broadly requests-compatible, and the README links to a compatibility page rather than claiming equivalence. Broadly is doing real work in that sentence. If you are porting a large codebase that depends on requests internals, response quirks or plugin behaviour, budget time for the differences instead of assuming a rename.

The async story is also conditional. Async support exists if you need it, but adding an event loop to a script that makes two sequential calls buys nothing and complicates error handling. The classifier marks the project as Beta, so pinning a version is sensible for anything long-lived. Optional features are genuinely optional: HTTP/2, SOCKS, brotli, zstd and the CLI all require extras, and the README does not document rollback or downgrade procedures for those dependencies. Finally, the README does not document built-in retry behaviour, so anything needing retries has to be built around the client rather than configured inside it.

HTTPX versus requests: the actual difference

The README credits requests for the API layout that much of the work follows, and credits urllib3 for design inspiration around lower-level networking. So the comparison is not stylistic. The difference is scope.

requests gives you a synchronous client and a mature ecosystem. HTTPX gives you a synchronous client plus an async client, HTTP/1.1 and HTTP/2 in one package, in-process WSGI and ASGI transports, and a bundled command line client. If your work is synchronous and stays that way, requests remains a reasonable choice and HTTPX adds a dependency tree you may not need. If your work spans a FastAPI service, a Trio-based worker and a terminal debugging session, HTTPX lets those three share one mental model. The README's own framing is that HTTPX builds on requests usability rather than replacing it, and that framing is accurate.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-03-29. The most recent release listed is 0.28.1 from 2024-12-06, with 0.28.0 and 0.27.2 before it. The gap between the latest release and the last push is the thing to weigh: source activity and tagged releases are not the same signal, and a project that pushes to master without cutting a release leaves users on older tags.

Licensing is BSD-3-Clause, declared both in the repository metadata and in pyproject.toml, with the licence file at LICENSE.md. That is a permissive licence, which generally means fewer obligations than a copyleft licence, but the practical implications for your distribution depend on how you ship the code. Read LICENSE.md rather than relying on the identifier alone.

Upgrade cost is mostly dependency cost. The base install is four packages. Add HTTP/2, SOCKS, brotli, zstd and the CLI and you are pulling in h2, socksio, brotli or brotlicffi, zstandard, click, pygments and rich. Each extra is opt-in, which keeps the default footprint small, but it also means version constraints live in your environment rather than in one place. The pyproject.toml pins httpcore to 1.*, click to 8.*, pygments to 2.*, socksio to 1.*, h2 to >=3,<5 and rich to >=10,<15, so those are the ranges you inherit.

Editorial conclusion

Adopt HTTPX if you need one client library that covers sync calls, async code, and a terminal client without rewriting your requests habits, and if you can install the optional extras for HTTP/2, SOCKS or the CLI. Do not adopt it expecting a drop-in replacement for every requests call: the README points to a separate compatibility page precisely because some behaviours differ. Before committing, verify that the Python version you target is 3.9 or newer, that any HTTP/2 dependency is acceptable to your packaging process, and that your code path actually benefits from async rather than just adding an event loop.

Frequently asked questions

Official sources

1. encode/httpx on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases