Docker Image Tagging: Versioning for Containers

WHY IT EXISTS: Docker images are identified by a long, unique SHA256 hash (e.g., sha256:f6e...). These are hard for humans to remember and manage. Tags provide a simple, human-readable way to reference specific image versions, making them easier to distribute and deploy.

THE MENTAL MODEL: Think of a tag as a sticky note on a specific box in a warehouse. The box has a unique, unchangeable serial number (the image ID hash). You can put multiple sticky notes on the same box (e.g., myapp:v1.2 and myapp:latest) or move a sticky note from one box to another (retagging latest from v1.2 to v1.3). The tag is a mutable pointer to an immutable image.

HOW IT WORKS: The command docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] creates a new tag that points to the same image ID as the source. It doesn't create a copy of the image; it just adds another reference. When you run docker pull ubuntu, Docker translates this to docker pull ubuntu:latest by default. The tag latest is just a string; it has no special meaning to the Docker daemon itself.

WHEN TO USE IT: Always use specific tags for your base images in Dockerfiles (e.g., FROM python:3.9-slim) to ensure reproducible builds. Use semantic versioning for your own images (e.g., my-app:1.2.3). This helps track exactly what version of your code is running in a given environment.

WHEN NOT TO USE IT: Avoid using the latest tag in production deployments or CI/CD pipelines. The image that latest points to can change without warning, leading to unexpected failures or behavior drift. For true immutability, pin to a specific version tag (myapp:1.2.3) or, for maximum safety, the image's SHA256 digest.

ONE CANONICAL EXAMPLE: A common workflow is to build an image, tag it with a version number and latest, and then push both tags. First, docker build -t my-app:1.5.0 .. Second, docker tag my-app:1.5.0 my-app:latest. Finally, you would push both tags to your registry. This makes 1.5.0 the specific, stable version, while latest provides a convenient pointer for developers who just want the newest build.