docker-py

Docker SDK for Python (published to PyPI as docker) is the official client library for the Docker Engine API, maintained by Docker Inc. It provides two complementary interfaces: a high-level, Pythonic object model (DockerClient) for everyday container, image, network, and volume operations, and a low-level APIClient that mirrors the full Docker Engine REST API for cases needing complete control.

The library handles the transport details of talking to a Docker daemon over a Unix socket, TCP, SSH, or Windows named pipe, plus TLS negotiation, streaming logs/attach sockets, and Swarm-mode orchestration (services, secrets, configs, nodes). It’s the library that powers higher-level developer tools and CI pipelines that need to drive Docker programmatically instead of shelling out to the docker CLI.

What You Get

• High-level DockerClient object model for containers, images, networks, and volumes with Pythonic collections (client.containers.run(...), client.images.pull(...))
• Low-level APIClient exposing the complete Docker Engine REST API for advanced or unsupported operations
• Built-in transport support for Unix sockets, TCP, SSH (use_ssh_client), and Windows named pipes, plus TLS configuration via TLSConfig
• Swarm-mode primitives — services, secrets, configs, and nodes — for managing multi-node Docker clusters
• Streaming support for container logs, attach, and exec output via socket demuxing helpers

Common Use Cases

• Programmatically building and running containers from CI/CD pipelines or test harnesses
• Writing developer tooling (like Compose-style orchestrators) on top of the Docker Engine API
• Automating image builds and pushes as part of a Python-based release process
• Managing Swarm services, secrets, and configs from infrastructure automation scripts

Under The Hood

Architecture docker-py splits its surface into two layers: a low-level APIClient (docker/api/client.py) built as a requests.Session subclass composed from a dozen *ApiMixin classes (build, container, image, network, volume, service, swarm, secret, config, plugin, exec, daemon) that each contribute one slice of the Docker Engine REST surface, and a high-level DockerClient (docker/client.py) that wraps an APIClient instance and exposes typed collections (ContainerCollection, ImageCollection, etc.) built on a shared Model/Collection base (docker/models/resource.py). Models are lazy, cached wrappers around the daemon’s raw JSON responses — reload() re-fetches attrs from the collection — so mutating operations like container.stop() delegate straight back down to the corresponding APIClient method. Transport selection (Unix socket, TCP, SSH, Windows named pipe) is resolved through pluggable HTTPAdapter subclasses (UnixHTTPAdapter, SSHHTTPAdapter, NpipeHTTPAdapter) registered onto the requests.Session, keeping the wire-transport concern fully decoupled from the API-mixin layer above it.

Tech Stack The library targets Python 3.8+, uses requests and urllib3 as its sole hard HTTP dependencies, and builds with hatchling/hatch-vcs (version derived from git tags into docker/_version.py) rather than a hand-maintained version string. Optional extras are cleanly isolated: paramiko for SSH transport, websocket-client for a websocket-based attach mechanism, and pywin32 only on Windows. Linting is enforced with ruff, tests run under pytest with pytest-cov/pytest-timeout, and CI (GitHub Actions) runs lint plus unit and Docker-in-Docker integration jobs. Documentation is built with Sphinx and published to ReadTheDocs.

Code Quality Test coverage is extensive — separate tests/unit and tests/integration suites (each several thousand lines) plus a dedicated tests/ssh suite, backed by fake_api_client/fake_api fixtures that stub Engine API responses for isolated unit testing. Error handling is centralized through a DockerException base class with specific subclasses (APIError, NotFound, ImageNotFound, BuildError, ContextNotFound, and others) rather than leaking raw requests exceptions, and create_api_error_from_http_exception maps HTTP status codes and response bodies to the right exception type. The codebase does not use static type hints or mypy, relying instead on docstrings and the extensive test suite for correctness; ruff enforces style consistency across both the library and its tests.

API Design The dual-client design is the standout ergonomic choice: newcomers can call docker.from_env() and immediately work with a Pythonic object model (client.containers.run(...), client.images.pull(...)), while power users who need Engine API parity drop to client.api (the underlying APIClient) without switching libraries. Naming closely mirrors the docker CLI and Engine API vocabulary (containers, images, networks, volumes, services, secrets, configs), which minimizes the mental translation for anyone who already knows Docker. Documentation is thorough — every public method carries a docstring covering parameters and examples, and the Sphinx docs on ReadTheDocs mirror the object model one-to-one — though the lack of type hints means IDEs can’t autocomplete method signatures as precisely as a typed alternative would.