4.2.1.4 FROM Digest Pin

A FROM digest pin specifies a base image by its exact content digest rather than by a tag, guaranteeing that a build always starts from precisely the same base image content, regardless of whether the tag it would otherwise correspond to has since been reassigned upstream.

Why Tags Alone Are Not Fully Reliable for Reproducibility

A tag like python:3.12-slim can, in principle, be reassigned by its maintainers to point at different underlying content over time — perhaps to apply a security patch — meaning a build performed today and the same build performed next month could start from subtly different base content despite an unchanged Dockerfile.

FROM python:3.12-slim

Pinning to an Exact Digest

Specifying the digest alongside (or instead of) the tag removes this ambiguity entirely, since a digest can never correspond to anything other than the exact content it was computed from.

FROM python:3.12-slim@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Every build using this Dockerfile starts from precisely this base content, with no possibility of drift caused by the tag being reassigned upstream.

Finding the Digest to Pin

The digest corresponding to a currently available tag can be looked up directly, providing the exact value to pin in a Dockerfile.

docker pull python:3.12-slim
docker inspect python:3.12-slim --format '{{index .RepoDigests 0}}'

Updating a Pinned Digest Deliberately

Because a pinned digest never changes automatically, intentionally moving to a newer base image version requires explicitly updating the digest in the Dockerfile, which is a deliberate, reviewable change rather than something that happens silently on its own.

docker pull python:3.12-slim
docker inspect python:3.12-slim --format '{{index .RepoDigests 0}}'

Updating the Dockerfile with this newly retrieved digest is then a normal, version-controlled code change, subject to the same review process as any other.

Why Digest Pinning for FROM Matters

Pinning the base image by digest is one of the most effective single steps toward making a build fully reproducible, removing the base image itself as a potential, hard-to-detect source of variation between builds performed at different times.