{"id":176,"library":"docker","title":"Python Docker SDK","description":"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.","status":"active","version":"7.1.0","language":"python","source_language":"en","source_url":"https://github.com/docker/docker-py/","tags":["docker","containerization","devops","client","automation"],"install":[{"cmd":"pip install docker","lang":"bash","label":"Base installation"},{"cmd":"pip install docker[websockets]","lang":"bash","label":"With WebSocket support"}],"dependencies":[{"reason":"Required for WebSocket communication (e.g., for `exec_run(stream=True)`) if explicitly needed. Not included by default since 7.0.0.","package":"websocket-client","optional":true}],"imports":[{"note":"docker.Client() was the old API entry point and is deprecated. Use docker.from_env() for convenience or docker.DockerClient() for explicit client creation.","wrong":"import docker\nclient = docker.Client()","symbol":"from_env","correct":"import docker\nclient = docker.from_env()"},{"note":"Use this for explicit client configuration.","symbol":"DockerClient","correct":"from docker import DockerClient\nclient = DockerClient(base_url='unix://var/run/docker.sock')"},{"note":"For lower-level access to the Docker Engine API.","symbol":"APIClient","correct":"from docker import APIClient\nclient = APIClient(base_url='unix://var/run/docker.sock')"},{"note":"All Docker-specific exceptions are under the 'errors' module.","symbol":"errors","correct":"from docker import errors\ntry:\n    # ...\nexcept errors.DockerException as e:\n    # handle exception"}],"quickstart":{"code":"import docker\nimport os\n\n# Connect to the Docker daemon\n# docker-py automatically uses DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH\n# environment variables if available, or falls back to default sockets.\nclient = docker.from_env()\n\n# Verify the connection\ntry:\n    client.ping()\n    print(\"Successfully connected to Docker daemon.\")\nexcept docker.errors.DockerException as e:\n    print(f\"Error connecting to Docker: {e}\")\n    print(\"Please ensure Docker is running and accessible (e.g., Docker Desktop or daemon started).\")\n    exit(1)\n\n# List all running containers\nprint(\"\\nRunning containers:\")\nfor container in client.containers.list():\n    print(f\"- {container.name} (ID: {container.short_id}, Status: {container.status})\")\n\n# Example: Run a 'hello-world' container (only if it's not already running)\nprint(\"\\nAttempting to run 'hello-world' container...\")\ntry:\n    # Run a container, detach, and remove it after exit\n    container = client.containers.run('hello-world', detach=True, remove=True)\n    print(f\"Container '{container.name}' started and exited.\")\nexcept docker.errors.ImageNotFound:\n    print(\"Image 'hello-world' not found locally, pulling...\")\n    client.images.pull('hello-world')\n    container = client.containers.run('hello-world', detach=True, remove=True)\n    print(f\"Container '{container.name}' started and exited after pulling image.\")\nexcept docker.errors.APIError as e:\n    print(f\"Error running container: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"The `ssl_version` and `assert_hostname` options were removed from `DockerClient` and `APIClient` initialization.","severity":"breaking","affected_versions":"7.0.0+"},{"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]`.","message":"Websocket support is no longer included by default and requires an extra installation.","severity":"breaking","affected_versions":"7.0.0+"},{"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`.","message":"The minimum and default Docker Engine API versions have been bumped.","severity":"breaking","affected_versions":"7.1.0+"},{"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.","message":"Older versions of `docker-py` (specifically 6.0.x) had incompatibilities with newer `requests` (2.29+) or `urllib3` (2.x) versions.","severity":"gotcha","affected_versions":"~6.0.0 to 6.0.1"},{"fix":"Upgrade `docker-py` to version 7.1.0 or later, as this issue was fixed.","message":"`KeyError` when creating new configs (`ConfigCollection`) due to missing `name` field.","severity":"gotcha","affected_versions":"< 7.1.0"}],"env_vars":null,"last_verified":"2026-05-12T09:43:08.237Z","next_check":"2026-07-11T00:00:00.000Z","problems":[{"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.","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.","error":"docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))"},{"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.","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.","error":"ModuleNotFoundError: No module named 'docker'"},{"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`).","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.","error":"AttributeError: 'function' object has no attribute 'run'"},{"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.","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.","error":"docker.errors.APIError: 404 Client Error: Not Found (\"No such image: <image_name>\" or \"No such container: <container_id/name>\")"},{"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.","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.","error":"ERROR: Could not find a version that satisfies the requirement <package>==<version> (from versions: none) ERROR: No matching distribution found for <package>==<version>"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"ssh","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.19,"mem_mb":19.1,"disk_size":"45.5M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.63,"mem_mb":11.1,"disk_size":"22.4M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"websockets","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.61,"mem_mb":11.3,"disk_size":"23.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"ssh","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.85,"mem_mb":19.1,"disk_size":"46M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.45,"mem_mb":11.1,"disk_size":"23M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"websockets","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.45,"mem_mb":11.3,"disk_size":"24M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"ssh","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.67,"mem_mb":21.9,"disk_size":"48.6M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.84,"mem_mb":12.5,"disk_size":"24.6M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"websockets","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.79,"mem_mb":12.6,"disk_size":"25.5M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"ssh","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.28,"mem_mb":21.9,"disk_size":"49M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.74,"mem_mb":12.5,"disk_size":"25M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"websockets","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.71,"mem_mb":12.6,"disk_size":"26M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"ssh","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.82,"mem_mb":21.1,"disk_size":"40.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.74,"mem_mb":13,"disk_size":"16.4M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"websockets","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":13,"disk_size":"17.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"ssh","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.76,"mem_mb":21.9,"disk_size":"40M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.76,"mem_mb":13,"disk_size":"17M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"websockets","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.73,"mem_mb":13,"disk_size":"18M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"ssh","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.79,"mem_mb":22.1,"disk_size":"39.8M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.74,"mem_mb":13.3,"disk_size":"16.0M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"websockets","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":13.3,"disk_size":"16.9M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"ssh","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.76,"mem_mb":22.1,"disk_size":"40M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.71,"mem_mb":13.3,"disk_size":"16M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"websockets","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":13.3,"disk_size":"17M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"ssh","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.16,"mem_mb":19,"disk_size":"45.6M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.57,"mem_mb":10.9,"disk_size":"21.7M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"websockets","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.56,"mem_mb":10.9,"disk_size":"22.4M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"ssh","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.96,"mem_mb":19,"disk_size":"46M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.52,"mem_mb":10.9,"disk_size":"22M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"websockets","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.5,"mem_mb":10.9,"disk_size":"23M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}