Every image has an ID (a hash of its config) and zero or more names. A name is a that says where the image lives and which version it is.
The parts of a reference
registry.pier.internal/pier/status-page:1.0.0
└─────────┬──────────┘ └──────┬───────┘ └─┬─┘
registry repository path tag| Part | Example | Default when omitted |
|---|---|---|
| Registry | registry.pier.internal, localhost:5000, ghcr.io | docker.io (Docker Hub) |
| Repository path | pier/status-page, library/nginx | none, it is required |
| Tag | 1.0.0, stable, 20-alpine | latest |
Docker treats the first component as a registry only when it contains a . or a : port, or is localhost. Otherwise the whole name is a path on Docker Hub.
Short names expand
| You type | Docker uses |
|---|---|
nginx | docker.io/library/nginx:latest |
nginx:1.27 | docker.io/library/nginx:1.27 |
stackmonsters/greeter:1.0 | docker.io/stackmonsters/greeter:1.0 |
localhost:5000/web/nginx:1.27 | registry localhost:5000, path web/nginx, tag 1.27 |
library/ is the namespace for Docker Hub's official images. docker pull prints the expanded name on its last line:
$ docker pull nginx:1.27
1.27: Pulling from library/nginx
Digest: sha256:461e750887eaa9bc4ce2df02120c91f5420bf6f8c99ddd609e212a8f8e65cd96
Status: Downloaded newer image for nginx:1.27
docker.io/library/nginx:1.27Names must be lowercase. Web/Nginx:1 is rejected with invalid reference format.
The name decides where a push goes
docker push localhost:5000/web/nginx:1.27 → registry on this host, port 5000
docker push registry.pier.internal/web/nginx → registry.pier.internal
docker push nginx:1.27 → docker.io/library/nginx (denied)There is no --registry flag. To send an image somewhere, give it a name that starts with that registry.
One image, many names
docker tag SOURCE TARGET adds a name to an existing image. It copies nothing.
docker tag nginx:1.27 localhost:5000/web/nginx:1.27
docker tag nginx:1.27 registry.pier.internal/web/nginx:stable
docker imagesREPOSITORY TAG IMAGE ID CREATED SIZE
nginx 1.27 9c00f3b0b0e0 2 weeks ago 192MB
localhost:5000/web/nginx 1.27 9c00f3b0b0e0 2 weeks ago 192MB
registry.pier.internal/web/nginx stable 9c00f3b0b0e0 2 weeks ago 192MBThree rows, one IMAGE ID, 192MB stored once. List every name of an image with:
docker image inspect -f '{{json .RepoTags}}' nginx:1.27docker rmi on one name only removes that name (Untagged:). The image is deleted when its last name goes.