3.2.3.2 Immutable Digest References
A focused guide to Immutable Digest References, connecting core concepts with practical Docker and container operations.
Immutable digest references use an image's content digest, rather than a tag, as the way of referring to it in any context where being absolutely certain about exact content matters more than the convenience of a human-readable name.
Why a Digest Reference Cannot Drift
A digest is computed directly from an image's content, so a reference using that digest can only ever resolve to the exact content it was computed from — there is no operation that reassigns a digest to point at different content, unlike a tag.
docker pull myapp@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
This command, run at any point in the future, against any registry mirror that has the content, returns exactly the same image every time.
Where Immutable References Matter Most
Anywhere a system needs a guarantee that it is running exactly the content that was tested or approved — production deployment manifests, security-sensitive infrastructure, audited environments — benefits from referencing images by digest rather than by a tag that could theoretically be reassigned.
containers:
- name: myapp
image: registry.example.com/myapp@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
A deployment manifest written this way leaves no ambiguity about exactly which image content is being deployed, regardless of what any tag currently points to.
Recording Digests Alongside Tags
A practical pattern is to deploy using a version tag during development for convenience, but to record and pin the resulting digest once a release is finalized, capturing an immutable reference to exactly what was validated.
docker inspect myapp:2.3.0 --format '{{index .RepoDigests 0}}' >> release-manifest.txt
Why Immutable Digest References Matter
Relying on digest references wherever exact content matters removes an entire category of risk — the possibility that a tag was unintentionally or maliciously reassigned between when an image was validated and when it was actually deployed — replacing trust in a mutable label with a verifiable, content-derived guarantee.