repo2docker looks for configuration files in the repository being built
to determine how to build it. In general, repo2docker uses the same
configuration files as other software installation tools,
rather than creating new custom configuration files.
A number of repo2docker configuration files can be combined to compose more
The binder examples organization on
GitHub contains a list of sample repositories for common configurations
that repo2docker can build with various configuration files such as
Python and R installation in a repository.
A list of supported configuration files (roughly in the order of build priority)
can be found on this page (and to the right).
environment.yml is the standard configuration file used by conda
that lets you install any kind of package,
including Python, R, and C/C++ packages.
repo2docker does not use your environment.yml to create and activate a new conda environment.
Rather, it updates a base conda environment defined here with the packages listed in your environment.yml.
This means that the environment will always have the same default name, not the name
specified in your environment.yml.
You can install files from pip in your environment.yml as well.
For example, see the binder-examples environment.yml
You can also specify which Python version to install in your built environment
with environment.yml. By default, repo2docker installs
|default_python| with your environment.yml unless you include the version of
Python in this file. conda supports all versions of Python,
though repo2docker support is best with Python 3.7, 3.6, 3.5 and 2.7.
If you include a Python version in a runtime.txt file in addition to your
environment.yml, your runtime.txt will be ignored.
pipenv allows you to manage a virtual
environment Python dependencies. When using pipenv, you end up with
Pipfile and Pipfile.lock files. The lock file contains explicit details
about the packages that has been installed that met the criteria within the
If both Pipfile and Pipfile.lock are found by repo2docker, the former
will be ignored in favor of the lock file. Also note that these files
distinguish packages and development packages and that repo2docker will install
This specifies a list of Python packages that should be installed in your
on GitHub shows a typical requirements file.
To install your repository like a Python package, you may include a
setup.py file. repo2docker installs setup.py files by running
pip install -e ..
pip install -e .
A Project.toml (or JuliaProject.toml) file can specify both the
version of Julia to be used and a list of Julia packages to be installed.
If a Manifest.toml is present, it will determine the exact versions
of the Julia packages that are installed.
A REQUIRE file can specify both the version of Julia to be used and
which Julia packages should be used. The use of REQUIRE is only
recommended for pre 1.0 Julia versions. The recommended way of installing
a Julia environment that uses Julia 1.0 or newer is to use a Project.toml
file. If both a REQUIRE and a Project.toml file are detected,
the REQUIRE file is ignored. To see an example of a Julia repository
with REQUIRE and environment.yml, visit
This is used to install R libraries pinned to a specific snapshot on
To set the date of the snapshot add a runtime.txt.
For an example install.R file, visit our example install.R file.
A list of Debian packages that should be installed. The base image used is usually the latest released
version of Ubuntu.
We use apt.txt, for example, to install LaTeX in our
example apt.txt for LaTeX.
To install your repository like an R package, you may include a
DESCRIPTION file. repo2docker installs the package and dependencies
from the DESCRIPTION by running devtools::install_git(".").
You also need to have a runtime.txt file that is formatted as
r-<YYYY>-<MM>-<DD>, where YYYY-MM-DD is a snapshot of MRAN that will be
used for your R installation.
Stencila is an open source office suite for reproducible research.
It is powered by the open file format Dar.
If your repository contains a Stencila document, repo2docker detects it based on the file manifest.xml.
The required execution contexts are extracted from a Dar article (i.e.
files named *.jats.xml).
You may also have a runtime.txt and/or an install.R to manually configure your R installation.
To see example repositories, visit our
Stencila with R and
Stencila with Python examples.
A script that can contain arbitrary commands to be run after the whole repository has been built. If you
want this to be a shell script, make sure the first line is #!/bin/bash.
Note that by default the build will not be stopped if an error occurs inside a shell script.
You should include set -e or the equivalent at the start of the script to avoid errors being silently ignored.
An example use-case of postBuild file is JupyterLab’s demo on mybinder.org.
It uses a postBuild file in a folder called binder to prepare
their demo for binder.
A script that can contain simple commands to be run at runtime (as an
to the docker container). If you want this to be a shell script, make sure the
first line is #!/bin/bash. The last line must be exec "$@"
Use this to set environment variables that software installed in your container
expects to be set. This script is executed each time your binder is started and
should at most take a few seconds to run.
If you only need to run things once during the build phase use postBuild - Run code after installing the environment.
Sometimes you want to specify the version of the runtime
(e.g. the version of Python or R),
but the environment specification format will not let you specify this information
(e.g. requirements.txt or install.R).
For these cases, we have a special file, runtime.txt.
runtime.txt is only supported when used with environment specifications
that do not already support specifying the runtime
(when using environment.yml for conda or Project.toml for Julia,
runtime.txt will be ignored).
Have python-x.y in runtime.txt to run the repository with Python version x.y.
See our Python2 example repository.
Have r-<RVERSION>-<YYYY>-<MM>-<DD> in runtime.txt to run the repository with R version RVERSION and libraries from a YYYY-MM-DD snapshot of MRAN.
RVERSION can be set to 3.4, 3.5, 3.6, or to patch releases for the 3.5 and 3.6 series.
If you do not specify a version, the latest release will be used (currently R 3.6).
See our R example repository.
Specify packages to be installed by the nix package manager.
When you use this config file all other configuration files (like requirements.txt)
that specify packages are ignored. When using nix you have to specify all
packages and dependencies explicitly, including the Jupyter notebook package that
repo2docker expects to be installed. If you do not install Jupyter explicitly
repo2docker will no be able to start your container.
nix-shell is used to evaluate
a nix expression written in a default.nix file. Make sure to
pin your nixpkgs
to produce a reproducible environment.
To see an example repository visit
nix binder example.
In the majority of cases, providing your own Dockerfile is not necessary as the base
images provide core functionality, compact image sizes, and efficient builds. We recommend
trying the other configuration files before deciding to use your own Dockerfile.
With Dockerfiles, a regular Docker build will be performed.
If a Dockerfile is present, all other configuration files will be ignored.
See the Advanced Binder Documentation for
best-practices with Dockerfiles.