For builds you may need to repeat exactly, yes. A tag such as a version name can be moved to different content later, while a digest is a hash of the image content and always identifies the same image. Pin by digest, and pair it with a routine for updating it.
Tag versus digest
Docker's documentation states that tags can be reused or changed, so a name may refer to different content later, and that a digest is immutable. A digest is a SHA-256 hash of the image content. Any change in content produces a different digest.
For multi-platform images, a tag points to a manifest list that references one digest per platform. If you need an exact image for one architecture, use the platform specific digest.
Why this matters for recovery
Imagine rebuilding last quarter's release after an incident. If the Dockerfile says a tag, you get whatever that tag points to today, with different packages and fixes. A bug fix you shipped may not reproduce, or a new vulnerability may appear. With a digest, the starting point is the same bytes as before, as long as the registry still has them.
That last clause matters. A digest does not keep the image alive. If the registry deletes it, the pin fails. Keep a copy of the images you ship in storage you control.
How to pin
- Look up the digest for the tag you use with an image inspection command, or copy it from the registry page.
- Reference the image as name at sha256 and the digest in your Dockerfile or deployment file. You can keep the tag in a comment for readers.
- Record the digest in your release notes or SBOM.
- Copy the image to your own registry.
docker buildx imagetools inspect example/base:1.2
docker pull example/base@sha256:REPLACE_WITH_DIGEST
The cost of pinning
A pinned digest never picks up security fixes by itself. That is the trade: repeatable builds in exchange for a duty to update.
- Run a scheduled job that checks for a newer image for each pin.
- Open an update pull request, build, scan and test it.
- Merge on a regular cadence, and sooner for a serious vulnerability.
Without that routine, digests turn into a slow accumulation of unpatched software.
Decision guide
| Situation | Choice |
|---|---|
| Release builds, regulated builds | Digest, with update job |
| Local experiments | Tag is fine |
| Base image you build yourself | Digest of your own image |
Try it yourself
Click through it at your own pace, or open it full screen.
Notice how findings attach to specific layers. Pinning tells you which layers you have, and scanning tells you what is in them.
Safeguard scans container images and can gate pull requests on the result, so a digest update PR gets checked. Try the free scan.
Quick check
Does a digest prove the image is safe?
No. It proves the content has not changed. Scan the image to learn what is in it.
Can I keep the tag as well?
Yes, as a comment for humans. Builds should use the digest.
Sources
Last reviewed: 19 October 2026.
