aiodocker

aiodocker is a Python client for the Docker Engine API written with asyncio and aiohttp. It wraps the Docker daemon’s HTTP interface in awaitable methods for containers, images, networks, volumes, secrets, configs, services, and Swarm, plus streaming endpoints for logs, events, and exec sessions. It is maintained under the aio-libs organization and ships type hints (py.typed).

What You Get

• An async Docker client that connects over UNIX socket, TCP, or SSH
• Awaitable resource APIs for containers, images, networks, volumes, secrets, configs, and Swarm services
• Streaming helpers for container logs, daemon events, exec sessions, and attach channels
• Bundled type hints (py.typed) for editor autocompletion and static checking

Common Use Cases

• Orchestrating containers from async web services or background workers
• Building CI/CD and test harnesses that spin Docker containers up and down
• Streaming live container logs and daemon events into monitoring pipelines

Under The Hood

Architecture — The package centers on docker.py, whose Docker class holds an aiohttp session and a connector that resolves the transport (UNIX socket, TCP, or SSH). Resource modules — containers.py, images.py, networks.py, volumes.py, services.py, swarm.py, secrets.py, configs.py, nodes.py, tasks.py, system.py — expose collection and object wrappers that issue requests through that session. Streaming concerns live in stream.py, multiplexed.py, jsonstream.py, and channel.py, backed by a vendored _flow_control_queue.py for backpressure.

Tech Stack — Python 3.10+ built with hatchling and hatch-vcs. The single runtime dependency is aiohttp>=3.11.13,<4.0; optional ssh extras add asyncssh and paramiko. Dev tooling uses ruff, mypy, pytest, and towncrier for changelog fragments.

Code Quality — The codebase is typed end to end (py.typed, mypy in CI) and has an extensive pytest suite under tests/ covering containers, images, execs, events, networks, and Swarm, including a docker-in-docker compose setup. Dependency bounds are documented inline with the reasoning behind each pin.

API Design — The client mirrors Docker’s own resource model, so docker.containers.create(...), .images.pull(...), and streaming a container’s logs read naturally to anyone who knows the Docker CLI. Streaming endpoints return async iterators, keeping long-lived log and event consumption idiomatic in asyncio.