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

Supported configuration files

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

Dockerfile

This will be treated as a regular Dockerfile and a regular Docker build will be performed. The presence of a Dockerfile takes priority over and ignores all other build behavior specified in other configuration files.

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.

See the Binder Documentation for best-practices with Dockerfiles.

environment.yml

This is a conda environment specification, that lets you install packages with conda.

Example Contents
channels:
  - conda-forge
  - defaults
dependencies:
  - matplotlib
  - pip:
    - sphinx-gallery

requirements.txt

This specifies a list of Python packages that should be installed in a virtualenv (or conda environment).

Example Contents
numpy==1.7
matplotlib==2.1

REQUIRE

This specifies a list of Julia packages.

Note

Using a REQUIRE file also requires that the repository contain an environment.yml file.

Example Contents
PyPlot
Stats

apt.txt

A list of Debian packages that should be installed. The base image used is usually the latest released version of Ubuntu.

Example Contents
cowsay
fortune

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.

Example Contents
wget <url-to-dataset>
python myfile.py

Note

This file must be executable to be used with repo2docker. To do this, run the following:

chmod +x postBuild

runtime.txt

This allows you to control the runtime of Python. To use Python 2, put the line python-2.7 in the file. A Python 2 kernel will be installed alongside Python 3.

Example Contents
python-2.7

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.