aiohttp

3.13.3 · active · verified Wed Mar 25

Async HTTP client/server framework for asyncio. Provides both a client (ClientSession) and a web server (web.Application). Current version is 3.13.3 (Jan 2026). Has removed several long-deprecated parameters that LLMs still generate.

Warnings

breaking timeout= parameter must be aiohttp.ClientTimeout, not int/float. Passing timeout=30 raises AttributeError: 'int' object has no attribute 'total' at request time, not at session creation. The error is confusing and delayed.
Fix: timeout = aiohttp.ClientTimeout(total=30, connect=10) async with aiohttp.ClientSession(timeout=timeout) as session: ...
breaking loop= parameter removed from ClientSession, TCPConnector, and all other aiohttp objects. Was deprecated for years; removed in 3.9. LLM-generated code from older tutorials passes loop=asyncio.get_event_loop().
Fix: Remove all loop= arguments. aiohttp uses the running event loop automatically.
breaking read_timeout and conn_timeout constructor parameters removed from ClientSession. Replaced by ClientTimeout.
Fix: Use aiohttp.ClientTimeout(total=..., connect=..., sock_read=...) instead.
breaking verify_ssl=, ssl_context=, and fingerprint= parameters deprecated in request methods. Replaced by unified ssl= parameter.
Fix: Use ssl=False to skip verification, ssl=ssl_context for custom context, ssl=aiohttp.Fingerprint(...) for fingerprint pinning.
deprecated app.loop, request.loop, client.loop, connector.loop properties deprecated and scheduled for removal in aiohttp 4.0.
Fix: Use asyncio.get_event_loop() or asyncio.get_running_loop() directly.
gotcha Creating ClientSession outside of an async context (e.g. at module level or in __init__) raises DeprecationWarning and will raise RuntimeError in a future version.
Fix: Always create ClientSession inside an async function or use async with at the point of use.
gotcha Response body must be consumed before the response context manager exits, or the connection is left in a broken state. await resp.json() / await resp.text() / await resp.read() must be called inside the async with block.
Fix: Always consume the response body inside the async with session.get(...) as resp: block.

Install

pip install aiohttp Core
pip install aiohttp[speedups] With Cython speedups (aiodns, brotli, backports.zstd)

Imports

ClientSession
```
import aiohttp

async with aiohttp.ClientSession() as session:
    async with session.get('https://example.com') as resp:
        data = await resp.json()
```
ClientSession must be used as an async context manager or closed explicitly with await session.close(). Creating it outside an async context was removed.
ClientTimeout
```
timeout = aiohttp.ClientTimeout(total=30)
async with aiohttp.ClientSession(timeout=timeout) as session: ...
```
The timeout parameter must be an aiohttp.ClientTimeout instance, not a plain int or float. Passing an int silently fails at request time with an AttributeError.

Quickstart

Client with ClientTimeout and basic web server setup.

import aiohttp
import asyncio

async def main():
    timeout = aiohttp.ClientTimeout(total=30)
    async with aiohttp.ClientSession(timeout=timeout) as session:
        async with session.get('https://httpbin.org/get') as resp:
            print(resp.status)
            data = await resp.json()
            print(data)

asyncio.run(main())

# Server
from aiohttp import web

async def handle(request):
    return web.Response(text='Hello')

app = web.Application()
app.add_routes([web.get('/', handle)])
web.run_app(app)

view raw JSON →