Docker SDK for Python — Programmatic Docker Engine Control

Introduction

The Docker SDK for Python (formerly docker-py) is the official Python library for interacting with the Docker Engine API. It lets you manage containers, images, volumes, networks, and swarm services from Python code with the same capabilities as the Docker CLI.

What Docker SDK for Python Does

• Creates, starts, stops, and removes Docker containers programmatically
• Builds, pulls, pushes, and tags Docker images from Python scripts
• Manages Docker networks, volumes, secrets, and configs via a high-level API
• Streams container logs and exec output in real time
• Supports Docker Swarm service management including scaling and rolling updates

Architecture Overview

The SDK wraps the Docker Engine REST API with two abstraction layers. The low-level APIClient maps directly to API endpoints with minimal transformation. The high-level DockerClient provides Pythonic resource objects (Container, Image, Network) with methods and attributes. Communication uses Unix sockets by default or TCP with optional TLS for remote Docker hosts.

Self-Hosting & Configuration

• Install from PyPI: pip install docker
• Connect to the local Docker daemon with docker.from_env() which reads DOCKER_HOST and related environment variables
• For remote hosts, pass base_url and optional TLS configuration to docker.DockerClient()
• Authentication for registries uses client.login() or reads credentials from ~/.docker/config.json
• Supports both synchronous operations and streaming responses for logs and build output

Key Features

• Full coverage of the Docker Engine API including containers, images, networks, volumes, and swarm
• High-level Pythonic interface with resource objects that support attribute access and method chaining
• Streaming support for build output, container logs, and exec commands
• TLS client authentication for secure remote Docker host connections
• Maintained by Docker, Inc. as the official Python SDK with consistent API parity

Comparison with Similar Tools

• Docker CLI — Command-line interface for Docker; the SDK provides the same operations for programmatic use
• docker-compose (Python) — Orchestrates multi-container apps from YAML; the SDK offers lower-level, per-container control
• Podman Python bindings — Similar API for Podman; the Docker SDK is Docker-specific with broader ecosystem support
• testcontainers-python — Testing library built on top of docker-py for disposable test containers
• dockerode — Node.js Docker client; the Docker SDK is the Python equivalent with official Docker backing

FAQ

Q: Does the SDK support Docker Compose files? A: The SDK does not parse Compose files directly. Use the docker compose CLI or the Compose Python library for multi-service orchestration.

Q: Can I connect to a remote Docker daemon? A: Yes. Pass base_url="tcp://remote-host:2376" and a TLSConfig object to DockerClient() for secure remote connections.

Q: How do I stream container logs? A: Call container.logs(stream=True) to get a generator that yields log lines as they arrive.

Q: Is the SDK compatible with Podman? A: Podman's Docker-compatible API socket works with many SDK operations, though some advanced Docker-specific features may not be available.

Sources

• https://github.com/docker/docker-py
• https://docker-py.readthedocs.io/