How to share Jupyter Notebooks


September 15, 2020

I tend to preserve and post online all the work I do for later reference and sharing. Jupyter Notebooks are a bit more complex than standard source code because they are natively in a format (JSON) that needs to be rendered to be readable.

Most of the times you want to share a static copy of your “executed” notebook which contains all the generated plots and outputs.

Share on gist through the browser

The easiest way to share a Jupyter Notebook is to use a gist, which is quick sharing service provided by Github based on copy-paste.

Navigate to, it shows a text-area for copy-pasting content, you can drag your ipynb file from your File Manager into the text-area and it will paste its content into the area, then you can click on “Create a public gist” button and it will be uploaded and rendered automatically. If you don’t want the gist to appear under and not be findable on Google, select “Create a private gist” instead. You can also upload multiple notebooks to the same gist.

The good thing is that behind this interface there is an actual git repository, so you can later clone and update it using git. Or you can even use the web interface to copy-paste a newer version of your Notebook.

Share on gist from the command line

If you are working on a remote machine (e.g. HPC), it is way better to setup the gh client for Github, then you can directly create a gist from the command line:

gh gist create --public -d "My description" *.ipynb

and it will print to stdout the gist URL.

Render larger Notebooks via nbviewer

The Github rendering engine is not the most reliable: it fails for larger notebooks, it doesn’t work on mobile and it doesn’t support some JavaScript based libraries, like altair.

Then after having uploaded your Notebook to gist, you can go to, paste the full link to your gist and share the nbviewer rendering instead.

Save clean Notebooks in Github repositories

I also recommend to save a copy of notebooks without any outputs (either doing “Clear all outputs” from the interface or using nbstripout) into a related Github repository, this makes it easier to reference it later on. However don’t save executed notebooks inside Github repositories, they are too large and cause ugly diff between versions (also use nbdime to help manage notebooks inside repos).

Make notebooks executable in the browser

Once you have notebooks in a repository, you can also plug them into to allow people to spin a Virtual Machine on Google Cloud automatically and for free and execute them in their browser. You can also provide a environment.yml file to setup the requirements.

See for example the healpy tutorial gist, which can be executed on Binder clicking on the following Icon: Binder logo