Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 111 ยท Images

Tags and Registries

Learn how Docker image names work: registry, repository, tag and digest. Tag images, push them to a registry, pull them back, and avoid the latest-tag trap.

Every image you have used so far had a name like alpine:3.22 or nginx. That name is not a label stuck on the image. It is an address: it says which registry to ask, which repository to look in, and which tag (or exact digest) to fetch. Once you understand how the address is built, docker tag, docker push and docker pull stop being magic words and become three small operations on a simple naming scheme.

In this lesson you will take apart an image reference, give one image several names, run your own small registry on your machine, push an image to it and pull it back. You will also see why the tag latest causes more production incidents than almost any other word in Docker.

Anatomy of an image reference

A full image reference has up to four parts:

TEXT
  registry.example.com:5000 / team / web-app : 1.4.2 @ sha256:9f2c...
  \_______________________/   \__/   \_____/   \___/   \__________/
        registry host        namespace repo     tag       digest
        (optional)           (optional)         (optional) (optional)
        \______________ repository name _____/
  • The registry is the server that stores images. If you leave it out, Docker uses Docker Hub (docker.io).
  • The namespace is usually a user or organization name (team). Official images on Docker Hub live in the special namespace library.
  • The repository is the image's name (web-app). The registry keeps one repository per image and stores many versions inside it.
  • The tag picks a version inside the repository. If you leave it out, Docker uses latest.
  • The digest pins one exact, immutable image. You will meet it later in this lesson.

Docker fills in the missing pieces for you. These four commands ask for exactly the same image:

Terminal
docker pull alpine
docker pull alpine:latest
docker pull library/alpine:latest
docker pull docker.io/library/alpine:latest

You can see the long form in Docker's own output. After docker pull alpine:3.22, the last line of the output is the fully qualified name:

CONSOLE
$ docker pull alpine:3.22
3.22: Pulling from library/alpine
Digest: sha256:2e0b81d60597f449baa56dc25d355367869d2dca4cd57e866f1e2b52af3eb55f
Status: Image is up to date for alpine:3.22
docker.io/library/alpine:3.22

How does Docker know that the first part of a name is a registry host and not a namespace? A registry host contains a dot or a colon, or is exactly localhost. So team/web-app means "namespace team on Docker Hub", while localhost:5000/web-app and registry.example.com/web-app point at other servers.

docker tag: more names for the same image

A tag is a pointer from a name to an image. docker tag SOURCE TARGET does not copy anything. It adds one more name that points at the same image, so it is instant and costs no disk space.

CONSOLE
$ docker tag alpine:3.22 demo-app:1.0
$ docker tag alpine:3.22 demo-app:latest
$ docker images demo-app --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}'
REPOSITORY   TAG       IMAGE ID
demo-app     1.0       2e0b81d60597
demo-app     latest    2e0b81d60597

Both names show the same image ID, because they are the same image. Removing a name only removes the pointer. The image itself is deleted when its last name is gone and no container uses it:

CONSOLE
$ docker rmi demo-app:latest
Untagged: demo-app:latest
$ docker images demo-app --format '{{.Tag}}'
1.0

docker rmi said Untagged, not Deleted, because demo-app:1.0 and alpine:3.22 still point at the image.

Name rules

Docker checks names strictly, and the error messages are clear once you know the rules:

  • Repository names must be lowercase. They may contain lowercase letters, digits, and the separators ., _, - and /.
  • A tag may contain letters (upper or lower case), digits, _, . and -. It cannot start with a period or a dash, and it can be at most 128 characters long.
CONSOLE
$ docker tag alpine:3.22 localhost:5000/Team/x
error parsing reference: "localhost:5000/Team/x" is not a valid repository/tag: invalid reference format: repository name (Team/x) must be lowercase
$ docker tag alpine:3.22 demo-app:bad/tag
error parsing reference: "demo-app:bad/tag" is not a valid repository/tag: invalid reference format

The cause is always one of two things: uppercase in the repository name, or a character that is not allowed in a tag. A slash cannot be part of a tag.

Run a registry on your machine

The best way to understand push and pull is to use a registry you control. Docker Hub's open-source registry server is itself an image called registry. Start one and publish it only on your own machine:

CONSOLE
$ docker run -d --name registry -p 127.0.0.1:5000:5000 registry:2

The registry is now listening on localhost:5000. Docker treats localhost registries as a special case: it allows plain HTTP to them without any extra configuration. Any other registry must use HTTPS (or be listed in the daemon's insecure-registries setting, which you should avoid).

To push an image to a registry, its name has to start with that registry's address. That is the whole trick: you cannot tell docker push "send this to localhost", you give the image a name that already contains the destination.

CONSOLE
$ docker tag alpine:3.22 localhost:5000/team/demo-app:1.0
$ docker push localhost:5000/team/demo-app:1.0
The push refers to repository [localhost:5000/team/demo-app]
63e7e49699e8: Unavailable
63e7e49699e8: Pushed
1.0: digest: sha256:dc92f017beea... size: 1022

The first Unavailable line is Docker noting that the registry does not have that layer yet. The push then sent each layer the registry did not already have (here a single layer) and then a small JSON manifest that lists the layers and the image configuration. The line 1.0: digest: sha256:... size: 1022 reports the digest of that manifest. Push the same image again and every layer reports Layer already exists, so nothing is uploaded twice.

The registry has a small HTTP API, which makes it easy to check what it stores:

CONSOLE
$ curl -s http://localhost:5000/v2/_catalog
{"repositories":["team/demo-app"]}
$ curl -s http://localhost:5000/v2/team/demo-app/tags/list
{"name":"team/demo-app","tags":["1.0"]}

Now delete the local copy and pull it back from the registry, to prove that the registry really holds the image:

CONSOLE
$ docker rmi localhost:5000/team/demo-app:1.0
Untagged: localhost:5000/team/demo-app:1.0
Deleted: sha256:dc92f017beea...
$ docker pull localhost:5000/team/demo-app:1.0
1.0: Pulling from team/demo-app
Digest: sha256:dc92f017beea...
Status: Downloaded newer image for localhost:5000/team/demo-app:1.0
localhost:5000/team/demo-app:1.0

To push several tags at once, tag them all and use --all-tags. In our test, pushing 1.0 and stable and then listing the registry's tags gave {"name":"team/demo-app","tags":["1.0","stable"]}.

On Docker Desktop (which uses the containerd image store) you may see an extra block after a push, starting with Info -> Not all multiplatform-content is present and only the available single-platform image was pushed. It means the local copy of that image only contains your machine's CPU architecture, so that is all that was uploaded. It is harmless here. Multi-platform images are covered in Multi-Platform Images.

Digests: the name that cannot move

A tag is a movable pointer: the owner of a repository can point 1.0 at a different image tomorrow. A digest is the SHA-256 hash of the image manifest, so it identifies exactly one image forever. If a single byte changes, the digest changes.

You can see digests next to tags with --digests:

CONSOLE
$ docker image ls --digests localhost:5000/team/demo-app
REPOSITORY                TAG   DIGEST              IMAGE ID       CREATED       SIZE
localhost:5000/team/demo-app   1.0   sha256:dc92f017...   dc92f017beea   41 hours ago   12.8MB

(Columns shortened for the page.) To use a digest, add @sha256:... after the repository name. Docker pulls by that digest and refuses anything else:

CONSOLE
$ docker run --rm localhost:5000/team/demo-app@sha256:dc92f017beea... echo hi
Unable to find image 'localhost:5000/team/demo-app@sha256:dc92f017beea...' locally
...
Status: Downloaded newer image for localhost:5000/team/demo-app@sha256:dc92f017beea...
hi

Pinning by digest is how you get reproducible deployments: FROM python:3.13-slim@sha256:... always builds on the same base, even if the maintainers re-publish 3.13-slim next week with security fixes. The cost is that you must update the digest yourself, ideally with an automated tool. Image Security and Scanning and Tagging and Versioning Strategies return to this trade-off.

The digest you see in docker push output may differ from the "image ID" you see locally. On the containerd image store the local ID can be the digest of a multi-platform index, while the registry received the manifest for your platform only. When you want a digest that is valid on the registry, copy it from the push output or from docker image ls --digests for the registry-named image.

Docker Hub and other registries

Docker Hub is the default registry and the home of the official images (alpine, nginx, postgres...). Anyone can read public repositories without an account, but pushing requires you to be logged in, and your repository name must start with your Docker Hub username or organization:

Terminal
# read-only example: needs a Docker Hub account
docker login
docker tag demo-app:1.0 yourname/demo-app:1.0
docker push yourname/demo-app:1.0

If you forget the username prefix, Docker tries to push to docker.io/library/demo-app, which you do not own, and the registry answers denied: requested access to the resource is denied. If you are not logged in, you get the same message. Other registries work the same way, with their own host name in front: ghcr.io/yourname/demo-app:1.0 for GitHub, registry.example.com/team/demo-app:1.0 for a company registry. Working with Registries covers logins and credential helpers, and Running a Private Registry goes deeper into the server you just started.

The latest pitfall

latest is not magic. It is an ordinary tag with a special job: it is what Docker uses when you do not give a tag. It does not mean "the newest version". It means "whatever the person who pushed last decided to call latest". Watch how easily it moves:

CONSOLE
$ docker tag alpine:3.22 demo-app:latest
$ docker images demo-app --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}'
REPOSITORY   TAG       IMAGE ID
demo-app     latest    2e0b81d60597
$ docker tag busybox:1.37 demo-app:latest
$ docker images demo-app --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}'
REPOSITORY   TAG       IMAGE ID
demo-app     latest    bdf57e528e45

The same name now points at a completely different image. Two servers that ran docker pull demo-app a day apart can end up running different code, and nothing in the command tells you. Rules of thumb that avoid the trap:

  1. Never deploy latest. Deploy an explicit version (1.4.2) or a digest.
  2. When you build and publish your own images, always push a specific version tag. If you also publish latest, treat it as a convenience for humans.
  3. Remember that docker pull is what makes a tag current. docker run demo-app uses the local copy if one exists, even if the registry has a newer latest.

When to use what

You want to... Use
Try something quickly A short tag like nginx:1.27-alpine
Deploy to production A full version tag, ideally also pinned by digest
Share with your team A registry-qualified name such as registry.example.com/team/app:1.4.2
Be sure nobody can swap the image @sha256: digest

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does docker tag alpine:3.22 demo-app:1.0 do?

    A tag is only a pointer. Both names refer to the same image ID, so no data is copied and the old name keeps working.
  2. 2. Which reference tells Docker to talk to a registry running on your own machine on port 5000?

    The first path component is treated as a registry host when it contains a dot or a colon, or is localhost. Without it, Docker uses Docker Hub.
  3. 3. Why is it risky to deploy an image by the tag latest?

    latest is just a tag that anyone with push access can move. Deploying a version tag or a digest makes the result predictable.
  4. 4. What is special about an image digest such as @sha256:dc92...?

    A digest is the hash of the image manifest, so it is immutable. That makes it the safest way to pin an image.
  5. 5. You run docker push demo-app:1.0 and Docker tries to push to docker.io/library/demo-app. How do you push to your own registry at localhost:5000 instead?

    The registry address is part of the image name. docker push has no separate destination option, so you tag the image with the destination first.

Summary

  • An image reference is [registry/][namespace/]repository[:tag][@digest]. Missing parts default to Docker Hub, the library namespace and the tag latest.
  • docker tag adds a name for an existing image. It copies nothing, and docker rmi on one name only removes that name.
  • To push, give the image a name that starts with the registry's address; localhost registries may use plain HTTP, all others need HTTPS.
  • Repository names are lowercase; tags allow letters, digits, _, . and - (up to 128 characters).
  • A digest is the immutable hash of a manifest; use @sha256: to pin an image exactly.
  • latest is a normal, movable tag. Deploy explicit versions or digests instead.

Next: Save, Load, Export, Import