Docker Image Name Guide [2026]

Introduction to Docker Image Names
The Docker Image Reference Format
Registry
Namespace and Repository
Tags
Digests
Docker Hub Official Images
Container Registry Comparison
Image References in Practice
Common Mistakes
Programmatic Image Name Parsing
Using Our Free Docker Image Parser

Introduction to Docker Image Names

Docker image names are the addressing system of the container world. Every time you pull a container image, deploy a microservice, or write a CI/CD pipeline, you use an image reference to tell Docker (or any OCI-compatible runtime) exactly which image to use. Getting image names right is not a trivial detail — it is fundamental to reproducible builds, secure deployments, and reliable infrastructure.

Container image references appear everywhere in modern software development. In a Dockerfile, the FROM instruction specifies the base image your application builds upon. In a docker-compose.yml file, the image: field determines which container runs for each service. In Kubernetes manifests, the containers.image field in a Pod spec tells the kubelet which image to pull and run. In CI/CD pipelines — whether GitHub Actions, GitLab CI, Jenkins, or CircleCI — image references define both the build environment and the artifacts you produce and deploy.

Despite their ubiquity, Docker image names are frequently misunderstood. Developers often treat them as simple strings without appreciating the structure encoded within them. This leads to subtle problems: images pulled from the wrong registry, deployments that silently use outdated versions because of the :latest tag, security vulnerabilities introduced by mutable tags, and CI/CD pipelines that break when a registry URL changes. Understanding the Docker image name format eliminates these problems and gives you precise control over your container infrastructure.

This guide provides a complete, in-depth explanation of the Docker image reference format. We will dissect every component — registry, namespace, repository, tag, and digest — explain how Docker resolves short names, compare major container registries, show how image references appear in real-world configuration files, and cover common mistakes that trip up even experienced engineers.

The Docker Image Reference Format

A Docker image reference is a structured string that uniquely identifies a container image. The full format is:

[registry[:port]/][namespace/]repository[:tag][@digest]

Let us break down each component with a fully annotated example:

ghcr.io/my-org/my-app:v2.1.0@sha256:a3ed95caeb02...
|        |      |      |       |
|        |      |      |       +-- Digest (immutable content hash)
|        |      |      +-- Tag (human-readable version label)
|        |      +-- Repository (image name)
|        +-- Namespace (organization or user)
+-- Registry (hostname where image is stored)

Not every component is required. Docker applies sensible defaults when components are omitted. Here are examples showing how Docker expands short image references into their fully qualified forms:

# What you type             # What Docker resolves it to
nginx                       docker.io/library/nginx:latest
ubuntu:22.04                docker.io/library/ubuntu:22.04
myuser/myapp                docker.io/myuser/myapp:latest
myuser/myapp:v1.0           docker.io/myuser/myapp:v1.0
ghcr.io/org/app:main        ghcr.io/org/app:main
gcr.io/project/img:v2       gcr.io/project/img:v2

Understanding these defaults is critical. When you type docker pull nginx, Docker is actually pulling docker.io/library/nginx:latest. Each implicit default — the Docker Hub registry, the library/ namespace for official images, and the :latest tag — has important implications that we will explore in the sections that follow.

Formal Grammar

The OCI Distribution Specification defines the formal grammar for image references. While you do not need to memorize the spec, understanding the rules helps you avoid invalid references:

reference       := name [ ":" tag ] [ "@" digest ]
name            := [ domain "/" ] path
domain          := host [ ":" port ]
host            := hostname | IP
path            := component [ "/" component ]*
component       := [a-z0-9]+ ( [._-] [a-z0-9]+ )*
tag             := [a-zA-Z0-9_.-]{1,128}
digest          := algorithm ":" hex
algorithm       := [a-z0-9]+([+.-_][a-z0-9]+)*
hex             := [a-f0-9]{32,}

Key takeaways from the grammar: repository paths must be lowercase, tags allow uppercase letters and have a maximum length of 128 characters, and digests always follow the algorithm:hex format. These constraints are enforced by container registries and runtimes, so violating them will cause errors.

Registry

The registry is the hostname of the server that stores and serves container images. It is the first component of a fully qualified image reference, appearing before the first forward slash. When omitted, Docker defaults to docker.io (Docker Hub).

Docker uses a specific heuristic to determine whether the first component of an image name is a registry hostname or part of the image path. The first component is treated as a registry if it meets any of these conditions:

It contains a dot (.) — e.g., ghcr.io, gcr.io, registry.example.com
It contains a colon (:) — e.g., localhost:5000, myregistry:8443
It is the literal string localhost

If none of these conditions are met, Docker treats the first component as a namespace on Docker Hub. This is why myuser/myapp resolves to docker.io/myuser/myapp (no dot or colon, so myuser is a Docker Hub namespace), while ghcr.io/myuser/myapp correctly identifies ghcr.io as the registry (it contains a dot).

Common Container Registries

The container ecosystem has a rich set of registries, each serving different use cases. Here are the most widely used registries and their hostnames:

Registry                         Hostname
--------                         --------
Docker Hub                       docker.io (default)
GitHub Container Registry        ghcr.io
Google Container Registry        gcr.io (legacy)
Google Artifact Registry         REGION-docker.pkg.dev
Amazon ECR (Public)              public.ecr.aws
Amazon ECR (Private)             ACCOUNT.dkr.ecr.REGION.amazonaws.com
Azure Container Registry         REGISTRY.azurecr.io
Red Hat Quay                     quay.io
Microsoft Container Registry     mcr.microsoft.com
Kubernetes Registry              registry.k8s.io
GitLab Container Registry        registry.gitlab.com
Harbor (self-hosted)             your-harbor-domain.com
JFrog Artifactory                your-jfrog-domain.com

Registry with Port Numbers

Registries can include port numbers, which is common for development environments, self-hosted registries, and registries running behind non-standard ports:

# Local development registry
localhost:5000/my-app:dev

# Self-hosted registry on custom port
registry.internal.company.com:8443/platform/api-gateway:v3.1

# Docker registry running on a non-standard port
192.168.1.100:5000/team/service:latest

When a port number is present, it is separated from the hostname by a colon. This is one reason Docker uses the dot-or-colon heuristic for registry detection — a component like localhost:5000 is unambiguously a registry because it contains a colon.

Docker Hub Registry Shorthand

Docker Hub has a special status as the default registry. When you omit the registry, Docker automatically prepends docker.io. Additionally, Docker Hub accepts the shorthand docker.io even though the actual API endpoint is registry-1.docker.io. This means the following references are all equivalent:

# All equivalent for Docker Hub images
nginx
library/nginx
docker.io/library/nginx
docker.io/library/nginx:latest

Namespace and Repository

After the registry, the remaining path components form the namespace and repository name. The namespace identifies the owner of the image (a user, organization, or project), while the repository is the specific image name. Together, they form the image path.

Official Images (library/)

On Docker Hub, official images live under the special library/ namespace. When you pull an image with no namespace, Docker automatically prepends library/. Official images are curated and maintained by Docker in partnership with upstream maintainers:

# These are official images - Docker adds "library/" automatically
nginx           -->  docker.io/library/nginx
ubuntu          -->  docker.io/library/ubuntu
python          -->  docker.io/library/python
node            -->  docker.io/library/node
postgres        -->  docker.io/library/postgres
redis           -->  docker.io/library/redis
alpine          -->  docker.io/library/alpine

User and Organization Images

Non-official images on Docker Hub include the user or organization name as a namespace prefix. This distinguishes different publishers' images with the same repository name:

# User/organization namespace on Docker Hub
bitnami/nginx
grafana/grafana
prom/prometheus
hashicorp/terraform
traefik/whoami

The namespace provides a trust boundary — you know that grafana/grafana comes from the Grafana organization, while a hypothetical randomuser/grafana would be from an unverified publisher.

Nested Paths

Some registries support deeply nested paths with multiple levels of hierarchy. This is particularly common with Google Container Registry, Google Artifact Registry, Amazon ECR, and GitLab Container Registry:

# Google Container Registry - project-based nesting
gcr.io/my-gcp-project/backend/api-server:v2.0

# Google Artifact Registry - region + project + repo
us-central1-docker.pkg.dev/my-project/my-repo/my-image:latest

# Amazon ECR - account + region based
123456789012.dkr.ecr.us-east-1.amazonaws.com/my-org/my-service:v1

# GitLab Container Registry - group + subgroup + project
registry.gitlab.com/my-group/my-subgroup/my-project/my-image:v1

# GitHub Container Registry
ghcr.io/my-org/my-team/my-service:main

Docker Hub limits namespaces to a single level (e.g., myuser/myimage), but most other registries allow arbitrary nesting. This flexibility is useful for organizing images by team, project, environment, or any other organizational scheme.

Repository Name Constraints

Repository names (and path components in general) must follow specific rules:

Must be lowercase — MyApp is invalid; use myapp
Can contain lowercase letters, digits, and separators (., _, -)
Separators cannot appear at the start or end of a component
Consecutive separators (like my--app) are not allowed per the OCI spec, though some registries may be lenient
Path components are separated by forward slashes (/)

# Valid repository names
my-app
my_app
my.app
myapp123
my-org/my-app
my-org/backend/api-server

# Invalid repository names
My-App          (uppercase letters)
my app          (spaces)
-my-app         (starts with separator)
my--app         (consecutive hyphens per OCI spec)

Digests

While tags provide human-readable version labels, digests provide immutable, content-addressable references to container images. A digest is a cryptographic hash of the image manifest, and it is guaranteed to never change — if even a single byte of the image changes, the digest changes. This makes digests the only truly reliable way to reference a specific image version.

Digest Format

Digests follow the format @algorithm:hex, where the algorithm is typically sha256 and the hex string is a 64-character hexadecimal hash:

# Full digest reference (no tag)
nginx@sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4

# Tag + digest (both present)
nginx:1.25.4@sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4

# Fully qualified with registry, namespace, tag, and digest
docker.io/library/nginx:1.25.4@sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4

When both a tag and a digest are present, the digest takes precedence. The tag is effectively informational — it helps humans understand which version the digest corresponds to, but the runtime uses the digest to fetch the exact image content.

When to Use Digests vs. Tags

Digests and tags serve complementary purposes. Here is when to use each:

# Use TAGS for:
# - Development environments (convenience)
# - Dockerfile FROM instructions (readability)
# - Documentation and communication
FROM python:3.12-slim

# Use DIGESTS for:
# - Production deployments (reproducibility)
# - Security-sensitive environments (tamper-proof)
# - Compliance requirements (auditability)
FROM python@sha256:2dc3e0b4aee...

# Use BOTH for maximum clarity:
# - Tag for human readability + digest for immutability
FROM python:3.12-slim@sha256:2dc3e0b4aee...

In production Kubernetes deployments, referencing images by digest ensures that every node in your cluster runs exactly the same image, regardless of whether the tag has been updated since the deployment was created. This eliminates an entire class of "works on my machine" (or "works on that node") issues.

Obtaining Digests

You can retrieve an image's digest using Docker CLI commands or registry APIs:

# Get the digest of a local image
docker inspect --format='{{index .RepoDigests 0}}' nginx:1.25.4

# Get the digest from a remote registry (without pulling)
docker manifest inspect nginx:1.25.4 | grep digest

# Using crane (a popular registry tool)
crane digest nginx:1.25.4

# Using skopeo
skopeo inspect docker://nginx:1.25.4 | jq -r '.Digest'

Docker Hub Official Images

Docker Hub Official Images are a curated set of container images maintained by Docker in collaboration with upstream software maintainers and the community. These images undergo security reviews, follow best practices for Dockerfile construction, and provide a trusted foundation for building container-based applications.

What Makes an Image "Official"

Official images are distinguished by several characteristics:

Curated by Docker: Docker's official images team reviews and approves all Dockerfiles and build configurations.
Automated builds: Images are built automatically from public GitHub repositories, ensuring transparency and reproducibility.
Security scanning: Official images are regularly scanned for known vulnerabilities and updated when patches are available.
Documentation: Each official image has comprehensive documentation on Docker Hub describing usage, environment variables, and configuration options.
Multi-architecture support: Most official images support multiple CPU architectures through manifest lists.
The library/ prefix: Internally, official images live under the library/ namespace, which Docker Hub hides from the user-facing name.

The library/ Prefix

When you type docker pull nginx, Docker expands this to docker.io/library/nginx:latest. The library/ namespace is a special, reserved namespace on Docker Hub that can only contain official images. You cannot create a Docker Hub user or organization called "library."

# How Docker resolves official image short names
nginx               --> docker.io/library/nginx:latest
ubuntu:22.04        --> docker.io/library/ubuntu:22.04
python:3.12-slim    --> docker.io/library/python:3.12-slim
node:20-alpine      --> docker.io/library/node:20-alpine
postgres:16         --> docker.io/library/postgres:16
redis:7             --> docker.io/library/redis:7
alpine:3.19         --> docker.io/library/alpine:3.19
golang:1.22         --> docker.io/library/golang:1.22

Popular Official Images

Here are some of the most widely used official images, along with their common tag patterns:

Image       Common Tags                          Use Case
-----       -----------                          --------
nginx       1.25, 1.25.4, 1.25-alpine            Web server / reverse proxy
ubuntu      22.04, 24.04, jammy, noble           General-purpose base image
alpine      3.19, 3.20                           Minimal base image (~5MB)
python      3.12, 3.12-slim, 3.12-alpine         Python applications
node        20, 20-slim, 20-alpine               Node.js applications
postgres    16, 16-alpine                        PostgreSQL database
redis       7, 7-alpine                          In-memory data store
mysql       8.0, 8.4                             MySQL database
mongo       7, 7-jammy                           MongoDB database
golang      1.22, 1.22-alpine                    Go applications
openjdk     21, 21-slim                          Java applications
httpd       2.4, 2.4-alpine                      Apache HTTP Server
traefik     v3.0, v3.0-alpine                    Cloud-native reverse proxy
vault       1.15, 1.16                           HashiCorp Vault

The -slim variants contain a minimal set of packages needed to run the language runtime, reducing image size significantly. The -alpine variants use Alpine Linux as the base, resulting in even smaller images but with potential compatibility differences (Alpine uses musl libc instead of glibc).

Container Registry Comparison

Choosing the right container registry depends on your cloud provider, security requirements, cost constraints, and team workflow. Here is a detailed comparison of the major container registries, including their image reference formats.

Registry Reference Formats

Registry                     Image Reference Format
--------                     ----------------------
Docker Hub                   docker.io/namespace/image:tag
  (official)                 docker.io/library/image:tag (or just image:tag)
  (user)                     docker.io/user/image:tag (or user/image:tag)

GitHub Container Registry    ghcr.io/OWNER/IMAGE:tag
  (org)                      ghcr.io/my-org/my-image:v1.0
  (user)                     ghcr.io/myuser/my-image:v1.0

Google Container Registry    gcr.io/PROJECT-ID/IMAGE:tag
  (legacy)                   gcr.io/my-project/my-image:v1.0
  (regional)                 us.gcr.io/my-project/my-image:v1.0

Google Artifact Registry     REGION-docker.pkg.dev/PROJECT/REPO/IMAGE:tag
                             us-central1-docker.pkg.dev/my-proj/my-repo/my-img:v1

Amazon ECR (Private)         ACCOUNT.dkr.ecr.REGION.amazonaws.com/REPO:tag
                             123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:v1

Amazon ECR (Public)          public.ecr.aws/ALIAS/IMAGE:tag
                             public.ecr.aws/nginx/nginx:1.25

Azure Container Registry     REGISTRY.azurecr.io/REPO:tag
                             myregistry.azurecr.io/my-app:v1.0

Red Hat Quay                 quay.io/NAMESPACE/IMAGE:tag
                             quay.io/prometheus/prometheus:v2.50.0

Microsoft MCR                mcr.microsoft.com/PATH/IMAGE:tag
                             mcr.microsoft.com/dotnet/aspnet:8.0

Kubernetes Registry          registry.k8s.io/IMAGE:tag
                             registry.k8s.io/kube-apiserver:v1.29.0

GitLab Container Registry    registry.gitlab.com/GROUP/PROJECT/IMAGE:tag
                             registry.gitlab.com/my-group/my-project:v1.0

Feature Comparison

Feature              Docker Hub   GHCR    GAR     ECR     ACR     Quay
-------              ----------   ----    ---     ---     ---     ----
Free tier            Yes (*)      Yes     Yes     Yes     No      Yes
Private repos        Paid         Free    Free    Free    Paid    Paid
Vulnerability scan   Paid         Free    Free    Free    Free    Free
Tag immutability     No           No      Yes     Yes     Yes     No
Geo-replication      No           No      Yes     Yes     Yes     No
OCI artifacts        Yes          Yes     Yes     Yes     Yes     Yes
Manifest lists       Yes          Yes     Yes     Yes     Yes     Yes
Webhook support      Yes          Yes     Yes     Yes     Yes     Yes
Rate limiting        Yes (*)      Generous None    None    None    Yes

(*) Docker Hub free tier: 200 pulls/6hr (anonymous), 200 pulls/6hr (authenticated)

The best choice depends on your ecosystem. If your source code is on GitHub, GHCR offers the tightest integration. If you run on AWS, ECR provides IAM-based access control and no cross-region data transfer costs within the same AWS account. If you run on GCP, Artifact Registry integrates natively with GKE and Cloud Build. Azure Container Registry naturally pairs with AKS and Azure DevOps.

Image References in Practice

Understanding the image name format is most valuable when you see how references are used in real-world configuration files. This section shows how Docker image references appear in the most common contexts.

Dockerfiles (FROM instruction)

The FROM instruction in a Dockerfile specifies the base image. It supports all forms of image references:

# Simple - official image with tag
FROM python:3.12-slim

# Multi-stage build with named stages
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o /app/server

FROM alpine:3.19 AS runtime
COPY --from=builder /app/server /usr/local/bin/
CMD ["server"]

# Pinned by digest for reproducible builds
FROM python:3.12-slim@sha256:2dc3e0b4aee14f4d7d3a7e0b...

# Private registry
FROM 123456789012.dkr.ecr.us-east-1.amazonaws.com/base-images/python:3.12

# Using ARG for dynamic base image
ARG BASE_IMAGE=python:3.12-slim
FROM ${BASE_IMAGE}

Docker Compose (image field)

In docker-compose.yml, the image field specifies the container image for each service:

version: "3.9"
services:
  web:
    image: nginx:1.25.4-alpine
    ports:
      - "80:80"

  api:
    image: ghcr.io/my-org/api-server:v2.1.0
    environment:
      DATABASE_URL: postgres://db:5432/myapp

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data

  cache:
    image: redis:7-alpine

  monitoring:
    image: prom/prometheus:v2.50.0
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

volumes:
  pgdata:

Kubernetes Pod Specs

In Kubernetes manifests, the image field in a container spec follows the same Docker image reference format. Kubernetes also supports the imagePullPolicy field, which controls when the kubelet pulls the image:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api-server
  template:
    metadata:
      labels:
        app: api-server
    spec:
      containers:
        - name: api
          image: ghcr.io/my-org/api-server:v2.1.0@sha256:a3ed95ca...
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 8080
        - name: sidecar
          image: envoyproxy/envoy:v1.29.1
          ports:
            - containerPort: 9901
      initContainers:
        - name: migrations
          image: ghcr.io/my-org/api-server:v2.1.0
          command: ["python", "manage.py", "migrate"]
      imagePullSecrets:
        - name: ghcr-credentials

Note the imagePullSecrets field — this is required when pulling from private registries that need authentication. Kubernetes uses the credentials stored in the referenced Secret to authenticate with the registry.

CI/CD Pipelines

Image references appear in CI/CD pipelines both as the environment to run steps in and as the artifact being built and pushed:

# GitHub Actions
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: |
            ghcr.io/my-org/my-app:${{ github.sha }}
            ghcr.io/my-org/my-app:latest

# GitLab CI
build:
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker build -t registry.gitlab.com/my-group/my-project:$CI_COMMIT_SHA .
    - docker push registry.gitlab.com/my-group/my-project:$CI_COMMIT_SHA

Helm Charts

Helm charts typically parameterize image references through values, allowing users to customize the registry, repository, and tag independently:

# values.yaml
image:
  registry: ghcr.io
  repository: my-org/my-app
  tag: v2.1.0
  digest: ""
  pullPolicy: IfNotPresent

# deployment.yaml template
spec:
  containers:
    - name: {{ .Chart.Name }}
      image: "{{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }}"
      imagePullPolicy: {{ .Values.image.pullPolicy }}

This pattern gives operators maximum flexibility to point Helm releases at different registries (e.g., an internal mirror) without modifying the chart itself.

Common Mistakes

Even experienced engineers make mistakes with Docker image names. These errors range from minor inconveniences to production-breaking issues. Knowing the common pitfalls helps you avoid them.

Using :latest in Production

This is the single most common and most dangerous mistake. Using :latest (or omitting the tag entirely) in production deployments makes your infrastructure non-deterministic:

# DANGEROUS - non-deterministic, no audit trail
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - image: my-org/api-server          # Implicit :latest
        - image: my-org/api-server:latest   # Explicit but still dangerous

# SAFE - pinned to exact version
spec:
  template:
    spec:
      containers:
        - image: my-org/api-server:v2.1.0
        - image: my-org/api-server:v2.1.0@sha256:a3ed95ca...

Case Sensitivity

Repository names must be lowercase. Using uppercase letters will cause errors at pull time:

# WRONG - uppercase letters in repository name
docker pull MyOrg/MyApp:v1.0
# Error: invalid reference format

# CORRECT - all lowercase
docker pull myorg/myapp:v1.0

Note that tags are case-sensitive and do allow uppercase letters. myapp:V1 and myapp:v1 are two different tags.

Missing Registry for Private Images

Forgetting to include the registry hostname when referencing images from a private registry causes Docker to look for the image on Docker Hub, where it either does not exist or is a completely different image:

# WRONG - looks for "my-company/api" on Docker Hub
docker pull my-company/api:v1.0

# CORRECT - includes the private registry hostname
docker pull registry.my-company.com/my-company/api:v1.0
docker pull 123456789012.dkr.ecr.us-east-1.amazonaws.com/api:v1.0

This mistake is especially dangerous because if someone has published a malicious image with the same name on Docker Hub, you could pull and run it instead of your intended private image. This is a form of "dependency confusion" attack.

Confusing Port with Tag

When using a registry with a port number, it is easy to confuse the port colon with the tag colon:

# WRONG - Docker interprets "5000/myapp" as the image name
docker pull localhost/5000/myapp:v1

# CORRECT - colon separates host from port
docker pull localhost:5000/myapp:v1

# AMBIGUOUS - is "myhost:8080" a hostname:port or image:tag?
# Docker resolves this by checking for dots and treating
# "myhost" as a Docker Hub namespace (no dot = not a registry)
docker pull myhost:8080    # Pulls image "myhost" with tag "8080" from Docker Hub!

# CORRECT - use FQDN so Docker recognizes it as a registry
docker pull myhost.local:8080/myapp:v1

Invalid Characters in Tags or Names

Using characters outside the allowed set causes cryptic "invalid reference format" errors:

# WRONG - common invalid characters
my-app:v1.0+build.123    # + not allowed in tags
my-app:feature/login     # / not allowed in tags
my-app:v1.0 (latest)     # spaces and parentheses not allowed

# CORRECT - use only [a-zA-Z0-9_.-]
my-app:v1.0-build.123
my-app:feature-login
my-app:v1.0_latest

Not Pinning Base Image Versions

Using unpinned base images in Dockerfiles means your builds are not reproducible. A docker build today might produce a different image than the same docker build tomorrow:

# WRONG - unpinned, different results over time
FROM python
FROM ubuntu
FROM node

# BETTER - pinned to minor version
FROM python:3.12
FROM ubuntu:22.04
FROM node:20

# BEST - pinned to exact version + digest
FROM python:3.12.2@sha256:2dc3e0b4aee...
FROM ubuntu:22.04@sha256:bb63b5e0a1...
FROM node:20.11.1@sha256:5c3ba7f0e2...

Forgetting imagePullPolicy in Kubernetes

Kubernetes has specific rules for when it pulls images. If you use the :latest tag, Kubernetes defaults to imagePullPolicy: Always. For any other tag, it defaults to IfNotPresent. This can lead to stale images if you overwrite a tag:

# If you push a new image with the same tag "v2.1.0",
# Kubernetes will NOT pull the new image on nodes that
# already have the old "v2.1.0" cached.

# Solution 1: Use unique tags (e.g., git SHA)
image: my-app:abc1234

# Solution 2: Use digests
image: my-app:v2.1.0@sha256:new-digest...

# Solution 3: Set imagePullPolicy explicitly
imagePullPolicy: Always  # (but this adds latency)

Programmatic Image Name Parsing

When building automation tools, validating CI/CD pipeline inputs, or processing container inventory, you often need to parse Docker image references programmatically. Here are concise implementations in Python and JavaScript.

Python

def parse_image(reference):
    """Parse a Docker image reference into its components."""
    digest = None
    if "@" in reference:
        reference, digest = reference.rsplit("@", 1)
    tag = None
    if ":" in reference.split("/")[-1]:
        reference, tag = reference.rsplit(":", 1)
    parts = reference.split("/")
    if len(parts) >= 2 and ("." in parts[0] or ":" in parts[0] or parts[0] == "localhost"):
        registry = parts[0]
        repository = "/".join(parts[1:])
    else:
        registry = "docker.io"
        repository = reference
    return {"registry": registry, "repository": repository, "tag": tag or "latest", "digest": digest}

# Usage
print(parse_image("ghcr.io/my-org/app:v2.0"))
# {'registry': 'ghcr.io', 'repository': 'my-org/app', 'tag': 'v2.0', 'digest': None}

JavaScript

function parseImage(reference) {
  let digest = null;
  if (reference.includes("@")) {
    [reference, digest] = reference.split("@");
  }
  let tag = null;
  const lastSegment = reference.split("/").pop();
  if (lastSegment.includes(":")) {
    const idx = reference.lastIndexOf(":");
    tag = reference.slice(idx + 1);
    reference = reference.slice(0, idx);
  }
  const parts = reference.split("/");
  let registry = "docker.io", repository = reference;
  if (parts.length >= 2 && (parts[0].includes(".") || parts[0].includes(":") || parts[0] === "localhost")) {
    registry = parts[0];
    repository = parts.slice(1).join("/");
  }
  return { registry, repository, tag: tag || "latest", digest };
}

// Usage
console.log(parseImage("ghcr.io/my-org/app:v2.0"));
// { registry: 'ghcr.io', repository: 'my-org/app', tag: 'v2.0', digest: null }

These implementations handle the common cases: detecting registries by looking for dots, colons, or localhost; separating digests from tags; and defaulting to docker.io and :latest when components are omitted. For production use, consider established libraries like Python's docker package or the Go reference package from the distribution project, which handle additional edge cases and validation.

Using Our Free Docker Image Parser

While understanding the image name format is valuable, manually parsing complex image references in your daily workflow is tedious and error-prone. That is why we built the QuickUtil Docker Image Parser — a free, browser-based tool that instantly breaks down any Docker image reference into its component parts.

The QuickUtil Docker Image Parser provides:

Instant Parsing: Paste any image reference and instantly see its registry, namespace, repository, tag, and digest broken out into clearly labeled fields.
Format Validation: The parser validates the image reference format and highlights errors, helping you catch invalid characters, missing components, and formatting mistakes before they break your builds or deployments.
Default Resolution: See how Docker would resolve short names — the parser shows the fully qualified form with all defaults applied, so you know exactly which registry and tag Docker will use.
Registry Detection: The parser applies Docker's registry heuristic (dot, colon, localhost) to correctly identify the registry component, eliminating guesswork.
No Data Transmitted: Everything runs in your browser. Your image references — which may reveal internal registry URLs, project names, or infrastructure details — are never sent to any server.

Whether you are debugging a failed docker pull, writing Kubernetes manifests, configuring CI/CD image tags, or auditing your container image inventory, the QuickUtil Docker Image Parser saves you time and reduces errors.

Parse and Validate Docker Image References Instantly

Stop guessing at image name components. Use our free Docker Image Parser to instantly break down, validate, and understand any container image reference.

Try the Docker Image Parser Now

Docker Image Name Format Explained: Complete Guide to Container Image References

Table of Contents