Written and maintained by CASRAI Editorial Board
Published
On this page
Binder (the Jupyter project’s service at mybinder.org) turns a public code repository that contains Jupyter notebooks into a temporary, runnable computing environment in your browser: you paste the repository address into the Binder form, click launch, and Binder builds the environment from the configuration files in the repository, then opens it for you. The mybinder.org deployment is free to use, the software behind it (BinderHub) is open source, and sessions are short-lived, so anything you want to keep must be downloaded before you close the tab.
What Binder is used for in research
The Binder documentation describes it as a way to “create custom computing environments that can be shared and used by many remote users.” For researchers the practical value is computational reproducibility: a reader of a paper, a reviewer or a student can run the authors’ notebooks without installing anything, in an environment whose software is defined by files in the repository rather than by whatever happens to be installed on a laptop. The people who built Binder made this argument themselves in an eLife Labs post: sharing code alone is not enough because software configurations are hard to recreate, so Binder packages the dependencies along with the notebooks.
Typical research uses follow from that:
- Attaching an executable version of an analysis to a paper, thesis or preprint through a launch badge in the repository README.
- Teaching, where every student needs an identical environment and a notebook to start from.
- Reviewing: a reviewer or collaborator can re-run a notebook without cloning the repository or building an environment locally.
Binder is not a place to do your day-to-day analysis. It has no persistent storage, tight memory limits and an idle timeout (all listed below). Use it to share and re-run work, not to hold the only copy of anything.
How to install or access Binder
There is nothing to install. You use Binder through the public website at mybinder.org, which is the free deployment operated for the community, and you need a repository that Binder can read. The repository requirements in the official introduction are:
- The repository must be public. The documentation uses GitHub and Bitbucket repositories as its examples.
- It must not contain sensitive information, because it is built on a public service.
- It needs a configuration file that describes the environment, for example
environment.yml, placed in the repository root or in abinder/folder.
If you want to run your own service instead of using mybinder.org, the software is BinderHub. Its README says BinderHub “allows you to BUILD and REGISTER a Docker image from a Git repository, then CONNECT with JupyterHub.” It ties together JupyterHub, which authenticates users and spawns single-user notebook servers, and repo2docker, which generates the Docker image from a Git repository. Running it is a server-administration task; see the JupyterHub guide for the hub side of that stack.
How to launch a Jupyter notebook on Binder step by step
The steps below follow the official Binder introduction. The repository used in its own example is binder-examples/conda, which is a good first test before you try your own work.
- Prepare the repository. Make it public, put your notebooks in it, and add an environment file such as
environment.ymlto the root or to abinder/folder. If you have not built a conda environment file before, the guide to making a new conda environment covers the format. - Open mybinder.org and paste the repository URL into the first field on the page.
- Click launch. Binder starts building an image from your repository. You can open the build logs to watch the progress.
- Wait for the interface. When the build finishes, Binder opens a Jupyter session in your browser, with your notebooks available to open and run.
- Copy the Binder URL. The page gives you a unique link for the repository. Send it to collaborators or put it in your README so others can launch the same environment.
A repository is built once. Later clicks on the same link reuse the built image rather than rebuilding it, and pushing changes to the repository triggers a rebuild the next time someone launches it. The docs also advise building the latest version of your repository before you share a link, so the first person who clicks it does not wait for a build.
An illustrative setup
This is an illustrative composite, not a real project. Suppose a group wants readers to re-run a figure-generating notebook from a paper. They keep analysis.ipynb, a small data file and an environment.yml in one public repository, describe the needed packages in the environment file, push, and then launch the repository once on mybinder.org to confirm that the image builds and the notebook runs top to bottom. Only after that check do they put the Binder link in the README. A reader who follows the link gets the same package set that the authors tested, not whatever versions are current that day on their own machine.
How to read the output
Binder gives you three things to read, and each answers a different question.
The build log shows whether the environment could be created. A failed build means the problem is in the repository’s configuration, not in your notebook: Binder never reached the point of running code. Read the log from the bottom, where the failing install step is reported.
The Jupyter interface is the same notebook interface you would see locally. Cell output, plots and error tracebacks behave as in any Jupyter session, so a traceback that mentions a missing module normally means the package is absent from the environment file, not that Binder is broken.
The session limits explain behaviour that looks like a fault but is policy. The user guidelines on the Binder documentation site set these figures:
| Limit | What the guidelines say | What it means for you |
|---|---|---|
| Memory | At least 1 GB of RAM is guaranteed and the maximum is 2 GB. Above 2 GB the kernel is restarted. | A notebook that loads a large dataset can die with a restarted kernel; shrink or subsample the data. |
| Idle time | Sessions inactive for more than 10 minutes are shut down. An open, foreground JupyterLab tab counts as activity. | Leaving a tab in the background can end the session. |
| Session length | Binder aims to support sessions up to 6 hours, or 1 CPU-hour for compute-heavy work, with no guarantee beyond that. | Do not plan long computations on Binder. |
| Storage | There is no persistent storage. | Download results before you close the tab; files created in the session are lost. |
| Concurrency | About 100 simultaneous users per repository. | A very popular repository can fill up. |
| Bandwidth | Roughly 1 Mbit of outgoing bandwidth per session. | Downloading large files out of the session is slow. |
Which files configure the environment
Binder uses repo2docker to turn the repository into an image, and repo2docker decides what to install from the files it finds. The data table below lists the configuration files named in the repo2docker documentation, with the ecosystem each belongs to and what it does. Two files are worth singling out for research use. postBuild runs after installation and its results are baked into the image, while start runs just before an interactive session begins and is not baked in. Use postBuild for work such as enabling an extension, and start for setup that must happen in every session. A Dockerfile hands full control to you, which is flexible but takes you out of the simple file-based setup; for the container concepts behind it, see the comparison of Docker and virtual machines.
The Binder documentation also explains that content and environment can live in different repositories, which is useful when many notebooks share one environment definition.
Troubleshooting Binder
The build fails or never starts
Check that the repository is public, that the URL is the repository itself and that an environment file sits in the root or in binder/. Then read the build log for the failing install step and correct that line in the file. Because pushing a change triggers a rebuild on the next launch, you can fix the file, push and launch again.
The kernel dies or restarts during a run
The most likely cause is memory. Binder restarts a kernel that goes over 2 GB, so reduce the data held in memory, read the file in smaller pieces or use a smaller sample for the demonstration.
The session disappears
Binder shuts down sessions idle for more than 10 minutes, and session length is only aimed at 6 hours. Work you want to keep has to be downloaded; there is no persistent storage to bring it back from.
A package is missing in the notebook
Add it to the environment file (or requirements.txt, install.R and so on, depending on the ecosystem) and push. System-level packages go in apt.txt. If you debug notebooks locally first, the Jupyter notebook debugging guide helps separate code errors from environment errors.
Data or credentials in the repository
Binder is a public service and the guidelines warn against sensitive information in the repository. Keep private data, keys and anything covered by a data-use agreement out of it.
Free alternatives to Binder
The table lists self-hosted options that appear in the same official sources. It is not a ranking, and each has a different operating burden.
| Option | What it is, per its own documentation | Fit with Binder |
|---|---|---|
| BinderHub (self-hosted) | The open-source software behind mybinder.org: builds a Docker image from a Git repository and connects it with JupyterHub. | Same launch experience on infrastructure you control, which also lets you set your own limits. |
| JupyterHub | Authenticates users and spawns single-user Jupyter Notebook servers. | A hub for a fixed group of users, with logins, rather than a one-click public launch. |
| repo2docker | Generates a Docker image from a Git repository using the same configuration files Binder reads. | Lets you test that your repository builds before sending anyone to Binder. |
If you are weighing a hosted notebook service instead, the comparison of Google Colab and Jupyter Notebook sets out how they differ.
Sources
- Binder documentation: The Binder Project, checked 2026-11-17
- Binder documentation: Get started with Binder, checked 2026-11-17
- Binder documentation: User guidelines, checked 2026-11-17
- repo2docker documentation: Configuring your repository, checked 2026-11-17
- BinderHub README on GitHub (jupyterhub organization), checked 2026-11-17
- mybinder.org, the public Binder service, checked 2026-11-17
Data: Configuration files repo2docker reads to build a Binder environment
Compiled from the repo2docker configuration documentation: each file the builder recognises for a repository, the language or tool ecosystem it belongs to, and what it does in the build. Order follows the documentation; the table is a reader-oriented reorganisation by ecosystem.
| Configuration file | Ecosystem | Role in the build |
|---|---|---|
| environment.yml | conda | Conda environment specification |
| install.R | R | R installation script |
| DESCRIPTION | R | R package description file |
| Project.toml | Julia | Julia project file |
| Pipfile / Pipfile.lock | Python | Pipenv dependency files |
| requirements.txt | Python | pip requirements |
| pyproject.toml | Python | Python project configuration |
| setup.py | Python | Python package setup script |
| apt.txt | System packages | Packages installed with apt-get |
| runtime.txt | Runtime | Runtime version declaration |
| default.nix | Nix | Nix environment definition |
| Dockerfile | Docker | Fully custom image definition |
| postBuild | Shell | Runs after install; results baked into the image |
| start | Shell | Runs just before a session begins; not baked in |
Sources
- repo2docker documentation: Configuring your repository (accessed 2026-11-17)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







