Install & Compatibility
Where this runs
tested against v7.2.0.20260827 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.000s · 20MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
docker
✓ import docker_stubs as docker
✗ import docker-stubs as docker
This quickstart demonstrates how to connect to the Docker daemon and run a basic 'hello-world' container using the `docker` library, leveraging `types-docker` for static type checking. It assumes Docker Desktop or a Docker daemon is running and accessible.
import docker
import os
def main():
# Connect to the Docker daemon using environment variables or default socket
# Requires Docker Desktop or daemon running.
# For auth, Docker typically uses local socket or environment variables like DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH.
# No specific auth key needed in os.environ for basic local setup.
client: docker.DockerClient = docker.from_env()
print("Docker client connected.")
# Run a simple 'hello-world' container
print("Running 'hello-world' container...")
try:
container = client.containers.run('hello-world', remove=True, detach=True)
print(f"Container ID: {container.id}")
# Wait for container to finish and print its logs
container.wait()
logs = container.logs().decode('utf-8')
print("Container logs:")
print(logs)
print("Container finished and removed.")
except docker.errors.ContainerError as e:
print(f"Container error: {e}")
except docker.errors.ImageNotFound as e:
print(f"Image not found: {e}. Please ensure 'hello-world' image is available or can be pulled.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
# Example: List all running containers (if any)
print("\nListing running containers:")
for c in client.containers.list():
print(f" - {c.name} ({c.status})")
if __name__ == "__main__":
main()
Debug
Known issues
breakingThe `docker` library (for which `types-docker` provides stubs) dropped support for Python 2.7 with version 2.0.0 and Python 3.6 with version 7.x. Ensure your Python environment meets the minimum `docker` library requirements.fixUpgrade your Python environment to 3.7+ (for docker 2.0.0+) or 3.7+ (for docker 7.0.0+). types-docker itself requires Python >=3.10.
affects: docker<2.0.0 (Python 2.7), docker<7.0.0 (Python 3.6)
breakingThe `docker` library was renamed from `docker-py` around version 2.0.0. Installing `docker-py` instead of `docker` will lead to `ModuleNotFoundError` when importing `docker`.fixEnsure you install the correct package: `pip install docker` (not `pip install docker-py`).
affects: docker-py installations post-2.0.0 rename
gotchaWhen both an installed library (like `docker`) has its own inline type hints and a stub package (`types-docker`) is present, type checkers typically prioritize the stub package. This can lead to unexpected type-checking errors if the stub package's types differ significantly or are more strict than the inline types in the library's source code, or if the stub version is mismatched with the runtime library version.fixIt's generally recommended to align `types-docker`'s version with your `docker` library's major and minor version (e.g., `docker==7.1.*` should use `types-docker==7.1.*`). Regularly update both. If issues persist, refer to your type checker's documentation (e.g., MyPy's `$MYPYPATH`) for stub resolution order.
affects: All versions
deprecatedNative type hinting for generic collections (e.g., `list[str]` instead of `typing.List[str]`) became available in Python 3.9. While older `typing` module imports still work, it's recommended to use native generics for cleaner and more Pythonic code when using Python 3.9+.fixUpdate your type hints from `from typing import List, Dict` to using built-in types directly: `items: list[str]` instead of `items: List[str]`.
affects: Python 3.9+
Upgrade
Version history
7.2.0.20260827latest on PyPI · released Aug 27, 2026
Audit
Dependencies
dockerrequiredProvides type stubs for the 'docker' runtime library. This should be installed as a development dependency.