9.3.2.3 Compose Registry Image Tag

A Compose registry image tag identifies a specific version of an image hosted in a container registry — Docker Hub or a private registry — referenced through a service's image field, with the chosen tag determining exactly which version of that image Compose pulls and runs.

Referencing a Specific Registry Tag

The tag, appended after a colon to the image name, selects a specific version from the registry.

services:
  db:
    image: postgres:16.2

This pulls specifically version 16.2 of the official postgres image, rather than whatever the mutable latest tag happens to currently point at.

Why Avoiding the Latest Tag Is Generally a Good Practice

The latest tag's actual content can change over time as a new version is published under that same tag name, meaning a deployment relying on latest might unexpectedly receive a different, untested version at some point without any explicit change to the Compose file itself.

services:
  db:
    image: postgres:latest

services:
  db:
    image: postgres:16.2

The second, explicitly versioned reference provides a far more predictable, reproducible deployment than the first.

Referencing an Image From a Private Registry With a Specific Tag

A private registry's image is referenced the same way, with the registry's address prefixed to the image name.

services:
  api:
    image: registry.example.com/myteam/api:2.3.0

Pulling a Specific Tag Explicitly

Confirming a specific tag is actually available, and pulling it ahead of time, can be useful before relying on it in a deployment.

docker compose pull db

Why Compose Registry Image Tags Matter

Deliberately referencing specific, meaningful registry tags — rather than a mutable default like latest — is an important practice for ensuring a Compose application's deployments are predictable and reproducible, with the exact version of every dependency clearly and explicitly recorded in the Compose file itself.