Welcome to AIOHTTP¶

Asynchronous HTTP Client/Server for asyncio and Python.

Current version is 4.0.0a2.dev0.

Key Features¶

Supports both Client and HTTP Server.
Supports both Server WebSockets and Client WebSockets out-of-the-box without the Callback Hell.
Web-server has Middlewares, Signals and plugable routing.

Library Installation¶

$ pip install aiohttp

You may want to install optional cchardet library as faster replacement for charset-normalizer:

$ pip install cchardet

Warning

Note that the cchardet project is known not to support Python 3.10 or higher. See #6819 and GitHub: PyYoshi/cChardet/issues/77 for more details.

For speeding up DNS resolving by client API you may install aiodns as well. This option is highly recommended:

$ pip install aiodns

Installing speedups altogether¶

The following will get you aiohttp along with cchardet, aiodns and Brotli in one bundle. No need to type separate commands anymore!

$ pip install aiohttp[speedups]

Getting Started¶

Client example¶

import aiohttp
import asyncio

async def main():

    async with aiohttp.ClientSession() as session:
        async with session.get('http://python.org') as response:

            print("Status:", response.status)
            print("Content-type:", response.headers['content-type'])

            html = await response.text()
            print("Body:", html[:15], "...")

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

This prints:

Status: 200
Content-type: text/html; charset=utf-8
Body: <!doctype html> ...

Coming from requests ? Read why we need so many lines.

Server example:¶

from aiohttp import web

async def handle(request):
    name = request.match_info.get('name', "Anonymous")
    text = "Hello, " + name
    return web.Response(text=text)

app = web.Application()
app.add_routes([web.get('/', handle),
                web.get('/{name}', handle)])

if __name__ == '__main__':
    web.run_app(app)

For more information please visit Client and Server pages.

What’s new in aiohttp 3?¶

Go to What’s new in aiohttp 3.0 page for aiohttp 3.0 major release changes.

Tutorial¶

Polls tutorial

Source code¶

The project is hosted on GitHub

Please feel free to file an issue on the bug tracker if you have found a bug or have some suggestion in order to improve the library.

The library uses Azure Pipelines for Continuous Integration.

Dependencies¶

async_timeout
charset-normalizer
multidict
yarl
Optional cchardet as faster replacement for charset-normalizer.

Install it explicitly via:
```
$ pip install cchardet
```
Optional aiodns for fast DNS resolving. The library is highly recommended.
```
$ pip install aiodns
```
Optional Brotli for brotli (RFC 7932) client compression support.
```
$ pip install Brotli
```

Communication channels¶

aio-libs Discussions: https://github.com/aio-libs/aiohttp/discussions

Feel free to post your questions and ideas here.

gitter chat https://gitter.im/aio-libs/Lobby

We support Stack Overflow. Please add aiohttp tag to your question there.

Contributing¶

Please read the instructions for contributors before making a Pull Request.

Authors and License¶

The aiohttp package is written mostly by Nikolay Kim and Andrew Svetlov.

It’s Apache 2 licensed and freely available.

Feel free to improve this package and send a pull request to GitHub.

Policy for Backward Incompatible Changes¶

aiohttp keeps backward compatibility.

When a new release is published that deprecates a Public API (method, class, function argument, etc.), the library will guarantee its usage for at least a year and half from the date of release.

Deprecated APIs are reflected in their documentation, and their use will raise DeprecationWarning.

However, if there is a strong reason, we may be forced to break this guarantee. The most likely reason would be a critical bug, such as a security issue, which cannot be solved without a major API change. We are working hard to keep these breaking changes as rare as possible.