aiodocker is an Apache-2.0 Python library that wraps the Docker HTTP API with asyncio and aiohttp, aimed at Python developers and platform engineers who need to drive Docker from asynchronous application code rather than from the shell, from a subprocess, or from a synchronous client.

What it is

aiodocker is a simple Docker HTTP API wrapper written with asyncio and aiohttp, published on PyPI as aiodocker and maintained under the aio-libs organisation. It lives in the Python ecosystem and speaks directly to the Docker daemon over Docker's HTTP API, exposing that API as awaitable Python methods. Instances are created with aiodocker.Docker() inside an async context, used with await, and released with await docker.close(). The library carries the topics asyncio, aiohttp, docker, api-client, and python.

The concrete problem it solves is the mismatch between Docker's blocking client interface and event-loop-based Python services. A web service, task worker, or orchestrator that already runs on asyncio cannot call a synchronous Docker client without blocking the loop or pushing the work into a thread pool. aiodocker replaces that blocking call path with native coroutines, so listing images, creating containers, streaming logs, and deleting containers all compose with the rest of an async application. It also replaces ad-hoc subprocess calls to the docker CLI, giving structured responses from the daemon instead of parsed command output.

Key capabilities

• Asynchronous client construction and teardown via aiodocker.Docker() and await docker.close().
• Image listing through await docker.images.list(), returning entries with Id and RepoTags fields.
• Container listing through await docker.containers.list().
• Idempotent container creation with await docker.containers.create_or_replace(config={...}, name=...), where config carries Docker API fields such as Cmd and Image.
• Lifecycle control with await container.start() and await container.delete(force=True).
• Log retrieval as an awaitable stream with await container.log(stdout=True).
• Standard asyncio.run(main()) entry point, so the client drops into ordinary asyncio programs.
• Development tooling built around uv, the committed uv.lock, pre-commit hooks, and Makefile targets (make develop, make install, make lint, make test).

Who uses it and how

• Python services that already run an asyncio event loop and need to start, inspect, or stop containers without blocking that loop.
• Backend and platform teams automating container lifecycle from application code, for example creating a container from alpine:latest, running a command, reading its logs, and deleting it in one async flow.
• CI and test harnesses that spin containers up and down programmatically; the project's own suite is run with make test or targeted with uv run pytest tests/test_images.py.
• Developers building internal tooling or dashboards that list images and containers on a host and need structured data rather than docker CLI text output.
• Contributors and maintainers, who work from the uv-managed environment with uv sync --extra dev --extra lint --extra test --extra doc and build artifacts with uv build.

Getting started

Install from PyPI with pip install aiodocker, then follow the examples and API documentation at http://aiodocker.readthedocs.io. For development work, the recommended path is uv sync --extra dev --extra lint --extra test --extra doc followed by uv run pre-commit install; a pip install -e '.[dev,lint,test,doc]' fallback exists but is not pinned to uv.lock.

How it compares

The provided facts list no paid or commercial products that aiodocker replaces, and they name no directly comparable client library. Within this registry it stands alone: it is the entry that pairs the Docker HTTP API with asyncio and aiohttp specifically.

When to use it — and when not to

A self-hoster or adopter must run a reachable Docker daemon and grant the calling process access to it, which in practice usually means socket access or equivalent privileges; the library itself ships no server, storage, database, or mail component to operate. Teams that are not already committed to asyncio, or that prefer the synchronous Docker client or the docker CLI, should not adopt it, because the await-based surface adds friction without removing the dependency on Docker's own API. The README is deliberately short and defers the real API surface to external Read the Docs pages, so its examples cover only image listing, container listing, create-or-replace, start, log, and delete; with 28 open issues and its most recent push on 2026-09-01, expect to consult the upstream Docker HTTP API documentation to use parts of the client the README never demonstrates.

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.

.. code-block:: sh

   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
~~~~~~~~~~~~~

.. code-block:: sh

   # 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.

.. code-block:: sh

   uv build


Documentation
==============

http://aiodocker.readthedocs.io


Examples
=========

.. code-block:: python

    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())