Install & Compatibility
Where this runs
tested against v7.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.438s · 23MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.7s · import 0.417s · 24MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
from_env
✓ import docker
client = docker.from_env()
✗ import docker
client = docker.Client()
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.
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}")
docker --version
Errors
Common errors & fixes
docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
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.
fixEnsure 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.
ModuleNotFoundError: No module named 'docker'
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.
fixInstall 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.
AttributeError: 'function' object has no attribute 'run'
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.
fixAccess 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`).
docker.errors.APIError: 404 Client Error: Not Found ("No such image: <image_name>" or "No such container: <container_id/name>")
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.
fixVerify 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: Could not find a version that satisfies the requirement <package>==<version> (from versions: none) ERROR: No matching distribution found for <package>==<version>
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.
fixCheck 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.
Upgrade
Version history
7.2.0latest on PyPI · released Jul 9, 2026
Audit
Dependencies
websocket-clientoptionalRequired for WebSocket communication (e.g., for `exec_run(stream=True)`) if explicitly needed. Not included by default since 7.0.0.