Pin Docker base images by digest for repeatable builds
Short answer: A Dockerfile that starts with FROM node:22 or FROM python:3.13-slim can build a different image next week than it does today, because tags can be moved to newer images. If you need builds you can repeat exactly, pin the base image by digest, for example FROM alpine:3.21@sha256:..., so every build uses the same bytes. Then let an automated tool such as Dependabot raise pull requests to update the digest on a schedule, so you still get security fixes, deliberately and with a record.
Why tags drift
Docker's build best-practices guide puts it directly: image tags are mutable, meaning a publisher can update a tag to point to a new image. That's useful, because rebuilding picks up fixes automatically. It also means:
- A build that worked on Friday fails on Monday with no code change, because the base image moved.
- Two servers built a day apart run slightly different system libraries.
- A bug appears in production that nobody can reproduce from the same commit, because the image underneath changed.
- Rolling back to an old commit doesn't roll back the base image.
For small teams, these mysteries eat days. The cause is invisible in the code: the Dockerfile line didn't change, but what it refers to did.
What a digest is
Every image has a content digest, a SHA-256 hash of its manifest, written as sha256: followed by 64 hexadecimal characters. Docker's pull documentation describes pulling by digest as using an immutable identifier: the same digest always means the same image.
You can combine a tag and digest in a FROM line. The best-practices guide shows FROM alpine:3.21@sha256: plus the hash, and explains that even if the publisher updates the 3.21 tag, your builds keep using the pinned image. The tag stays in the line for humans to read; the digest is what Docker uses.
Finding the digest
- Pull the image and run
docker images --digeststo show digests next to tags. - Use
docker buildx imagetools inspect <image:tag>to see the digest without pulling, including details for multi-platform images. - Copy the digest from your registry's web page for that tag.
For images published for several CPU architectures, the tag points to an index covering all platforms. Pin the index digest, which is what tools usually show for a multi-platform tag, so builds on different machines each get the right variant.
The trade-off: staying up to date
The guide is candid about the downside: pinning helps you avoid unexpected changes, but it's more tedious to look up and include digests by hand. On top of that, a pinned image won't pick up security fixes by itself. The answer is automation.
The same guide recommends GitHub's Dependabot with the docker package ecosystem, which raises pull requests to update base image tags and digests on a schedule. It argues this is better than an automatically moving tag, because you're in control and you have an audit trail of when and how each change happened. Renovate and similar tools offer the same for other hosts.
A sensible routine:
- Pin every
FROMline by digest, including those in multi-stage builds. - Enable automated update pull requests for Docker images, weekly or so.
- Let CI build and test each update pull request.
- Merge promptly, especially when updates carry security fixes.
- Rebuild and redeploy after merging, so running containers actually pick up the new base.
Pin the rest too
A fixed base image doesn't make the build fully repeatable if later steps fetch moving targets:
- System packages installed with
apt-get installwithout versions change over time. - Language dependencies should be installed from a lock file, such as
package-lock.json,poetry.lockorcomposer.lock. - Downloaded tools fetched by URL should use specific versions and, ideally, checksum checks.
Pin what matters most for your app, and accept that some system package drift may be fine if your update process rebuilds regularly.
Record what you're running
Pinning also makes your deployments easier to describe. Because the digest is in the Dockerfile, every commit records exactly which base image it used, and your release notes or deploy logs can show it. When a security advisory names an affected base image, you can search your repositories for the digest and know within minutes which services need rebuilding, instead of guessing which servers pulled the tag before or after a change.
When not to pin
For quick experiments, local development images or throwaway tools, a plain tag is fine. Pin images that build what you deploy to customers, and images used in CI where repeatable results matter.
Signs you need this
- "It worked yesterday" build failures with no code changes.
- Different behaviour between servers deployed on different days.
- Security reviews or customers asking how you control what goes into your containers.
- Rollbacks that don't fully restore the previous behaviour.
A worked example
Consider a hypothetical Perth logistics software company whose nightly builds started failing intermittently. The Dockerfile used FROM python:3.12-slim, and a recent base update had changed a system library one of its PDF tools relied on. The team pinned the base image by digest to the last known working image, fixed the PDF tool's dependency, and enabled Dependabot updates for Docker images so each new base came as a reviewed pull request. Builds became repeatable, and the next base update arrived as a pull request that CI tested before anyone merged it.
FAQ
Does pinning by digest stop me getting security fixes?
Only if you never update it. Automated update pull requests keep you current on your own schedule.
Is a specific version tag like 3.21.2 enough?
It's better than a broad tag, but publishers can still rebuild and move it. Only a digest is fixed.
Will the digest change if I pull on a different machine?
No. The same digest refers to the same image everywhere.
Should I pin images in docker compose files too?
Yes, for images you run in production. The same digest syntax works there.
If unpredictable builds are slowing your team down, tell us how your images are built and we'll help make them repeatable.