Python Docker SDK

7.1.0 verified Tue May 12 auth: no python install: verified quickstart: stale

The Python Docker SDK (formerly docker-py) is a Python client for the Docker Engine API. It allows you to build, run, and manage Docker containers, images, networks, and volumes programmatically. The current version is 7.1.0, and the library is actively maintained with frequent patch and minor releases.

pip install docker

Common errors

error docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory')) ↓

cause The Python Docker SDK client cannot connect to the Docker daemon, often because the daemon is not running, the client lacks proper permissions, or the DOCKER_HOST environment variable is misconfigured.

fix

Ensure Docker Desktop or Docker Engine is running and accessible. On Linux, check if the Docker service is active (sudo systemctl status docker) and if your user is in the docker group (sudo usermod -aG docker $USER && newgrp docker). For macOS/Windows, confirm Docker Desktop is running. Sometimes, restarting Docker Desktop or setting the DOCKER_HOST environment variable explicitly can help.

error ModuleNotFoundError: No module named 'docker' ↓

cause The `docker` Python package is either not installed in the active Python environment or is installed incorrectly, or there's a script named `docker.py` shadowing the actual library.

fix

Install the correct package using pip install docker. If already installed, ensure your Python environment's PATH includes the directory where packages are installed. Avoid naming your script file docker.py to prevent conflicts.

error AttributeError: 'function' object has no attribute 'run' ↓

cause This error typically occurs when using an older API style (e.g., `client.containers()`) from `docker-py` with the newer object-oriented API of the `docker` SDK, where `client.containers` is a collection object, not a function.

fix

Access container methods directly from the client.containers collection. For instance, replace client.containers().run(...) with client.containers.run(...) and client.containers().list() with client.containers.list(). Ensure you are using the docker package (the successor to docker-py).

error docker.errors.APIError: 404 Client Error: Not Found ("No such image: <image_name>" or "No such container: <container_id/name>") ↓

cause The Docker daemon could not find the specified image or container. This happens if the image or container name/ID is incorrect, has been deleted, or never existed.

fix

Verify that the image name (including tag, e.g., ubuntu:latest) or container name/ID is correct and that the resource actually exists on the Docker daemon. Use docker images or docker ps -a in your terminal to list available resources.

error ERROR: Could not find a version that satisfies the requirement <package>==<version> (from versions: none) ERROR: No matching distribution found for <package>==<version> ↓

cause This error occurs during a `pip install` command within a Docker image build when a specified Python package version is not available for the base Python image's OS and Python version, or there are network/proxy issues preventing access to PyPI.

fix

Check the Python version compatibility of the package. Try removing the version constraint (<package>) or using a more general constraint. Ensure the base image has necessary build tools if the package requires compilation. Check for network connectivity or proxy configuration issues within the Dockerfile's build environment.

Warnings

breaking The `ssl_version` and `assert_hostname` options were removed from `DockerClient` and `APIClient` initialization. ↓

fix Remove these arguments from your client initialization code. Python 3.7+ supports TLSv1.3 by default, and `assert_hostname` has not been used since Python 3.6.

breaking Websocket support is no longer included by default and requires an extra installation. ↓

fix If you rely on WebSocket functionality (e.g., for streaming `exec_run` output), you must install `docker` with the `websockets` extra: `pip install docker[websockets]`.

breaking The minimum and default Docker Engine API versions have been bumped. ↓

fix Ensure your Docker daemon is at least API version 1.24 (Docker Engine 1.12.0) for `docker-py` 7.1.0+ compatibility. For full compatibility, an API version of 1.44 (Moby 25.0) or higher is recommended. If you need to connect to older Docker Engines, you may need to pin an earlier version of `docker-py`.

gotcha Older versions of `docker-py` (specifically 6.0.x) had incompatibilities with newer `requests` (2.29+) or `urllib3` (2.x) versions. ↓

fix Upgrade `docker-py` to 6.1.0+ or 7.x (recommended) to ensure compatibility. If an upgrade is not possible, pin `requests < 2.29` and `urllib3 < 2` in your project dependencies.

gotcha `KeyError` when creating new configs (`ConfigCollection`) due to missing `name` field. ↓

fix Upgrade `docker-py` to version 7.1.0 or later, as this issue was fixed.

Install

pip install docker[websockets]

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) ssh - - 1.19s 45.5M

3.10 alpine (musl) docker - - 0.63s 22.4M

3.10 alpine (musl) websockets - - 0.61s 23.1M

3.10 slim (glibc) ssh - - 0.85s 46M

3.10 slim (glibc) docker - - 0.45s 23M

3.10 slim (glibc) websockets - - 0.45s 24M

3.11 alpine (musl) ssh - - 1.67s 48.6M

3.11 alpine (musl) docker - - 0.84s 24.6M

3.11 alpine (musl) websockets - - 0.79s 25.5M

3.11 slim (glibc) ssh - - 1.28s 49M

3.11 slim (glibc) docker - - 0.74s 25M

3.11 slim (glibc) websockets - - 0.71s 26M

3.12 alpine (musl) ssh - - 1.82s 40.2M

3.12 alpine (musl) docker - - 0.74s 16.4M

3.12 alpine (musl) websockets - - 0.70s 17.2M

3.12 slim (glibc) ssh - - 1.76s 40M

3.12 slim (glibc) docker - - 0.76s 17M

3.12 slim (glibc) websockets - - 0.73s 18M

3.13 alpine (musl) ssh - - 1.79s 39.8M

3.13 alpine (musl) docker - - 0.74s 16.0M

3.13 alpine (musl) websockets - - 0.70s 16.9M

3.13 slim (glibc) ssh - - 1.76s 40M

3.13 slim (glibc) docker - - 0.71s 16M

3.13 slim (glibc) websockets - - 0.70s 17M

3.9 alpine (musl) ssh - - 1.16s 45.6M

3.9 alpine (musl) docker - - 0.57s 21.7M

3.9 alpine (musl) websockets - - 0.56s 22.4M

3.9 slim (glibc) ssh - - 0.96s 46M

3.9 slim (glibc) docker - - 0.52s 22M

3.9 slim (glibc) websockets - - 0.50s 23M

Imports

from_env
wrong
```
import docker
client = docker.Client()
```
correct
```
import docker
client = docker.from_env()
```
docker.Client() was the old API entry point and is deprecated. Use docker.from_env() for convenience or docker.DockerClient() for explicit client creation.

DockerClient

from docker import DockerClient
client = DockerClient(base_url='unix://var/run/docker.sock')

Use this for explicit client configuration.

APIClient

from docker import APIClient
client = APIClient(base_url='unix://var/run/docker.sock')

For lower-level access to the Docker Engine API.

errors

from docker import errors
try:
    # ...
except errors.DockerException as e:
    # handle exception

All Docker-specific exceptions are under the 'errors' module.

Quickstart stale last tested: 2026-04-23

This quickstart demonstrates how to connect to the Docker daemon using environment variables or default socket paths, verify the connection, list running containers, and run a simple 'hello-world' container. It includes basic error handling for connection issues.

import docker
import os

# Connect to the Docker daemon
# docker-py automatically uses DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH
# environment variables if available, or falls back to default sockets.
client = docker.from_env()

# Verify the connection
try:
    client.ping()
    print("Successfully connected to Docker daemon.")
except docker.errors.DockerException as e:
    print(f"Error connecting to Docker: {e}")
    print("Please ensure Docker is running and accessible (e.g., Docker Desktop or daemon started).")
    exit(1)

# List all running containers
print("\nRunning containers:")
for container in client.containers.list():
    print(f"- {container.name} (ID: {container.short_id}, Status: {container.status})")

# Example: Run a 'hello-world' container (only if it's not already running)
print("\nAttempting to run 'hello-world' container...")
try:
    # Run a container, detach, and remove it after exit
    container = client.containers.run('hello-world', detach=True, remove=True)
    print(f"Container '{container.name}' started and exited.")
except docker.errors.ImageNotFound:
    print("Image 'hello-world' not found locally, pulling...")
    client.images.pull('hello-world')
    container = client.containers.run('hello-world', detach=True, remove=True)
    print(f"Container '{container.name}' started and exited after pulling image.")
except docker.errors.APIError as e:
    print(f"Error running container: {e}")