A reproducible build gives the same output bytes from the same inputs, no matter when or where it runs. SOURCE_DATE_EPOCH is a standard environment variable that gives build tools a fixed timestamp, which removes one common reason two builds differ. It is necessary for many builds, but not enough on its own.
Why bit-for-bit matters
If two independent parties build the same source and get identical output, they can compare hashes and gain confidence that nobody tampered with the result. If builds differ every time, you cannot tell harmless noise from a change someone slipped in.
For images, there is a second reason: digests. A digest is a hash of content. If timestamps change inside layers on every build, the digest changes on every build, even when nothing meaningful did. That breaks caching, makes signatures noisier, and makes "did this image change?" hard to answer.
What the variable is
The Reproducible Builds documentation describes SOURCE_DATE_EPOCH as a standardised environment variable that lets distributions set a single timestamp for a build. Tools read it so their output does not change from run to run. It holds a count of seconds since the Unix epoch, usually marking when the source was last modified.
Many tools embed the current time in what they produce. The page notes that adjusting the system clock is not enough, since long builds can finish at different times. The variable tells the tool to execute the build as if the current time were the given value. Some tools, including CMake, GCC and Sphinx, already support it, while others may need patching.
What else breaks reproducibility
Timestamps are one cause. Others include:
- File ordering. Archives built from a directory listing in a different order.
- Unpinned inputs. A base image tag or package that moves between builds.
- Embedded paths or hostnames from the build machine.
- Random values such as generated IDs.
- Network fetches that return different content.
- Different tool versions across machines.
For container images, pinning the base image by digest and pinning package versions removes the input drift. Layer metadata, such as creation time in the image config, is another place a timestamp hides. Check whether your build tool offers a way to set it from the same value.
A practical approach
- Pin every input you can: base image digest, package versions, tool versions.
- Set a fixed timestamp in CI from the commit time, not the current time.
- Build the same commit twice on different machines.
- Compare image digests. If they differ, compare layer by layer and fix the first difference.
- Repeat until the digests match, then keep a check running.
Expect this to take effort. Some ecosystems are easier than others, and you may stop at "mostly reproducible", which still helps debugging.
How it connects to supply chain security
Reproducibility pairs with provenance. Provenance says which builder produced an artifact from which inputs. A reproducible build lets a second builder confirm the claim. See signatures, provenance and SBOMs.
Safeguard's SBOM and dependency scanning records what went into an image so you can compare builds, and a free scan is an easy place to start.
Quick check
Does setting the variable make my image reproducible?
It removes timestamps from tools that honor it. Unpinned inputs, file ordering and other sources can still cause differences.
What value should I use?
A common choice is the last commit time of the source, since it is the same for every rebuild of that commit.
Sources
Last reviewed: 19 October 2026.
