---
id: docker-image-py
version: "0.2.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# docker-image-py — Parse docker image as distribution does.

License: permissive · Maintenance: active · Downloads: 3.2M/mo

## What it is and what it does

docker-image-py is a Python library for parsing Docker image reference strings into structured components. It implements the Docker distribution reference grammar, allowing you to extract and normalize registry hostnames, repository names, tags, and content digests from image strings.

The package provides two main parsing modes: parse_normalized_named() applies Docker CLI conventions (filling in docker.io for unqualified names, adding library/ for official images), while parse() performs raw grammar-level parsing without inference. It's useful in tools that need to validate, normalize, or decompose image references programmatically.

Use it for:

- Normalize user-provided image names to ensure consistent registry and namespace handling.
- Extract registry hostname and repository path from image strings for routing to custom registries.
- Parse image digests and tags for validation or logging in deployment workflows.
- Validate Docker image reference syntax before passing to container runtime APIs.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Parses Docker image reference strings into their component parts (registry, repository, tag, digest) following Docker's distribution reference grammar and normalization rules.

Yes. The package solves a specific, well-defined problem (Docker image reference parsing) with low install friction, active maintenance, permissive licensing, and no known vulnerabilities. It's appropriate for any tool that needs to handle Docker image strings programmatically.

## Install

pip install docker-image-py
uv add docker-image-py
poetry add docker-image-py

## Installing docker-image-py

Before you install: Low friction install with a single runtime dependency (regex). Active maintenance with recent release 46 days ago and current Python version support (3.10–3.14).

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions.

Quickstart:

pip install docker-image-py

from docker_image import reference

ref = reference.Reference.parse_normalized_named('ubuntu')
print(ref.familiar_name())

Requires Python 3.10 or later.

Verify before relying:

- Whether parse_normalized_named() and parse() handle all edge cases in real-world container registries beyond the examples shown.
- Performance characteristics when parsing large batches of image references.
- Compatibility with container orchestration platforms and CI/CD systems that may have specific reference format requirements.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 3.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

parse docker image names, docker reference parsing, container image registry parsing, docker tag digest extraction, normalize docker image strings, docker, container-registry, parsing

[View on SkillFed](https://skillfed.io/packages/docker-image-py) · [View on PyPI](https://pypi.org/project/docker-image-py/)