{"id":4301,"library":"types-docker","title":"types-docker","description":"types-docker is a type stub package providing accurate annotations for the `docker` Python library. It enables static type checkers like MyPy or Pyright to verify code using the Docker SDK for Python, ensuring type safety and improving developer experience. This package is part of the `typeshed` project and tracks the `docker` library's versions, aiming for daily updates.","status":"active","version":"7.1.0.20260409","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","docker","typeshed","type checking"],"install":[{"cmd":"pip install types-docker","lang":"bash","label":"Install types-docker"}],"dependencies":[{"reason":"Provides type stubs for the 'docker' runtime library. This should be installed as a development dependency.","package":"docker","optional":false}],"imports":[{"note":"This is the primary import for the Docker SDK for Python, for which types-docker provides stubs.","symbol":"docker","correct":"import docker"},{"note":"Used for explicitly typing the Docker client object returned by `docker.from_env()` or `docker.client.DockerClient()`.","symbol":"DockerClient","correct":"from docker import DockerClient"}],"quickstart":{"code":"import docker\nimport os\n\ndef main():\n    # Connect to the Docker daemon using environment variables or default socket\n    # Requires Docker Desktop or daemon running.\n    # For auth, Docker typically uses local socket or environment variables like DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH.\n    # No specific auth key needed in os.environ for basic local setup.\n    client: docker.DockerClient = docker.from_env()\n\n    print(\"Docker client connected.\")\n\n    # Run a simple 'hello-world' container\n    print(\"Running 'hello-world' container...\")\n    try:\n        container = client.containers.run('hello-world', remove=True, detach=True)\n        print(f\"Container ID: {container.id}\")\n        # Wait for container to finish and print its logs\n        container.wait()\n        logs = container.logs().decode('utf-8')\n        print(\"Container logs:\")\n        print(logs)\n        print(\"Container finished and removed.\")\n    except docker.errors.ContainerError as e:\n        print(f\"Container error: {e}\")\n    except docker.errors.ImageNotFound as e:\n        print(f\"Image not found: {e}. Please ensure 'hello-world' image is available or can be pulled.\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\n    # Example: List all running containers (if any)\n    print(\"\\nListing running containers:\")\n    for c in client.containers.list():\n        print(f\" - {c.name} ({c.status})\")\n\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade 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.","message":"The `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.","severity":"breaking","affected_versions":"docker<2.0.0 (Python 2.7), docker<7.0.0 (Python 3.6)"},{"fix":"Ensure you install the correct package: `pip install docker` (not `pip install docker-py`).","message":"The `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`.","severity":"breaking","affected_versions":"docker-py installations post-2.0.0 rename"},{"fix":"It'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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update your type hints from `from typing import List, Dict` to using built-in types directly: `items: list[str]` instead of `items: List[str]`.","message":"Native 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+.","severity":"deprecated","affected_versions":"Python 3.9+"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}