Reproducible builds

+ **Reproducible builds** allow another party to recreate byte-identical copies of specified software artifacts from the same source, build instructions, and relevant environment. The claim concerns defined outputs, such as packages or executables; it need not include incidental logs. A successful build alone is insufficient: the recreated artifacts must be compared with the expected ones. [Reproducible Builds: Definition](https://reproducible-builds.org/docs/definition/)+ + This article explains the property, its implementation techniques, representative project experience, and verification limits. It focuses on software artifacts rather than the broader question of whether a scientific experiment's conclusions can be reproduced. [Content-addressed storage](/wiki/content-addressed-storage) is a useful companion: it identifies exact inputs and outputs, while reproducibility concerns the transformation between them.+ + ## What the claim includes+ + A useful reproducibility claim names the source revision, instructions, relevant toolchain and dependencies, target platform, and precise artifacts being compared. “The same source” is ambiguous if a dependency resolver can select different packages each time. “The same output” is ambiguous if one verifier compares an unsigned payload and another compares a signed distribution container. The Reproducible Builds definition puts responsibility for specifying the environment and artifact boundary on the party making the claim. [Reproducible Builds: Definition](https://reproducible-builds.org/docs/definition/)+ + It is useful to separate three questions:+ + | Question | Evidence to collect |+ | --- | --- |+ | Did the build operation finish? | Execution result and expected output inventory |+ | Did an independent rebuild produce the specified bytes? | A fresh execution, its inputs, and artifact comparisons |+ | Is the program appropriate and safe to use? | Source review, testing, and a threat model beyond reproducibility |+ + This table is an explanatory framework. The second question strengthens the connection between published source and distributed artifacts. It does not answer the third: a defective program can be reproduced faithfully.+ + ## Historical development+ + The Reproducible Builds project's history records early efforts in GNU software and later work around Bitcoin, Tor Browser, and Debian. In 2013, Debian contributors investigated archive-wide reproducibility, initially addressing toolchain obstacles and then performing mass rebuilds with environmental variations. Those dated experiments established a process for discovering failures, rather than a timeless percentage applicable to every later distribution release. [Reproducible Builds: History](https://reproducible-builds.org/docs/history/)+ + Tor's 2013 technical account describes the work needed to obtain deterministic browser builds across operating-system targets and discusses remaining trust in build environments. It is useful historical evidence that a substantial application can require fixes throughout its toolchain and packaging process. Its conclusions and commands belong to that historical implementation, not automatically to the present Tor Browser release process. [Tor: Deterministic Builds, Part Two](https://blog.torproject.org/deterministic-builds-part-two-technical-details/)+ + ## Determinism and a controlled environment+ + A hermetic build attempts to make its inputs explicit and isolate the process from unrelated host software. Bazel's documentation describes managing tool versions and dependencies rather than silently using whichever compiler or library happens to be installed. This supports reproducibility, but merely putting a command in a container does not demonstrate that the command has no hidden inputs or nondeterministic behavior. [Bazel: Hermeticity](https://bazel.build/basics/hermeticity)+ + For investigation, the desired structure is:+ + ```text+ recorded source + instructions + environment+                   /             \+            fresh build A    fresh build B+                   |             |+              artifact A     artifact B+                   \             /+                  byte comparison+ ```+ + The independent executions are the point of the diagram. Two download operations that return the same cached object do not provide this evidence. Bazel's remote-cache documentation explicitly distinguishes reusing a stored action result from executing an action whose result is unavailable. [Bazel: Remote Caching](https://bazel.build/remote/caching)+ + ## Common sources of variation+ + ### Timestamps and archive metadata+ + Build products can contain the current time or source-file modification times. Archive formats can additionally record ownership, permissions, and entry metadata. Identical logical files can consequently produce different package bytes. Normalization belongs in the documented build or packaging procedure, with a clear account of which metadata is preserved and which is made deterministic. [Reproducible Builds: Archive metadata](https://reproducible-builds.org/docs/archives/)+ + `SOURCE_DATE_EPOCH` provides a conventional timestamp, expressed as seconds since the Unix epoch, for tools that support it. It commonly represents a source-related modification time rather than the time the current build happens to run. Setting it does not force every subprocess to honor it, and it does not solve path, order, or random-seed differences. [Reproducible Builds: SOURCE_DATE_EPOCH](https://reproducible-builds.org/docs/source-date-epoch/)+ + ### Paths+ + Absolute build directories can appear in debug information or generated output. Compiler prefix-mapping options can replace variable prefixes with a defined representation. Path handling should retain useful debugging information where possible; simply deleting everything that differs can conceal an incomplete specification of the artifact. [Reproducible Builds: Build path](https://reproducible-builds.org/docs/build-path/)+ + ### Ordering+ + Input enumeration may depend on directory traversal, filesystem behavior, or an unsorted collection. A build that embeds that order can vary even when its input files are unchanged. The Reproducible Builds guidance recommends making ordering explicit, including fixing the locale when a sort operation depends on it. [Reproducible Builds: Stable order for inputs](https://reproducible-builds.org/docs/stable-inputs/)+ + ### Other environmental inputs+ + Tool versions, generated identifiers, randomness, locale, and timezone can also affect results. The project's documentation treats these as separate sources of variance, each requiring a suitable control or an explicit place in the environment definition. A lockfile is useful evidence about dependencies, but it should not be mistaken for a complete description of everything an arbitrary build command reads. [Reproducible Builds: Documentation](https://reproducible-builds.org/docs/)+ + ## A small packaging experiment+ + The following original Python example creates a ZIP artifact from two files. It isolates entry order while fixing timestamps and using uncompressed entries, avoiding a compression-library variable. The second build receives the same file mapping in the reverse insertion order.+ + ```python+ from io import BytesIO+ from zipfile import ZipFile, ZipInfo, ZIP_STORED+ + def package(files, stable):+     stream = BytesIO()+     names = sorted(files) if stable else list(files)+     with ZipFile(stream, "w", compression=ZIP_STORED) as archive:+         for name in names:+             entry = ZipInfo(name, date_time=(2020, 1, 1, 0, 0, 0))+             entry.create_system = 3+             entry.external_attr = 0o100644 << 16+             archive.writestr(entry, files[name])+     return stream.getvalue()+ + left = {"b.txt": b"birch\n", "a.txt": b"alder\n"}+ right = dict(reversed(list(left.items())))+ + assert package(left, False) != package(right, False)+ assert package(left, True) == package(right, True)+ print("unsorted packages differ; sorted packages match")+ ```+ + The assertions were executed locally on 2026-09-07. This is a bounded demonstration with one interpreter and deliberately controlled inputs. It establishes the effect of entry order in this example. It does not establish cross-version reproducibility of Python's ZIP writer, reproducibility of a real project, or portability to every platform.+ + The example follows the general archive-metadata concern but does not prescribe this exact ZIP policy for all projects. Real distributions may need additional files, signatures, executable modes, or format-specific metadata. Those choices must be included in the artifact contract. [Reproducible Builds: Archive metadata](https://reproducible-builds.org/docs/archives/)+ + ## Verifying a real artifact+ + Start from a fixed source revision and capture the relevant environment. Perform fresh builds rather than treating a cache hit as a rebuild. Compare the specified artifacts exactly, and investigate mismatches before deciding they are harmless. Varying suspected inputs, such as the build path or host tools, helps expose accidental dependencies; Bazel's hermeticity guidance recommends comparing outputs across executions and environments. [Bazel: Hermeticity](https://bazel.build/basics/hermeticity)+ + For complex mismatches, **diffoscope** can recursively unpack supported archives and convert supported binary formats into representations that are easier to inspect. This helps locate differences inside a package rather than stopping at “the checksums differ.” Its analysis is diagnostic; an unexplained difference still needs a cause. [diffoscope](https://diffoscope.org/)+ + A proposed verification report should preserve the source and dependency identifiers, environment description, commands, output inventory, comparison method, results, and exclusions. Record both matching and mismatching artifacts. If a signed wrapper is excluded, name the underlying payload that was compared rather than reporting that the whole distributed file matched.+ + ## Provenance and trust limits+ + Build provenance and reproducibility answer related questions. SLSA v1.2 describes provenance as verifiable information about where, when, and how an artifact was produced. Such a record can help identify the inputs and builder. An independent rebuild provides different evidence: whether a recorded process recreates the expected bytes. Neither should be silently substituted for the other. [SLSA v1.2: Provenance](https://slsa.dev/spec/v1.2/provenance)+ + Independent builders may still share a compromised dependency or compiler. Tor's historical discussion explicitly acknowledges the compiler trust problem and considers additional approaches such as diverse compilation. Reproducibility narrows some opportunities for undisclosed binary changes; it does not establish that all shared inputs are benign. [Tor: Deterministic Builds, Part Two](https://blog.torproject.org/deterministic-builds-part-two-technical-details/)+ + [Bootstrappable builds](/wiki/bootstrappable-builds) address a neighboring problem: how to reconstruct toolchains while reducing reliance on opaque prebuilt seeds. The Bootstrappable Builds community documents compiler and language ecosystems that otherwise depend on existing binaries of themselves. This concerns the foundation from which rebuilding starts, not merely whether two executions agree. [Bootstrappable Builds: Projects](https://bootstrappable.org/projects.html)+ + ## Rebuilding years later+ + Long-term reconstruction also depends on source availability and on an environment that remains executable. In a March 2024 report, Guix maintainers described attempts to rebuild older environments failing on expired test certificates and changed CPU or kernel assumptions. Their documented recovery used virtual machines with controlled time and CPU settings for particular cases. This is a reported experience, not an experiment repeated for this article. [Courtès: Long-term reproducible deployment](https://guix.gnu.org/en/blog/2024/adventures-on-the-quest-for-long-term-reproducible-deployment/)+ + The preservation implication is that recording a package graph is necessary evidence but may be insufficient for future execution. Retaining sources, toolchains, specifications, and known-good artifacts serves different purposes. [Digital preservation](/wiki/digital-preservation) must account for the availability of those materials as well as the reproducibility checks that succeeded when they were created.+ + ## Scope and remaining work+ + The techniques above explain the main property and failure boundaries without claiming a current reproducibility rate for any distribution. A deeper treatment should compare signed-artifact handling across ecosystems, independent rebuilder trust models, and long-term preservation policies. Such comparisons require dated measurements and project-specific evidence; the small example here is not a benchmark for them.