Docker SDK for Python: Control Containers from Code

Why calling docker from Python beats subprocess

A shell script that runs containers might invoke the shell with string commands. From Python, you could use the subprocess module with that string, but you lose type safety, error handling becomes ad-hoc, and your code reads like a template. The Docker SDK for Python maps the daemon API directly: you import the library and call methods on container and image objects. Each call returns structured objects with methods for streaming logs, stopping containers, and cleaning up resources. Code that orchestrates containers becomes readable, testable, and debuggable as regular Python. This matters when you control dozens of containers or need to handle failures gracefully.

How the SDK connects to Docker and runs a first container

Install the library from PyPI:

pip install docker

Connect to the Docker daemon using the default socket:

import docker
client = docker.from_env()

The client reads DOCKER_HOST, DOCKER_CERT_PATH and similar environment variables, following the same conventions as the Docker command-line tool.

Once connected, you can run a container and capture its output. The call pulls the image if it is not present, runs the container, waits for it to exit, and returns stdout. For background work, you can pass detach=True. The call returns a Container object that you can fetch by ID, stream its logs, or stop at any time.

Container and image operations without subprocesses

List all running containers by iterating over a container collection. Fetch a specific container by its ID. Stream logs line-by-line from a running or stopped container. Manage images by pulling them from a registry, listing what is installed, or building new ones from a Dockerfile.

Each operation has a return value, not text output. You build conditional logic around the result: if a container fails, you know immediately from an exception, not from parsing stderr. If you need an image's ID, you get a Python string, not a line of text to parse. Control flow becomes explicit and testable, not hidden in string matching.

SSH connections and TLS, without configuration files

By default, the SDK uses the local socket. To connect over SSH, set the DOCKER_HOST environment variable to an SSH URL before calling the library. SSH connections require the optional paramiko dependency, which can be installed separately or as an extra with the docker package.

TLS connections (to a remote Docker daemon) are built into the urllib3 dependency and require no extra install. The SDK reads DOCKER_CERT_PATH and DOCKER_TLS_VERIFY from the environment, following the same conventions as the Docker command-line tool. This means you can often drop a Python script into an existing Docker workflow without new credential management.

What the SDK does not automate and when you reach API limits

The SDK wraps the Docker daemon API, which means anything the daemon does not expose, the SDK cannot do. Dockerfile syntax is not exposed as Python objects; you pass a Dockerfile path and the daemon handles the rest. Container networking beyond bridge mode requires the networks API, which the SDK exposes but does not simplify. Swarm orchestration and service management are documented in the API but rarely used. If your use case involves deep configuration of networking policies or service constraints, you will spend time reading the Docker API docs to understand what arguments to pass, rather than discovering them through method signatures.

Development status and compatibility

The latest release is 7.2.0 (July 2026). The library is marked as stable. The last push to GitHub was September 22, seven days ago. It supports Python 3.8 through 3.12. The codebase has 564 open issues, some dating back years, so not every reported problem gets a fix. The maintainers are responsive to pull requests and security issues but move slowly on feature requests. If you need a feature that is not in the API yet, you can call the HTTP endpoint directly via the lower-level API, but that is undocumented and fragile across versions.

When to choose docker-py over the CLI

Use the SDK when you are building tools that orchestrate containers: deployment systems, testing frameworks, CI pipelines, or any application that needs to manage containers as a feature. The SDK excels when you control many containers, handle errors programmatically, or pass structured data between operations. The CLI is faster for one-off commands and exploration. A hybrid approach is common: use the CLI for operations, the SDK for automation. The SDK depends on requests and urllib3; if your environment already has those for HTTP calls, the overhead is negligible. If you are starting a new project, the SDK trades typing convenience for less friction than subprocess calls.

Editorial conclusion

Docker SDK for Python is for teams building deployment automation, infrastructure tools, or any system that needs to control containers programmatically. Skip it if your workflow is CLI-driven and simple shell scripts suffice. Start by reading the README examples, then adapt one to your use case. The API is stable but occasionally grows new methods, so read the release notes before upgrading in production.

Frequently asked questions

Official sources

1. docker/docker-py on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases