python aiohttp vs httpx: Choosing the Right HTTP Client
aiohttp vs httpx in Python: compare async and sync APIs, streaming, timeouts, HTTP/2 support, and decide which HTTP client fits your project.

When you need to make HTTP requests in Python, aiohttp and httpx are two of the most common libraries. The choice between them depends on whether you need a full async framework, a sync API, or HTTP/2 support. This article compares their APIs, practical usage, and typical use cases.
What aiohttp and httpx Actually Are
aiohttp is an asynchronous HTTP client and server library built on asyncio. It has been a core part of the Python async ecosystem for years and is widely used in high-concurrency applications such as web scrapers, microservices, and IoT gateways. Its client API is designed exclusively for async code, meaning you must use it inside an event loop.
httpx is a modern HTTP client that offers both sync and async interfaces. It was created to fill the gap left by requests, which does not support asyncio, and to provide a more feature-rich alternative to aiohttp for client-side work. httpx does not include a server implementation; it focuses on making HTTP requests with a clean, requests-like API.
The most important distinction is that aiohttp is a full async framework, while httpx is a client library that works in both sync and async contexts. This affects everything from API design to how you handle concurrency.
Core API Differences
The basic request syntax differs significantly. aiohttp requires you to create a session and use await for every network operation. httpx offers a Client object for sync code and an AsyncClient for async code, but the method names and argument patterns are nearly identical to requests.
Here is a minimal GET request with aiohttp:
import aiohttp
import asyncio
async def fetch(session, url):
async with session.get(url) as resp:
return await resp.text()
async def main():
async with aiohttp.ClientSession() as session:
html = await fetch(session, 'https://example.com')
print(html)
asyncio.run(main())With httpx, the same request can be written synchronously:
import httpx
response = httpx.get('https://example.com')
print(response.text)Or asynchronously:
import httpx
import asyncio
async def main():
async with httpx.AsyncClient() as client:
response = await client.get('https://example.com')
print(response.text)
asyncio.run(main())Notice that aiohttp always requires a session object, while httpx can use a module-level function for simple requests. If you need to make many requests, both libraries recommend reusing a session or client to benefit from connection pooling.
Async and Sync Usage
The choice between async and sync is the primary driver when picking a library. aiohttp forces you to write async code, which is beneficial in event-driven applications that need to handle many concurrent connections without blocking the event loop. However, it adds complexity: you must manage the event loop, use async with for sessions and responses, and be careful about mixing sync blocking code inside async functions.
httpx gives you the flexibility to write sync code when you are in a script, a Jupyter notebook, or a traditional threaded server, and switch to async when you are inside an asyncio application. This is especially useful when you are migrating an existing requests-based codebase to async incrementally.
For example, you can use httpx in a sync function without any event loop:
import httpx
def get_status(url):
with httpx.Client() as client:
response = client.get(url)
return response.status_codeAnd in an async function with the same logic:
import httpx
async def get_status_async(url):
async with httpx.AsyncClient() as client:
response = await client.get(url)
return response.status_codeaiohttp has no sync API. If you need to call aiohttp from sync code, you typically have to run the event loop manually with asyncio.run() or loop.run_until_complete(), which can be awkward in larger applications.
Streaming and Response Handling
Streaming responses are a common requirement when downloading large files or processing server-sent events. Both libraries support streaming, but the APIs differ.
With aiohttp, you use the content attribute of the response to iterate over chunks:
import aiohttp
import asyncio
async def download(url):
async with aiohttp.ClientSession() as session:
async with session.get(url) as resp:
async for chunk in resp.content.iter_chunked(1024):
# process chunk
passhttpx offers a stream context manager that gives you access to the raw response bytes:
import httpx
with httpx.Client() as client:
with client.stream('GET', 'https://example.com/large-file') as r:
for chunk in r.iter_bytes():
# process chunk
passIn async httpx, the pattern is similar but with await on the stream context:
import httpx
async def download_async(url):
async with httpx.AsyncClient() as client:
async with client.stream('GET', url) as r:
async for chunk in r.aiter_bytes():
# process chunk
passThe key difference is that aiohttp always works in an async context, so streaming naturally uses async for. httpx provides both sync and async iteration methods, so you can choose the style that fits your environment.
Timeouts and Cancellation
Timeout handling is another area where the two libraries diverge. aiohttp uses a ClientTimeout configuration object that you can apply to a request or a session. httpx uses a Timeout configuration class that can be set per request or per client.
In aiohttp, you can set a timeout for a single request:
import aiohttp
import asyncio
async def fetch_with_timeout():
timeout = aiohttp.ClientTimeout(total=10)
async with aiohttp.ClientSession(timeout=timeout) as session:
async with session.get('https://example.com') as resp:
return await resp.text()httpx allows similar configuration:
import httpx
timeout = httpx.Timeout(10.0)
with httpx.Client(timeout=timeout) as client:
response = client.get('https://example.com')For async cancellation, aiohttp is tightly integrated with asyncio. If you cancel a task that is awaiting a response, the underlying connection is closed properly. httpx also supports cancellation when used with asyncio, but because it also offers sync mode, the behavior depends on whether you are using AsyncClient or Client. In sync mode, cancellation is not possible in the same way; you would need to run the request in a separate thread.
HTTP/2 and Advanced Features
httpx has built-in support for HTTP/2 when the optional h2 package is installed. This can be important for services that need to multiplex many requests over a single connection. aiohttp does not support HTTP/2 natively; you would need to use a different library or a proxy that terminates HTTP/2.
httpx also supports HTTP/1.1 and includes features like client certificates, proxies, and custom authentication. aiohttp provides similar features but focuses on the async ecosystem. For example, aiohttp integrates well with asyncio-based libraries like aiohttp-session for server-side work, but as a client it does not offer HTTP/2.
If you need HTTP/2, the choice is clear: httpx supports it (with the optional h2 dependency), while aiohttp does not. However, aiohttp's server capability might be relevant if you are building a full async web service and want to use the same library for both client and server.
Choosing Between aiohttp and httpx
The decision depends on your project's context. Use aiohttp when you are already building an asyncio application and need a client that is tightly coupled with the event loop, especially if you also need a server component. aiohttp's session management and connection pooling are designed for high concurrency, and its API is stable and proven in production.
Use httpx when you need a flexible client that can work in both sync and async code, or when you need HTTP/2 support. httpx is also a better choice if you are coming from requests and want a similar API without rewriting all your sync code. Its Client and AsyncClient share the same interface, making it easier to switch between sync and async as requirements change.
For a simple script that makes a few requests, httpx's module-level functions are convenient. For a long-running async service that makes many concurrent calls, aiohttp's session reuse and explicit async model may give you more control. But if you are not sure, httpx is often the safer default because it does not force you into async mode and still offers a complete async interface when you need it.
One final consideration is ecosystem compatibility. If you are using libraries like aiohttp-session or aiohttp-devtools, aiohttp is the natural choice. If you are integrating with requests-based tools or need to share client code between sync and async parts of your codebase, httpx reduces friction. Both libraries are actively maintained, so the choice should be based on your specific requirements rather than on features that are likely to change.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.