Skip to main content

Async http client/server framework (asyncio)

Project description

Async http client/server framework

aiohttp logo

Travis status for master branch AppVeyor status for master branch status for master branch Latest PyPI package version Latest Read The Docs Chat on Gitter

Key Features

  • Supports both client and server side of HTTP protocol.

  • Supports both client and server Web-Sockets out-of-the-box and avoids Callback Hell.

  • Provides Web-server with middlewares and pluggable routing.

Getting started


To get something from the web:

import aiohttp
import asyncio

async def fetch(session, url):
    async with session.get(url) as response:
        return await response.text()

async def main():
    async with aiohttp.ClientSession() as session:
        html = await fetch(session, '')

if __name__ == '__main__':
    loop = asyncio.get_event_loop()


An example using a simple server:

# examples/
from aiohttp import web

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

async def wshandle(request):
    ws = web.WebSocketResponse()
    await ws.prepare(request)

    async for msg in ws:
        if msg.type == web.WSMsgType.text:
            await ws.send_str("Hello, {}".format(
        elif msg.type == web.WSMsgType.binary:
            await ws.send_bytes(
        elif msg.type == web.WSMsgType.close:

    return ws

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

if __name__ == '__main__':



Communication channels

aio-libs google group:!forum/aio-libs

Feel free to post your questions and ideas here.

gitter chat

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


Optionally you may install the cChardet and aiodns libraries (highly recommended for sake of speed).


aiohttp is offered under the Apache 2 license.


The aiohttp community would like to thank Keepsafe ( for its support in the early days of the project.

Source code

The latest developer version is available in a GitHub repository:


If you are interested in efficiency, the AsyncIO community maintains a list of benchmarks on the official wiki:


3.6.1 (2019-09-19)


  • Compatibility with Python 3.8. #4056


  • correct some exception string format #4068

  • Emit a warning when ssl.OP_NO_COMPRESSION is unavailable because the runtime is built against an outdated OpenSSL. #4052

  • Update multidict requirement to >= 4.5 #4057

Improved Documentation

  • Provide pytest-aiohttp namespace for pytest fixtures in docs. #3723

3.6.0 (2019-09-06)


  • Add support for Named Pipes (Site and Connector) under Windows. This feature requires Proactor event loop to work. #3629

  • Removed Transfer-Encoding: chunked header from websocket responses to be compatible with more http proxy servers. #3798

  • Accept non-GET request for starting websocket handshake on server side. #3980


  • Raise a ClientResponseError instead of an AssertionError for a blank HTTP Reason Phrase. #3532

  • Fix an issue where cookies would sometimes not be set during a redirect. #3576

  • Change normalize_path_middleware to use 308 redirect instead of 301.

    This behavior should prevent clients from being unable to use PUT/POST methods on endpoints that are redirected because of a trailing slash. #3579

  • Drop the processed task from all_tasks() list early. It prevents logging about a task with unhandled exception when the server is used in conjunction with #3587

  • Signal type annotation changed from Signal[Callable[[‘TraceConfig’], Awaitable[None]]] to Signal[Callable[ClientSession, SimpleNamespace, …]. #3595

  • Use sanitized URL as Location header in redirects #3614

  • Improve typing annotations for along with changes required by mypy in files that references #3621

  • Close session created inside aiohttp.request when unhandled exception occurs #3628

  • Cleanup per-chunk data in generic data read. Memory leak fixed. #3631

  • Use correct type for add_view and family #3633

  • Fix _keepalive field in __slots__ of RequestHandler. #3644

  • Properly handle ConnectionResetError, to silence the “Cannot write to closing transport” exception when clients disconnect uncleanly. #3648

  • Suppress pytest warnings due to test_utils classes #3660

  • Fix overshadowing of overlapped sub-application prefixes. #3701

  • Fixed return type annotation for WSMessage.json() #3720

  • Properly expose TooManyRedirects publicly as documented. #3818

  • Fix missing brackets for IPv6 in proxy CONNECT request #3841

  • Make the signature of aiohttp.test_utils.TestClient.request match asyncio.ClientSession.request according to the docs #3852

  • Use correct style for re-exported imports, makes mypy --strict mode happy. #3868

  • Fixed type annotation for add_view method of UrlDispatcher to accept any subclass of View #3880

  • Made cython HTTP parser set Reason-Phrase of the response to an empty string if it is missing. #3906

  • Add URL to the string representation of ClientResponseError. #3959

  • Accept istr keys in LooseHeaders type hints. #3976

  • Fixed race conditions in _resolve_host caching and throttling when tracing is enabled. #4013

  • For URLs like “unix://localhost/…” set Host HTTP header to “localhost” instead of “localhost:None”. #4039

Improved Documentation

  • Modify documentation for Background Tasks to remove deprecated usage of event loop. #3526

  • use if __name__ == '__main__': in server examples. #3775

  • Update documentation reference to the default access logger. #3783

  • Improve documentation for web.BaseRequest.path and web.BaseRequest.raw_path. #3791

  • Removed deprecation warning in tracing example docs #3964

3.5.4 (2019-01-12)


  • Fix stream .read() / .readany() / .iter_any() which used to return a partial content only in case of compressed content #3525

3.5.3 (2019-01-10)


  • Fix type stubs for aiohttp.web.run_app(access_log=True) and fix edge case of access_log=True and the event loop being in debug mode. #3504

  • Fix aiohttp.ClientTimeout type annotations to accept None for fields #3511

  • Send custom per-request cookies even if session jar is empty #3515

  • Restore Linux binary wheels publishing on PyPI

3.5.2 (2019-01-08)


  • FileResponse from uses a ThreadPoolExecutor to work with files asynchronously. I/O based payloads from uses a ThreadPoolExecutor to work with I/O objects asynchronously. #3313

  • Internal Server Errors in plain text if the browser does not support HTML. #3483


  • Preserve MultipartWriter parts headers on write.

    Refactor the way how Payload.headers are handled. Payload instances now always have headers and Content-Type defined.

    Fix Payload Content-Disposition header reset after initial creation. #3035

  • Log suppressed exceptions in GunicornWebWorker. #3464

  • Remove wildcard imports. #3468

  • Use the same task for app initialization and web server handling in gunicorn workers. It allows to use Python3.7 context vars smoothly. #3471

  • Fix handling of chunked+gzipped response when first chunk does not give uncompressed data #3477

  • Replace collections.MutableMapping with to avoid a deprecation warning. #3480

  • Payload.size type annotation changed from Optional[float] to Optional[int]. #3484

  • Ignore done tasks when cancels pending activities on web.run_app finalization. #3497

Improved Documentation

  • Add documentation for aiohttp.web.HTTPException. #3490


3.5.1 (2018-12-24)

  • Fix a regression about ClientSession._requote_redirect_url modification in debug mode.

3.5.0 (2018-12-22)


  • The library type annotations are checked in strict mode now.

  • Add support for setting cookies for individual request (#2387)

  • Application.add_domain implementation (#2809)

  • The default app in the request returned by test_utils.make_mocked_request can now have objects assigned to it and retrieved using the [] operator. (#3174)

  • Make request.url accessible when transport is closed. (#3177)

  • Add zlib_executor_size argument to Response constructor to allow compression to run in a background executor to avoid blocking the main thread and potentially triggering health check failures. (#3205)

  • Enable users to set ClientTimeout in aiohttp.request (#3213)

  • Don’t raise a warning if NETRC environment variable is not set and ~/.netrc file doesn’t exist. (#3267)

  • Add default logging handler to web.run_app

    If the Application.debug flag is set and the default logger aiohttp.access is used, access logs will now be output using a stderr StreamHandler if no handlers are attached. Furthermore, if the default logger has no log level set, the log level will be set to DEBUG. (#3324)

  • Add method argument to session.ws_connect().

    Sometimes server API requires a different HTTP method for WebSocket connection establishment.

    For example, Docker exec needs POST. (#3378)

  • Create a task per request handling. (#3406)


  • Enable passing access_log_class via handler_args (#3158)

  • Return empty bytes with end-of-chunk marker in empty stream reader. (#3186)

  • Accept CIMultiDictProxy instances for headers argument in web.Response constructor. (#3207)

  • Don’t uppercase HTTP method in parser (#3233)

  • Make method match regexp RFC-7230 compliant (#3235)

  • Add app.pre_frozen state to properly handle startup signals in sub-applications. (#3237)

  • Enhanced parsing and validation of helpers.BasicAuth.decode. (#3239)

  • Change imports from collections module in preparation for 3.8. (#3258)

  • Ensure Host header is added first to ClientRequest to better replicate browser (#3265)

  • Fix forward compatibility with Python 3.8: importing ABCs directly from the collections module will not be supported anymore. (#3273)

  • Keep the query string by normalize_path_middleware. (#3278)

  • Fix missing parameter raise_for_status for aiohttp.request() (#3290)

  • Bracket IPv6 addresses in the HOST header (#3304)

  • Fix default message for server ping and pong frames. (#3308)

  • Fix tests/ typo and tests/autobahn/ duplicate loop def. (#3337)

  • Fix false-negative indicator end_of_HTTP_chunk in StreamReader.readchunk function (#3361)

  • Release HTTP response before raising status exception (#3364)

  • Fix task cancellation when sendfile() syscall is used by static file handling. (#3383)

  • Fix stack trace for asyncio.TimeoutError which was not logged, when it is caught in the handler. (#3414)

Improved Documentation

  • Improve documentation of Application.make_handler parameters. (#3152)

  • Fix BaseRequest.raw_headers doc. (#3215)

  • Fix typo in TypeError exception reason in web.Application._handle (#3229)

  • Make server access log format placeholder %b documentation reflect behavior and docstring. (#3307)

Deprecations and Removals

  • Deprecate modification of session.requote_redirect_url (#2278)

  • Deprecate stream.unread_data() (#3260)

  • Deprecated use of boolean in resp.enable_compression() (#3318)

  • Encourage creation of aiohttp public objects inside a coroutine (#3331)

  • Drop dead Connection.detach() and Connection.writer. Both methods were broken for more than 2 years. (#3358)

  • Deprecate app.loop, request.loop, client.loop and connector.loop properties. (#3374)

  • Deprecate explicit debug argument. Use asyncio debug mode instead. (#3381)

  • Deprecate body parameter in HTTPException (and derived classes) constructor. (#3385)

  • Deprecate bare connector close, use async with connector: and await connector.close() instead. (#3417)

  • Deprecate obsolete read_timeout and conn_timeout in ClientSession constructor. (#3438)


  • #3341, #3351

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aiohttp-3.6.1.tar.gz (1.1 MB view hashes)

Uploaded Source

Built Distributions

aiohttp-3.6.1-cp37-cp37m-win_amd64.whl (617.7 kB view hashes)

Uploaded CPython 3.7m Windows x86-64

aiohttp-3.6.1-cp37-cp37m-win32.whl (590.0 kB view hashes)

Uploaded CPython 3.7m Windows x86

aiohttp-3.6.1-cp37-cp37m-manylinux1_x86_64.whl (1.2 MB view hashes)

Uploaded CPython 3.7m

aiohttp-3.6.1-cp37-cp37m-manylinux1_i686.whl (1.1 MB view hashes)

Uploaded CPython 3.7m

aiohttp-3.6.1-cp36-cp36m-win_amd64.whl (617.6 kB view hashes)

Uploaded CPython 3.6m Windows x86-64

aiohttp-3.6.1-cp36-cp36m-win32.whl (589.9 kB view hashes)

Uploaded CPython 3.6m Windows x86

aiohttp-3.6.1-cp36-cp36m-manylinux1_x86_64.whl (1.2 MB view hashes)

Uploaded CPython 3.6m

aiohttp-3.6.1-cp36-cp36m-manylinux1_i686.whl (1.1 MB view hashes)

Uploaded CPython 3.6m

aiohttp-3.6.1-cp35-cp35m-win_amd64.whl (612.0 kB view hashes)

Uploaded CPython 3.5m Windows x86-64

aiohttp-3.6.1-cp35-cp35m-win32.whl (584.0 kB view hashes)

Uploaded CPython 3.5m Windows x86

aiohttp-3.6.1-cp35-cp35m-manylinux1_x86_64.whl (1.1 MB view hashes)

Uploaded CPython 3.5m

aiohttp-3.6.1-cp35-cp35m-manylinux1_i686.whl (1.1 MB view hashes)

Uploaded CPython 3.5m

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page