Tip: Debug binder builds faster with repo2docker

Fast iteration times make for fun development. Unfortunately, sometimes you are debugging why your repository isn’t working as it should on mybinder.org, and the cycle of ‘make a change, push to git, build, repeat’ can be slow sometimes. You can make the debug cycle much faster by running repo2docker locally.


  1. A recent version of Docker CE installed locally
  2. Local install of repo2docker


I’ve a notebook called numpy-test.ipynb in my repo, with the following code:

import numpy

On my local machine, this works fine. However, on mybinder.org, I get an error:

ModuleNotFoundError: No module named 'numpy'

You realize you need to add a requirements.txt with the following contents:


Normally, you’d create the file, commit it, push it, launch on binder, and then discover you had a typo - you used = instead of ==

If you have repo2docker installed locally, as soon as you create the file in the directory, you can run:

repo2docker -v .:. .

This builds the contents of the current directory in the exact same way mybinder.org would, and launches a notebook server for you afterwards if the build succeeds. You don’t even need to make a commit before trying this out! The -v .:. makes the files in your current directory read / writeable by the notebook server after it launches.

On running the repo2docker command, you see the complete build logs for your directory - same as you see on mybinder.org. It’ll be slow the very first time on your computer - gets faster after that. After a while, you’d get the following error:

Invalid requirement: 'numpy=1.15'
= is not a valid operator. Did you mean == ?

You realize your error, change your requirements.txt file, and try again. This time it builds successfully, and you get a message like:

    Copy/paste this URL into your browser when you connect for the first time,
    to login with a token:

If you copy paste the URL to your browser, you should see your notebook server - this is exactly what you’d see if you ran this on mybinder.org! Any edits to the contents of your directory will be reflected both inside & outside the running container. This makes development & debugging much faster.

This works for all the languages supported by mybinder.org, and all the frontends too (Jupyter Lab, Classic Notebook, nteract, RStudio, etc).

Hope this was helpful! I’ve tested this only on Ubuntu Linux, would love for others to test this on macOS / Windows and report their findings. Comments and corrections welcome! <3

Happy bindering!

1 Like

Should we also share this in the docs?

Absolutely! Not sure where exactly though. I think having a pipeline of useful tips from discourse finding their way back to docs is great.

How about https://mybinder.readthedocs.io/ ?

That’s probably a good place for something like this. I haven’t looked at any of the docs since I came back from surgery though, so not sure where exactly It’d fit. I trust y’all to make good choices!