Image Tags: A Movable Name, Not a Version

my-api:1 looks like a version number and behaves like a sticky label you can move.

A tag is the part after the colon in an image name such as my-api:1. It is a name attached to an image, not a property of the image: one image can carry several tags, and a tag can be moved to a different image at any time.

The image itself is identified by its image id, a hash computed from its content: a short fingerprint that would change if any byte of the image changed. Nobody types it. A tag is a label pointed at one of those ids, and pointing it somewhere else is a single command that changes no image:

bash

docker tag my-api:2 my-api:1
docker images my-api
REPOSITORY   TAG   IMAGE ID
my-api       1     3e9f77b21c04
my-api       2     3e9f77b21c04

docker tag my-api:2 my-api:1 moved the name my-api:1 onto the image that my-api:2 already names, so both tags now show the same image id. The image that my-api:1 used to name is still on the machine, now with no tag at all.

So a tag tells you what someone decided to call an image, not what is inside it. When you need to know exactly which image is running, compare image ids rather than tags.

The same holds for images other people publish to a registry, the server such as Docker Hub that stores images for download. node:20 today and node:20 next month can be two different images, because its publishers move that tag to each new release of Node.js 20.

← → move through sections and cards