3.2 Image Naming

Image naming is the convention Docker uses to identify an image by combining an optional registry address, a repository name, and a tag, into a single reference string that unambiguously points to where an image came from and which version it represents.

The Structure of an Image Name

A full image reference follows a consistent pattern: an optional registry hostname, a repository name (often including a namespace), and a tag, separated by specific characters.

registry.example.com/myteam/myapp:2.3.0

Breaking this down: registry.example.com is the registry, myteam/myapp is the repository (with myteam as a namespace), and 2.3.0 is the tag.

Names Without an Explicit Registry

When no registry is specified, Docker defaults to Docker Hub, which is why images like nginx or postgres can be referenced without any registry prefix at all.

docker pull nginx
docker pull docker.io/library/nginx

These two commands retrieve the same image, since omitting the registry implicitly resolves to Docker Hub's default namespace.

Names With an Implicit Tag

When no tag is specified, Docker defaults to the latest tag, which is simply a convention, not a guarantee that the image is actually the most recently published version.

docker pull myapp
docker pull myapp:latest

Why Explicit, Full Names Matter

Relying on implicit defaults (no registry, no tag) can lead to ambiguity about exactly what is being referenced, especially across teams or environments where the same short name might be assumed to mean different things — using fully qualified names removes this ambiguity entirely.

docker pull registry.example.com/myteam/myapp:2.3.0

Why Image Naming Conventions Matter

A consistent, well-understood naming scheme is what makes it possible to reason clearly about exactly which image, from which source, at which version, is being referenced in a script, a deployment configuration, or a conversation between team members — ambiguity at this level tends to cause confusing, hard-to-diagnose mistakes later.