Image naming conventions (registry/image:tag) in Docker - Commands & Configuration

Introduction

When you use Docker images, you need a clear way to name them so you know what they are and where they come from. Image naming conventions help you organize and find images easily by using a format that includes the registry, image name, and tag.

When you want to pull a specific version of an image from a Docker registry.

When you build your own Docker image and want to give it a meaningful name and version.

When you push images to a private or public registry and need to avoid name conflicts.

When you want to run containers using images with clear version tags to avoid unexpected updates.

When you manage multiple images for different environments like development, testing, and production.

Commands

This command pulls the nginx image with the tag 1.23.3 from the default Docker Hub registry. The tag specifies the exact version you want.

Terminal

docker pull nginx:1.23.3

Expected Output

1.23.3: Pulling from library/nginx

Digest: sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Status: Downloaded newer image for nginx:1.23.3

docker.io/library/nginx:1.23.3

This builds a Docker image from the current folder and tags it with a full name including a custom registry, image name, and version tag 2.0.

Terminal

docker build -t myregistry.example.com/myapp/backend:2.0 .

Expected Output

Sending build context to Docker daemon  10.24kB

Step 1/5 : FROM python:3.10-slim

 ---> abcdef123456

Step 2/5 : COPY . /app

 ---> Using cache

Step 3/5 : WORKDIR /app

 ---> Using cache

Step 4/5 : RUN pip install -r requirements.txt

 ---> Using cache

Step 5/5 : CMD ["python", "app.py"]

 ---> Using cache

Successfully built abcdef123456

Successfully tagged myregistry.example.com/myapp/backend:2.0

→

-t - Assigns a name and optionally a tag in the 'name:tag' format to the image

This command uploads the image tagged as myregistry.example.com/myapp/backend:2.0 to the specified registry so others can use it.

Terminal

docker push myregistry.example.com/myapp/backend:2.0

Expected Output

The push refers to repository [myregistry.example.com/myapp/backend]

2.0: Pushed

2.0: digest: sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890 size: 1234

This runs a container using the image with the full name and tag, ensuring you use the exact version you want.

Terminal

docker run myregistry.example.com/myapp/backend:2.0

Expected Output

No output (command runs silently)

Key Concept

If you remember nothing else, remember: Docker image names follow the format registry/image:tag to clearly identify the source and version of the image.

Common Mistakes

Using image names without tags like 'nginx' expecting the latest version.

This pulls the 'latest' tag by default, which can change and cause unexpected behavior.

Always specify a tag like 'nginx:1.23.3' to use a fixed version.

Omitting the registry when pushing to a private registry.

Docker tries to push to Docker Hub by default and fails if the image name is not fully qualified.

Include the full registry URL in the image name, e.g., 'myregistry.example.com/myapp/backend:2.0'.

Using uppercase letters or invalid characters in image names.

Docker image names must be lowercase and can only contain certain characters; invalid names cause errors.

Use lowercase letters, digits, dashes, underscores, and dots only.

Summary

Docker image names use the format registry/image:tag to identify images clearly.

Tags specify the version or variant of the image to avoid surprises.

Always use full image names with registry and tag when building, pushing, or running images.