System-wide configuration#

apt.txt - Install packages with apt-get#

A list of packages in the .deb format that should be installed. The .deb files are downloaded from the server configured in the Docker base image.

Note

If a Dockerfile is not used to change the Docker base image, the base image is Ubuntu 24.04 LTS (Noble Numbat). All .deb files availables are listed in Ubuntu Packages.

We use apt.txt, for example, to install LaTeX in our example apt.txt file for LaTeX.

runtime.txt - Specifying runtimes#

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 runtime.txt file.

Warning

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).

Set the Python version#

Add the line python-x.y in runtime.txt to run the repository with Python version x.y. See our Python2 example repository.

Set the R version#

Add the line r-x.y-YYYY-MM-DD in runtime.txt to run the repository with R version x.y and libraries from a YYYY-MM-DD snapshot of the Posit Package Manager.

The version of R, i.e. x.y, can be set to

  • 4.4

  • 4.3

  • 4.2

  • 4.1

  • 4.0

  • 3.6

  • 3.5

  • 3.4

  • 3.3

If you do not specify a version, the latest release will be used.

See our R example repository.

default.nix - the nix package manager#

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 not 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 example repository.

Dockerfile - Advanced environments#

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.

Warning

If a Dockerfile is present, all other configuration files will be ignored.

See the Advanced Binder Documentation for best-practices with Dockerfiles.