Using Binder

This page describes how to use Binder to create interactive, sharable repositories. It includes how to prepare your repository to be binder-ready, as well as how to build and launch that repository with Binder.

Preparing a repository for Binder

All of the code in a repository is available to users, your Binder repository should contain at least:

  • The code you want users to run. This might be a collection of Jupyter notebooks or scripts.
  • Configuration files (one or more text files) that specify the requirements for building your project’s code. For a complete list of supported files, see Configuration Files. Configuration files may be placed in the root of your repository or in a binder/ folder in the repository’s root (i.e. myproject/binder/). If a binder/ folder is used, Binder will only read configuration files from that location and will ignore those in the repository’s root.

Tip

For a list of sample repositories for use with Binder, see the Sample Binder Repositories page.

Configuration Files

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 complex setups.

repo2docker will look for configuration files in either:

  • A folder named binder/ in the root of the repository.
  • The root directory of the repository.
If the folder binder/ is located at the top level of the repository,
only configuration files in the binder/ folder will be considered.

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

Below is a list of supported configuration files (roughly in the order of build priority):

Dockerfile

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 Binder Documentation for best-practices with Dockerfiles.

environment.yml

environment.yml is the standard configuration file used by Anaconda, conda, and miniconda that lets you install Python packages. You can also install files from pip in your environment.yml as well. Our example environment.yml shows how one can specify a conda environment for repo2docker.

You can also specify which Python version to install in your built environment with environment.yml. By default, repo2docker installs Python 3.6 with your environment.yml unless you include the version of Python in the file. conda supports Python versions 3.6, 3.5, 3.4, and 2.7. repo2docker support is best with Python 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.

requirements.txt

This specifies a list of Python packages that should be installed in your environment. Our requirements.txt example on GitHub shows a typical requirements file.

REQUIRE

This specifies a list of Julia packages. Repositories with a REQUIRE file must also contain an environment.yml file. To see an example of a Julia repository with REQUIRE and environment.yml, visit binder-examples/julia-python.

install.R

This is used to install R libraries pinned to a specific snapshot on MRAN. To set the date of the snapshot add a runtime.txt. For an example install.R file, visit our example install.R file.

apt.txt

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.

setup.py

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

While one can specify dependencies in setup.py, repo2docker requires configuration files such as environment.yml or requirements.txt to install dependencies during the build process.

postBuild

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.

An example usecase 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.

runtime.txt

This allows you to control the runtime of Python or R.

To use python-2.7: add python-2.7 in runtime.txt file. The repository will run in a virtualenv with Python 2 installed. To see a full example repository, visit our Python2 example. Python versions in ``runtime.txt`` are ignored when environment.yml is present in the same folder.

repo2docker uses R libraries pinned to a specific snapshot on MRAN. You need to have a runtime.txt file that is formatted as r-<YYYY>-<MM>-<DD>, where YYYY-MM-DD is a snapshot at MRAN that will be used for installing libraries.

To see an example R repository, visit our R example in binder-examples.

Launching your Binder

Once you have prepared your repository per the instructions above, it is time to build and launch your binder-ready repo. Navigate to mybinder.org and insert the URL for your git repository. Press Launch to automatically create your Binder. The Binder service will automatically send you to a live Jupyter session connected to this repository.

If a previous version of the repository has already been built, Binder will only build a new one if the git hashes don’t match. When Binder doesn’t need to build a repository, the process of connecting to the live computational environment is much faster.

Use cases

Below are some example use-cases and their respective repository configuration.

For a full guide on how to configure your repository for Binder, see the repo2docker configuration guide. For a list of sample repositories for use with Binder, see the Sample Binder Repositories page.

Simple Python dependencies

Many repositories already contain a requirements.txt specifying the dependencies of that repository. For ‘simple to install’ dependencies, a requirements.txt should meet your needs. To generate a requirements.txt from the environment you have locally use pip freeze > requirements.txt. This will list all packages you have installed, and can be a starting point for constructing your requirements.txt. We recommend you only list those packages you really need to successfully build the repository.

Take a look at the binder-examples/requirements repository to see an example.

Using conda packages

For ‘complex to install’ packages, like geopandas, we recommend using the conda package manager. To specify your dependencies create an environment.yml listing the packages and versions required. For syntax help read create an environment file manually from the conda documentation.

Take a look at the binder-examples/conda repository to see an example.

Note

Packages that require pip for installation can be specified in the environment.yml file. We recommend this approach instead of having a requirements.txt and an environment.yml in the same repository. See binder-examples/python-conda_pip.

Using Python2

To use python 2.7 for your repository create a runtime.txt with python-2.7 as only content. This will install a python2 environment in addition to the default python environment. The contents of requirements.txt are installed into the python2 environment.

Take a look at the binder-examples/python2_runtime repository to see an example.

Note

Make sure that you save your notebooks with a python2 kernel activated, as this defines which kernel Binder will use when a notebook is opened. The active kernel is displayed in the upper right corner of the notebook.

Note

If you also wish to install dependencies into the python3 environment, include a file called requirements3.txt. The packages inside it will be installed into the python3 environment.

Executing post-build commands

You might need to run arbitrary commands at the end of the build process. Place these in the postBuild file and make it executable. One use case is having a repository that contains a Python package and examples that use the package. In this case you can run python setup.py install from the postBuild file to avoid having to place your package in the requirements.txt. It is also useful for activating notebook extensions you installed via a requirements.txt directive earlier.

Take a look at the binder-examples/jupyter-extension repository to see an example.