repo2docker is a tool that scans a repository for configuration files, such as requirements.txt, and builds a computing environment from them. It automates community practice, but it only makes a repository reproducible when those files pin exact versions. Unpinned files give you a different environment each time.
What the specification says
The repo2docker documentation calls the set of supported files, their contents and the actions taken the Reproducible Execution Environment Specification, or REES. The stated goal is to automate and encourage existing best practices for reproducible computational environments, using community standard files and tools: requirements.txt with pip, Project.toml for Julia, apt.txt for apt, and others.
A design point is worth quoting in spirit. The docs say a human should be able to look at a REES compliant repository and reproduce the environment using clear steps without the repo2docker software. So the files are the record, and the tool is a convenience.
The configuration files must sit in the repository root, in a binder directory or in a dot binder directory.
Where reproducibility can leak
The documentation says a REES compliant tool will install a Python interpreter of unspecified version and perform the equivalent of pip install with the requirements file. That wording matters. If you do not state the Python version and the package versions, you have not fixed them.
| Input | Reproducible? |
|---|---|
| requirements.txt with exact versions and hashes | Much closer |
| requirements.txt with loose ranges | Drifts over time |
| No Python version stated | Interpreter may differ |
| apt.txt with no versions | System libraries may differ |
Steps to tighten a Binder style repository
- Pin every Python package to an exact version. Add hashes where practical. See generate hashes for a requirements file.
- State the interpreter version using the mechanism the docs describe for your language.
- Pin or record system packages, since apt installs also change.
- Rebuild from scratch in CI on a schedule and fail when the result changes.
- Scan the pinned set for known vulnerabilities, and decide on updates deliberately.
- Never put tokens in the repository, because a public environment repository is public. See how to keep API keys out of Jupyter notebooks.
Security note
An environment built from public files and run in a hosted service should be treated as untrusted compute. Do not mount secrets into it, and do not assume the people running it are you.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how exact versions and transitive packages are listed, the same facts you need pinned in your requirements file.
Quick check
Does repo2docker pin my dependencies for me?
No. It installs what your files specify. If the files use loose versions, the result can change between builds.
Where do the configuration files go?
In the repository root, or in a binder or dot binder subdirectory, per the repo2docker specification.
Safeguard's SBOM and dependency scanning reads requirements files and lockfiles, and a free scan is available.
Sources
Last reviewed: 19 October 2026.
