Solutions to “Jupyter Notebook Not Rendering on GitHub” problem

Your Jupyter Notebook doesn’t render on GitHub and you’re not sure why. Sometimes even the same notebook that rendered fine last week isn’t working now.

It could be that your notebook is too big

Sorry, this is too big to display

But occasionally, even small notebooks won’t render or they render intermittently:

Unable to render code block

Sorry, something went wrong. Reload?

If this is because GitHub’s services are down or rendering queues are backed up, there isn’t much you can do about it except wait. Or possibly reach out to GitHub support.

The notebook took too long to render

So how can you share your notebook with your colleagues if it isn’t rendering on GitHub? Here are a few options:

1. NBviewer

A free tool maintained by the Jupyter project, NBviewer is an online service that renders static Jupyter Notebooks from URLs. If you supply NBviewer with a URL that points to a GitHub repository, you can navigate the repository structure from NBviewer and select notebooks to view.

One limitation of NBviewer is that your notebooks must be publicly available. If you’re working in a private GitHub repository, you can’t use NBviewer.

2. Binder

Another Jupyter subproject is Binder, a free service providing an online platform to share executable notebooks. All you need to do is enter the path to your repository and Binder will generate a JupyterLab instance:

Binder is designed for live sharing public code, mostly for educational or demonstration purposes, in small, short-lived environments with up to 1-2 GB of memory.

This is specially a good choice if your notebook has any interactive elements (e.g. plots). Such interactivity is disabled in GitHub notebook viewer for security reasons.

Like nbviewer above, mybinder.org is also restricted to public repositories only. You will have to deploy your own BinderHub for accessing private repository notebooks.

2. ReviewNB

ReviewNB is a GitHub marketplace app that enables code reviews on Jupyter Notebooks. It supports viewing stand-alone notebook files in a public / private GitHub repository.

Below we see the 30.3 MB notebook that GitHub couldn’t render natively, rendering fine in ReviewNB:

ReviewNB can be used with both public and private repositories. ReviewNB also supports Google-Doc style commenting & discussion on Jupyter notebook cells.

---

If sharing GitHub Notebook output is an important part of your workflow, it’s better not to entirely rely on the notebook rendering provided by GitHub. If you are working in public repositories, NBviewer or Binder are worth trying. NBviewer is a simple, reliable way to statically render your public notebooks, and Binder lets you share public notebooks as live code.

If you are working in private repositories, then ReviewNB is a good solution, both for code reviewing and full notebook rendering.