How it works

The explanation, with examples you can run.

Where differences come from

Most non-reproducibility comes from two places.

Floating inputs. A version range in package.json, a FROM node:24 tag, apt-get install without versions, or a "latest" compiler on the build machine. Each can resolve to something new without any change in your repository. Fix them with lockfiles (package-lock.json, go.sum, poetry.lock), installers that respect them (npm ci, pip install --require-hashes), base images pinned by digest, and toolchains pinned in the repository (.nvmrc, go.mod's toolchain, a pinned builder image).

Noise in the output. Build timestamps baked into binaries or archive entries, files added in whatever order the filesystem returns them, absolute paths of the build directory, the username, random identifiers. The Reproducible Builds project's convention is the SOURCE_DATE_EPOCH environment variable: tools that support it use that fixed time, usually the commit time, instead of "now".

Seeing it

This toy build packs two files into an "archive" and hashes it. With the current time and filesystem order in the archive, every build gets a new digest. With a fixed time and sorted entries, the digest is stable:

Your code

// A toy 32-bit FNV-1a hash standing in for sha256. Not for real use.
function toyHash(text) {
  let h = 0x811c9dc5
  for (let i = 0; i < text.length; i++) {
    h ^= text.charCodeAt(i)
    h = Math.imul(h, 0x01000193) >>> 0
  }
  return h.toString(16).padStart(8, "0")
}

const sources = { "index.js": "console.log('hi')", "util.js": "export const x = 1" }

function build({ time, order }) {
  const entries = order.map((name) => `${name}|mtime=${time}|${sources[name]}`)
  return toyHash(entries.join("\n"))
}

// Noisy: build time and filesystem order end up in the archive.
console.log("noisy 1:", build({ time: 1760000000, order: ["util.js", "index.js"] }))
console.log("noisy 2:", build({ time: 1760000042, order: ["index.js", "util.js"] }))

// Reproducible: a fixed time (like SOURCE_DATE_EPOCH) and sorted entries.
const SOURCE_DATE_EPOCH = 1759900000
const sorted = Object.keys(sources).sort()
console.log("fixed 1:", build({ time: SOURCE_DATE_EPOCH, order: sorted }))
console.log("fixed 2:", build({ time: SOURCE_DATE_EPOCH, order: sorted }))

⌘/Ctrl + Enter

OutputNot run yet

Press Run to see what your code prints, in order.

Runs in this browser, in an isolated frame with no access to this page. console.log, info, warn and error are shown; code runs as a classic script, so use an async function for await.

In a pipeline

Build in a pinned, clean environment: a container image by digest or a hosted runner, never a long-lived machine with leftovers.
Install from the lockfile only and fail if it would change.
Set SOURCE_DATE_EPOCH from the commit time (git log -1 --format=%ct).
Record the artifact's digest and deploy by digest.

How far to go

Perfect reproducibility can take real effort, especially for native code. Even partway helps: pinned inputs alone remove most "it built differently in production" surprises. Full reproducibility is what lets independent builders verify each other, the strongest check against a compromised build machine.

Check yourself

3 questions. Get them all right to finish this topic.

1.A Dockerfile starts with `FROM node:24`. Why can the same commit build different images next month?
2.Two builds of the same commit produce tarballs with different hashes. The files inside are identical. What is the most likely cause?
3.What does `npm ci` do that `npm install` does not?

0 of 3 right so far. Get all three to finish this topic.

Reproducible builds