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. We’ll look at this problem & some solutions for the same.
Problem
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? |
GitHub imposes a 5-second timeout for rich rendering. If the notebook cannot be rendered within the timeout period of 5 seconds, GitHub does not render it.
The same problem applies to the newly introduced rich notebook diffs on GitHub. The new GitHub rich diff functionality uses nbdime under the hood & nbdime diffs can be very slow for large notebooks (as mentioned by others here and here).
 |
|---|
| 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:
Solution
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.
3. 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 supports -
- Google-Doc style commenting & discussion on Jupyter notebook cells, and
- Jupyter Notebook code reviews for GitHub pull requests!
Summary
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.