repo2docker scans a repository for configuration files such as requirements.txt and builds a container image from what it finds. So whoever can change those files controls what gets installed. Review them the way you review build scripts, and pin their contents to exact versions.
Definition
The repo2docker documentation defines the Reproducible Execution Environment Specification, or REES. repo2docker scans a repository for supported configuration files, and the collection of files, their contents and the actions taken is the specification. Its stated goal is to automate existing community best practices for reproducible computational environments.
Any directory with zero or more of the supported files counts as a valid environment. The files must sit in the repository root, in a binder folder, or in a dot binder folder.
What it does with the files
The documentation gives examples. A requirements.txt file is read in the standard Python format, and a compliant tool installs a Python interpreter, of unspecified version, and performs the equivalent of installing from that file. A Project.toml is handled for Julia, and an apt.txt for system packages through apt.
The documentation also stresses that a person should be able to reproduce the environment from a compliant repository without the software, using common clear steps.
Why this is a supply chain issue
| Fact | Consequence |
|---|---|
| The repo defines the install | A pull request that edits a config file changes what runs in the image |
| The interpreter version is unspecified | Two builds may differ without any file changing |
| Unpinned requirements resolve at build time | The image is only as stable as the index at that moment |
| System packages come from apt | They are outside your Python scan unless you list them |
When such images power a public notebook service, a malicious change gets built and run by whoever visits.
Review checklist
- List every supported config file in the repo, including those in a binder or dot binder folder.
- Check that Python requirements are pinned to exact versions, with hashes where you can.
- Read any file that runs commands during the build and ask who can edit it.
- Treat changes to these files as security relevant in code review.
- Build in a clean environment and scan the resulting image and package list.
- Rebuild on a schedule and compare, so drift is visible.
For pinning ideas in data work see /resources/blog/pin-python-dependencies-in-data-projects, and for the image side /resources/blog/how-to-scan-a-gpu-inference-container-image.
Where Safeguard fits
Safeguard's SBOM and dependency scanning plus its policies and gates can check changes to dependency files in a pull request. Try the free scan at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how every package in the list traces back to a file in the repository.
Quick check
Where can repo2docker config files live?
In the repository root, in a binder folder, or in a dot binder folder.
Does repo2docker choose the Python version for me?
For a plain requirements.txt, the specification says an interpreter of unspecified version is installed, so pin it explicitly if it matters.
Sources
- The Reproducible Execution Environment Specification, repo2docker documentation, fetched 19 October 2026.
Last reviewed: 19 October 2026.
