Install & Compatibility
Where this runs
tested against v0.27.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.654s · 27.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.574s · 30MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Docker
✓ from aiodocker import Docker
DockerError
✓ from aiodocker.exceptions import DockerError
✗ from aiodocker import DockerError
DockerError is part of the exceptions submodule, not directly under aiodocker.
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())
Debug
Known issues
breakingVersion 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.fixUpgrade Python to 3.10 or newer and ensure `aiohttp` >= 3.10 and `async-timeout` >= 5.0. Pin these versions in your project dependencies.
affects: 0.25.0 and later
breakingIn 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`.fixReview 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.
affects: 0.25.0 and later
breakingThe method `docker.images.get` was renamed to `docker.images.inspect` and support for Docker API version 17.06 was removed in older versions.fixUpdate calls from `docker.images.get(...)` to `docker.images.inspect(...)`.
affects: 0.15.0 and later (initial change), 0.25.0 and later (further cleanup)
gotchaUnlike `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.fixCatch `aiodocker.exceptions.DockerError` and check `if err.status == 404:` to specifically handle 'Not Found' errors.
affects: All versions
gotchaSetting 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.fixMigrate from passing `timeout` as a float directly to API calls to using `asyncio.timeout()` for managing the overall execution time of your asynchronous operations.
affects: 0.25.0 and later
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aiodocker'
The 'aiodocker' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install aiodocker'.
AttributeError: module 'aiodocker' has no attribute 'DockerContainers'
The 'DockerContainers' class does not exist in the 'aiodocker' module.
fixUse 'docker.containers' instead of 'DockerContainers'.
AttributeError: 'Docker' object has no attribute 'containers'
The 'Docker' object does not have a 'containers' attribute.
fixEnsure you are using the correct version of 'aiodocker' and refer to the latest documentation for the correct usage.
TypeError: 'Docker' object is not callable
Attempting to call the 'Docker' class as a function.
fixInstantiate the 'Docker' class correctly: 'docker = aiodocker.Docker()'.
RuntimeError: Event loop is closed
The asyncio event loop has been closed before the asynchronous operation could complete.
fixEnsure the event loop is running when performing asynchronous operations, and avoid closing it prematurely.
Upgrade
Version history
0.27.0latest on PyPI · released May 27, 2026
Audit
Dependencies
aiohttprequiredCore dependency for asynchronous HTTP requests, minimum 3.10 since aiodocker 0.25.0.
async-timeoutrequiredUsed for managing request timeouts, minimum 5.0 since aiodocker 0.25.0.