Image Tags and Versioning

LEVEL 0

The Problem

You build your application with python:latest. It works great. You deploy to production.

Six months later, you rebuild. python:latest is now Python 3.12, but your code needs Python 3.11. Everything breaks.

Or consider this: your colleague pulls myapp:latest and gets version 2.0. You pull myapp:latest an hour later and get version 2.1 because someone pushed an update. You’re running different versions and don’t even know it.

latest is dangerous. We need proper versioning.

LEVEL 1

The Concept — Library Book Editions

The Concept

Think about books in a library.

“Introduction to Algorithms” isn’t just one book — it’s multiple editions:

First Edition (1990)
Second Edition (2001)
Third Edition (2009)
Fourth Edition (2022)

Each edition has changes — new chapters, corrections, updates. But they’re all “the same book” in some sense.

When you’re taking a course, the professor says “get the 4th edition.” Not just “get the book.” Because specific content matters.

Docker tags work the same way. An image name is like a book title. Tags are like editions.

python:3.9     ← 3.9 "edition"
python:3.10   ← 3.10 "edition"
python:3.11   ← 3.11 "edition"
python:latest ← Whatever the newest is right now

When you deploy to production, you don’t say “use Python.” You say “use Python 3.11.4” — a specific edition.

LEVEL 2

The Mechanics — How Tags Work

The Mechanics

Tag Syntax

Tags are appended to image names with a colon:

imagename:tag

nginx:latest
nginx:1.24
nginx:1.24.0
nginx:1.24-alpine
nginx:stable-alpine3.17

Common Tagging Conventions

Most images follow similar patterns:

Tag Pattern	Meaning	Example
`latest`	Most recent version (dangerous!)	`nginx:latest`
`X`	Major version	`python:3`
`X.Y`	Minor version	`python:3.11`
`X.Y.Z`	Patch version (most specific)	`python:3.11.4`
`X.Y-variant`	Variant of version	`python:3.11-slim`
`alpine`	Alpine Linux base (smaller)	`nginx:alpine`
`slim`	Minimal installation	`python:slim`
`bookworm/bullseye`	Debian release names	`python:3.11-bookworm`

The latest Tag Problem

latest doesn’t mean “newest version.” It means “whatever the publisher tagged as latest.”

Publishers can tag any version as latest. They can change what latest points to at any time. You have no control.

Never use latest in production.

LEVEL 3

Docker's Tag Implementation

Tags Are Pointers

A tag is just a pointer to a specific image ID. Multiple tags can point to the same image:

python:3.11        → sha256:abc123...
python:3.11.4      → sha256:abc123...  (same image!)
python:latest      → sha256:abc123...  (same image... for now)

When a new Python version comes out:

python:3.11        → sha256:abc123...  (unchanged)
python:3.11.4      → sha256:abc123...  (unchanged)
python:3.11.5      → sha256:def456...  (new!)
python:latest      → sha256:def456...  (now points to new version!)

See the problem? python:3.11.4 is stable — it always points to the same image. python:latest is a moving target.

Pulling Specific Tags

docker pull nginx:1.24.0      # Always this exact version
docker pull nginx:1.24        # Latest 1.24.x (might change)
docker pull nginx:1           # Latest 1.x.x (will change)
docker pull nginx             # Same as nginx:latest (dangerous)

Listing Tags for Local Images

docker images nginx

Shows all local nginx images with their tags.

LEVEL 4

Tagging Strategy Best Practices

For Users (Pulling Images):

Development: Minor version tags are fine (python:3.11)
Production: Use exact versions (python:3.11.4-slim-bookworm)
Never: Use latest in production Dockerfiles or deployments

For Publishers (Pushing Images):

Semantic versioning: 1.0.0, 1.0.1, 1.1.0, 2.0.0
Multiple tags: Point 1.0, 1, and latest to appropriate versions
Variant tags: -slim, -alpine for different bases
Immutable tags: Once pushed, never overwrite (except latest)