Skip to main content
v2026.11,986 entries · CC-BY 4.0

Binder (Jupyter): How to Launch a Notebook on mybinder.org

How to run a Jupyter notebook on Binder (mybinder.org): repository setup, launch steps, session limits and fixes for failed builds.

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 a binder/ 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.

  1. Prepare the repository. Make it public, put your notebooks in it, and add an environment file such as environment.yml to the root or to a binder/ folder. If you have not built a conda environment file before, the guide to making a new conda environment covers the format.
  2. Open mybinder.org and paste the repository URL into the first field on the page.
  3. Click launch. Binder starts building an image from your repository. You can open the build logs to watch the progress.
  4. Wait for the interface. When the build finishes, Binder opens a Jupyter session in your browser, with your notebooks available to open and run.
  5. 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

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 files repo2docker reads to build a Binder environment
Configuration fileEcosystemRole in the build
environment.ymlcondaConda environment specification
install.RRR installation script
DESCRIPTIONRR package description file
Project.tomlJuliaJulia project file
Pipfile / Pipfile.lockPythonPipenv dependency files
requirements.txtPythonpip requirements
pyproject.tomlPythonPython project configuration
setup.pyPythonPython package setup script
apt.txtSystem packagesPackages installed with apt-get
runtime.txtRuntimeRuntime version declaration
default.nixNixNix environment definition
DockerfileDockerFully custom image definition
postBuildShellRuns after install; results baked into the image
startShellRuns just before a session begins; not baked in

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about Binder (Jupyter): How to Launch a Notebook on mybinder.org

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →