{"id":2933,"library":"docker-image-py","title":"Docker Image Python Parser","description":"docker-image-py is a Python library designed to parse Docker image names, tags, and registries, mimicking how Docker distributions handle image parsing. It provides a structured way to break down an image string into its components. The current version is 0.1.13, released in July 2024, and the library maintains an active, albeit infrequent, release cadence, driven by community contributions and specific parsing needs.","status":"active","version":"0.1.13","language":"en","source_language":"en","source_url":"https://github.com/realityone/docker-image-py","tags":["docker","image","parsing","registry","container"],"install":[{"cmd":"pip install docker-image-py","lang":"bash","label":"Install from PyPI"}],"dependencies":[],"imports":[{"symbol":"Reference","correct":"from docker_image import Reference"}],"quickstart":{"code":"from docker_image import Reference\n\n# Parse a full image reference\nref = Reference.parse('registry.example.com/repo/image:tag')\nprint(f\"Registry: {ref.registry}\")\nprint(f\"Repository: {ref.repository}\")\nprint(f\"Tag: {ref.tag}\")\nprint(f\"Digest: {ref.digest}\")\nprint(f\"Raw: {ref.raw}\")\n\n# Parse an image with no registry specified (defaults to 'docker.io')\nref_default = Reference.parse('ubuntu:latest')\nprint(f\"\\nRegistry (default): {ref_default.registry}\")\nprint(f\"Repository: {ref_default.repository}\")\n\n# Parse an image with a digest\nref_digest = Reference.parse('myrepo/myimage@sha256:456abc...')\nprint(f\"\\nRepository: {ref_digest.repository}\")\nprint(f\"Digest: {ref_digest.digest}\")","lang":"python","description":"The `Reference.parse()` method is the primary entry point for parsing Docker image strings. It returns a `Reference` object with attributes for registry, repository, tag, and digest."},"warnings":[{"fix":"Ensure you are importing from `docker_image` for parsing, or `docker` for the Docker SDK. Verify the PyPI package `docker-image-py` is installed if you intend to use the parsing library.","message":"This library is 'docker-image-py' (from realityone), which specifically focuses on *parsing* Docker image names. It is not the 'docker-py' or 'docker' SDK (from Docker Inc.) which is used to interact with the Docker daemon API to build, run, and manage containers. Confusing the two can lead to incorrect imports and unexpected behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always provide the full registry path for private or custom images (e.g., `myregistry.com/myimage:tag`) or explicitly check the `registry` attribute if the default `docker.io` is not desired.","message":"The `Reference.parse()` method will infer 'docker.io' as the registry if no registry is explicitly provided in the image string. Be aware of this default behavior, especially when working with private or custom registries where an explicit registry name is always expected.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement robust error handling (e.g., `try-except`) when parsing user-provided or external image strings. Consider additional validation steps if the integrity or existence of the image is critical.","message":"The library primarily handles the structural parsing of image names. It does not validate the existence of the image, the correctness of the digest (beyond format), or the accessibility of the registry. Malformed image strings may raise exceptions or produce unexpected parsing results.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}