Aiodocker

0.26.0 verified Fri Apr 24 auth: no python

Aiodocker is a Python library providing an asynchronous HTTP API wrapper for Docker, built upon `asyncio` and `aiohttp`. It allows programmatic interaction with Docker daemons from Python applications. Currently at version 0.26.0, the library is under active development with regular releases, ensuring compatibility with recent Docker API versions and Python features.

pip install aiodocker

Common errors

error ModuleNotFoundError: No module named 'aiodocker' ↓

cause The 'aiodocker' package is not installed in the Python environment.

fix

Install the package using pip: 'pip install aiodocker'.

error AttributeError: module 'aiodocker' has no attribute 'DockerContainers' ↓

cause The 'DockerContainers' class does not exist in the 'aiodocker' module.

fix

Use 'docker.containers' instead of 'DockerContainers'.

error AttributeError: 'Docker' object has no attribute 'containers' ↓

cause The 'Docker' object does not have a 'containers' attribute.

fix

Ensure you are using the correct version of 'aiodocker' and refer to the latest documentation for the correct usage.

error TypeError: 'Docker' object is not callable ↓

cause Attempting to call the 'Docker' class as a function.

fix

Instantiate the 'Docker' class correctly: 'docker = aiodocker.Docker()'.

error RuntimeError: Event loop is closed ↓

cause The asyncio event loop has been closed before the asynchronous operation could complete.

fix

Ensure the event loop is running when performing asynchronous operations, and avoid closing it prematurely.

Warnings

breaking Version 0.25.0 dropped support for Python 3.9. It now requires Python >= 3.10. Additionally, it updated minimum dependencies for `aiohttp` to 3.10 and `async-timeout` to 5.0. ↓

fix Upgrade Python to 3.10 or newer and ensure `aiohttp` >= 3.10 and `async-timeout` >= 5.0. Pin these versions in your project dependencies.

breaking In version 0.25.0, `DockerContainer.{stop, restart, kill, delete}()` methods replaced `**kwargs` with explicit parameters. Specifically, the server-side stop timeout is now `t` and the client-side request timeout is `timeout`. If you were passing `timeout` for server-side behavior, it must now be `t`. ↓

fix Review calls to these methods and replace `timeout=...` with `t=...` if you intended to set the server-side stop timeout. Use `timeout=...` for the client-side request timeout.

breaking The method `docker.images.get` was renamed to `docker.images.inspect` and support for Docker API version 17.06 was removed in older versions. ↓

fix Update calls from `docker.images.get(...)` to `docker.images.inspect(...)`.

gotcha Unlike `docker-py`, `aiodocker` raises a generic `aiodocker.exceptions.DockerError` for 'Not Found' scenarios (e.g., image or container not existing). To check for a 'Not Found' error, you must inspect the `status` attribute of the exception. ↓

fix Catch `aiodocker.exceptions.DockerError` and check `if err.status == 404:` to specifically handle 'Not Found' errors.

gotcha Setting individual float timeouts per-API call is highly discouraged starting from version 0.25.0. The recommended approach for managing timeouts is via Python's standard library `asyncio.timeout()` async context manager, for better composability and consistency. ↓

fix Migrate from passing `timeout` as a float directly to API calls to using `asyncio.timeout()` for managing the overall execution time of your asynchronous operations.

Install compatibility last tested: 2026-04-24

runtime status import time mem disk

3.10-alpine 0.64s 15.2MB 27.8M

3.10-slim 0.56s 15.2MB 30M

3.11-alpine 0.96s 16.4MB 30.5M

3.11-slim 0.79s 16.4MB 33M

3.12-alpine 1.11s 16.8MB 22.4M

3.12-slim 1.13s 16.8MB 25M

3.13-alpine 1.06s 17.1MB 21.6M

3.13-slim 1.21s 17.1MB 24M

3.9-alpine 0.57s 14.0MB 27.6M

3.9-slim 0.56s 14.0MB 30M

Imports

Docker
```
from aiodocker import Docker
```
DockerError
wrong
```
from aiodocker import DockerError
```
correct
```
from aiodocker.exceptions import DockerError
```
DockerError is part of the exceptions submodule, not directly under aiodocker.

Quickstart last tested: 2026-04-25

This quickstart demonstrates how to initialize the Docker client, list existing images and containers, run a 'hello-world' container, capture its logs, and then clean it up. It showcases basic asynchronous operations with the Docker API.

import asyncio
import aiodocker

async def list_and_run_containers():
    docker = aiodocker.Docker()
    try:
        print('== Images ==')
        for image in (await docker.images.list()):
            tags = image['RepoTags'][0] if image['RepoTags'] else ''
            print(image['Id'], tags)

        print('== Containers ==')
        for container in (await docker.containers.list()):
            print(f"  {container._id}")

        print('== Running a hello-world container ==')
        container = await docker.containers.create_or_replace(
            config={
                'Cmd': ['/bin/ash', '-c', 'echo "hello world"'],
                'Image': 'alpine:latest',
            },
            name='testing',
        )
        await container.start()
        logs = await container.log(stdout=True)
        print(''.join(logs))
        await container.delete(force=True)
    finally:
        await docker.close()

if __name__ == "__main__":
    asyncio.run(list_and_run_containers())