4.2.1.1 FROM Base Reference

The FROM base reference is the specific image name, tag, or digest that follows the FROM keyword, determining exactly which base image content a build starts from, and the precision of this reference directly affects how predictable and reproducible the resulting build will be.

Referencing by Tag

The most common form references a base image by its repository name and a tag, which is convenient and readable but can correspond to different actual content over time if that tag is later reassigned upstream.

FROM python:3.12

This always resolves to whatever content the 3.12 tag currently points to at the time of the build, which may not be the exact same content it pointed to in a previous build.

Referencing by a More Specific Tag

A more specific tag, including the exact patch version, narrows the range of content this reference could possibly resolve to, though it can still theoretically be reassigned if the upstream maintainer chooses to do so.

FROM python:3.12.3-slim

Referencing by Digest for Full Precision

Referencing a base image by its content digest removes any ambiguity entirely, guaranteeing the exact same base image content is used regardless of when or where the build happens.

FROM python:3.12.3-slim@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

This is the most reproducible form of base reference possible, since a digest cannot be reassigned to different content.

Choosing the Right Level of Precision

For local development, a more general tag is often convenient, automatically picking up minor updates; for production builds where reproducibility matters significantly, pinning by digest, or at minimum a specific patch version, is generally the safer choice.

docker inspect python:3.12.3-slim --format '{{.Id}}'

Recording the resolved digest of a tag actually used in a build provides a way to later verify or reproduce the exact base content that build relied on.

Why the Precision of the FROM Reference Matters

The level of precision chosen for the FROM base reference directly trades off convenience against reproducibility — understanding this tradeoff, rather than defaulting unthinkingly to the most convenient option, is important for any build where consistent, predictable results matter.