Running Asyncio Web Apps with aiohttp in Docker

Mar 3, 2024 ยท 2 min read

Docker provides a great way to containerize Python web applications like those built with aiohttp. However, there are some specific considerations when running asyncio apps in Docker that are worth covering.

Choosing the Right Base Image

Since aiohttp relies on asyncio, you'll want to use a Python base image that has support for asyncio. The smaller Python base images like python:3.7-alpine don't include some necessary libraries for asyncio. The full Python images like python:3.7 or python:3.7-slim are better choices.

FROM python:3.7-slim

Installing Dependencies

Use pip to install aiohttp and other app dependencies. Make sure to also install uvloop which is a faster asyncio event loop implementation.

RUN pip install aiohttp uvloop

Configuring Number of Workers

By default, the number of asyncio worker processes will be based on the number of CPU cores available. This can lead to too many workers when running in Docker with limited cores. Set the environment variable AIOHTTP_WORKERS to configure the workers explicitly.


Avoiding Port Collisions

If you scale up the number of containers, you can run into issues with port collisions on the host machine. Map to a dynamic port instead with 0:


And then get the assigned port at runtime.

Graceful Shutdowns

Handle SIGTERM signals to trigger a graceful shutdown and finalize requests properly.

In summary, running aiohttp web apps in Docker introduces some special considerations but is very achievable with the right base image, dependencies, and config. Focus on limiting workers, dynamic ports, and graceful shutdowns.

Browse by tags:

Browse by language:

The easiest way to do Web Scraping

Get HTML from any page with a simple API call. We handle proxy rotation, browser identities, automatic retries, CAPTCHAs, JavaScript rendering, etc automatically for you

Try ProxiesAPI for free

curl ""

<!doctype html>
    <title>Example Domain</title>
    <meta charset="utf-8" />
    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />


Don't leave just yet!

Enter your email below to claim your free API key: