Binder Documentation

Join the chat at https://gitter.im/jupyterhub/binder

Binder allows you to create custom computing environments that can be shared and used by many remote users. This page provides information for those who wish to use a pre-existing Binder deployment (e.g., mybinder.org).

If you’d like to create and administer your own Binder deployment, see the BinderHub documentation. The BinderHub documentation guides you through creating a cluster, deploying BinderHub, and administering a BinderHub deployment.

See the Binder Examples GitHub organization for sample Binder repositories demonstrating its functionality.

What can I do with Binder?

Binder makes it simple to generate reproducible computing environments from a Git repository. Binder uses the BinderHub technology to generate a Docker image from this repository. The image will have all the components that you specify along with the Jupyter Notebooks inside. You will be able to share a URL with users that can immediately begin interacting with this environment via the cloud.

Preparing a repository for Binder

You can do this by making sure your repo contains:

  • A collection of Jupyter Notebooks. These notebooks will be made available to users of your Binder.
  • One (or many) text files that specify the requirements of your code. For example, a requirements.txt or environment.yml file. See the repo2docker documentation for a list of all the files and environments that are supported.

All you need to do is include the files specified above in a GitHub repository. Once that’s done, navigate to beta.mybinder.org and insert the URL for your git repository. Press Launch to automatically create your Binder. The Binder service will be automatically send you to a live Jupyter session connected to this repository.

Note

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. If Binder doesn’t have to build a new repository, the process of connecting to the live computational environment is much faster.

What technology does Binder use?

Binder combines several open-source technologies, especially:

  • repo2docker, for quickly generating Docker images from a GitHub repository.
  • JupyterHub, for connecting a built Docker image to cloud computation and a user-facing web portal.
  • BinderHub, for gluing the above two tools together to create the Binder experience.