AsyncIO bindings for docker.io

GitHub Actions status for the main branch

A simple Docker HTTP API wrapper written with asyncio and aiohttp.

Installation

pip install aiodocker

Development

The recommended developer setup uses uv, which manages the virtualenv and resolves dependencies from the committed uv.lock so every contributor and CI job builds against the same versions.

# Install uv first: https://docs.astral.sh/uv/getting-started/installation/
uv sync --extra dev --extra lint --extra test --extra doc
uv run pre-commit install

The Makefile helpers (make develop, make install, make lint, make test) all assume uv.

Using pip instead (fallback)

If you can't install uv, you can still bootstrap with pip. The resulting environment isn't pinned to uv.lock, so versions may drift from CI.

python -m venv .venv && source .venv/bin/activate
pip install -U pip
pip install -e '.[dev,lint,test,doc]'  # in zsh, you need to escape brackets
pre-commit install

Running tests

# Run all tests
make test
# Run individual tests
uv run pytest tests/test_images.py

Building packages

NOTE: Usually you don't need to run this step by yourself.

uv build

Documentation

http://aiodocker.readthedocs.io

Examples

import asyncio
import aiodocker
async def list_things(docker):
    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}")
async def run_container(docker):
    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)
async def main():
    docker = aiodocker.Docker()
    await list_things(docker)
    await run_container(docker)
    await docker.close()
if __name__ == "__main__":
    asyncio.run(main())