aiohttp — Async HTTP Client and Server for Python

Introduction

aiohttp is a mature asynchronous HTTP framework for Python built on top of asyncio. It provides both a client for making concurrent HTTP requests and a server for building web applications and APIs that handle high concurrency without thread pools, making it a foundation for many async Python projects.

What aiohttp Does

• Provides an async HTTP client with connection pooling and session management
• Includes a full web server framework with routing, middleware, and signals
• Supports WebSocket connections on both client and server sides
• Handles streaming request and response bodies for large payloads
• Offers multipart form data parsing and file upload handling

Architecture Overview

aiohttp runs on Python's asyncio event loop. The client uses a ClientSession that maintains a connection pool with keep-alive and cookie persistence. The server maps URL patterns to async handler coroutines via a router, processes requests through a middleware chain, and supports both traditional handler functions and class-based views. Internally it uses a hand-written HTTP parser for performance.

Self-Hosting & Configuration

• Install with pip install aiohttp and optionally aiohttp[speedups] for C extensions
• Create a server app with web.Application() and add routes via app.router.add_get()
• Run the server with web.run_app(app, host='0.0.0.0', port=8080)
• Deploy behind Nginx or with Gunicorn using the aiohttp.worker.GunicornWebWorker class
• Configure timeouts, connection limits, and SSL via TCPConnector and ClientTimeout

Key Features

• Connection pooling with configurable limits per host and total
• Built-in WebSocket support with ping/pong and close frame handling
• Middleware system for auth, CORS, logging, and error handling
• Streaming responses for serving large files without loading into memory
• Signal hooks for application startup, shutdown, and cleanup lifecycle events

Comparison with Similar Tools

• httpx — async client only, no server; aiohttp provides both client and server in one package
• FastAPI — higher-level with auto-generated docs; aiohttp is lower-level with more control over the HTTP layer
• requests — synchronous and blocking; aiohttp handles thousands of concurrent requests via asyncio
• Tornado — similar async approach but older; aiohttp is built on the standard asyncio event loop
• Starlette — ASGI-based and lighter; aiohttp has its own protocol implementation with more built-in features

FAQ

Q: Should I use aiohttp client or httpx? A: aiohttp client is mature and performant. httpx offers a requests-like API and HTTP/2 support. Choose based on your API preferences.

Q: Can I use aiohttp with Django or Flask? A: Not directly. aiohttp has its own server framework. Use the client portion alongside any framework for async HTTP calls.

Q: How do I handle graceful shutdown? A: Register cleanup callbacks with app.on_shutdown.append(cleanup_func). The server runs them when it receives a shutdown signal.

Q: Does aiohttp support HTTP/2? A: aiohttp currently supports HTTP/1.1. For HTTP/2, consider httpx or h2.

Sources

• https://github.com/aio-libs/aiohttp
• https://docs.aiohttp.org/en/stable/