The same commit builds a different Docker image because the Dockerfile reads things that change: a base image tag that moved, packages fetched at build time, files with new timestamps, or build steps that write the date. Pin the base by digest, control package sources and fix times from the commit.
Four causes, in order of how often they bite
1. The base image tag moved. Docker's guidance says tags are mutable, so a tag can resolve to a different patch release when you rebuild months later. You then have no audit trail of the exact version in use.
2. Packages were fetched at build time. An instruction that updates the package index and installs packages will pick up whatever the index offers that day. The Debian project runs a snapshot archive that works like a wayback machine for its packages, and the reproducible-builds project points to it as a way to recreate a system in the state of a past archive. Whether you use that or an internal mirror, the idea is the same: make the package source stop moving, or accept that it moves.
3. Timestamps got written. The reproducible-builds documentation calls timestamps the biggest source of reproducibility issues. Filesystems and archive formats record modification times on top of any timestamps the tools write.
4. File order and metadata varied. Archives built from directory listings can differ because filesystems do not guarantee listing order. The same documentation shows sorting names in a locale independent way and fixing modification times.
A quick diagnosis
- Build the image twice on the same machine with the cache disabled.
- If the layers differ, find the first layer that differs. Layers are built in order, so everything after it will differ too.
- Compare the contents of that layer, not just the hashes. Listing files with their times and sizes usually shows the culprit.
- Fix that cause, then repeat.
docker build --no-cache -t test:a .
docker build --no-cache -t test:b .
docker history test:a
docker history test:b
Pinning versus the build cache
A warm cache can hide the problem. Docker steps through each instruction and reuses a cached result when it can, so a second build on your machine may look identical simply because it reused layers. Always test with the cache off, and remember that a cache hit on one runner and a miss on another is itself a way for two builds to differ.
What to decide
| Choice | Result |
|---|---|
| Pin base image by digest | Same base every time, you own the update |
| Pin package versions or use a snapshot source | Same packages, more maintenance |
| Accept moving packages, rebuild weekly | Fresher patches, images differ between builds |
| Set timestamps from the commit | Removes the biggest source of noise |
Most small teams should do the first and last, and make a deliberate choice on the middle two.
Where Safeguard fits
Safeguard scans container images, so you can compare findings between two builds of the same commit and see what actually moved. Try a free scan at gold.safeguard.sh/scan.
Quick check
Is a different image hash always a problem?
Not always. It matters when you need to prove what you shipped or roll back to an identical artifact. Know which differences are harmless, such as timestamps, and write them down.
Does turning off the cache make the build reproducible?
No. It helps you see the true differences. You still need to pin the inputs.
Sources
- Docker docs: Dockerfile build guidance
- Reproducible Builds: Volatile inputs can disappear
- Reproducible Builds: Timestamps
- Reproducible Builds: Archive metadata
- snapshot.debian.org
Last reviewed: 19 October 2026.
