nbtoolbelt: Tools to Work with Jupyter Notebooks

Version: 2024.7.2

Introduction

When you work with many Jupyter notebooks (e.g., when writing a book or teaching a course), you will need tools to do bulk operations on notebooks.

nbtoolbelt is an integrated collection of tools to work with Jupyter notebooks.

We use nbtoolbelt together with Momotor, a highly-configurable LTI Tool Provider that automatically processes digital content submitted in our Learning Management System (in our case, students submit Jupyter notebooks), and returns various forms of feedback.

nbtoolbelt

With nbtoolbelt you get tools and libraries to

  • validate notebooks (a wrapper for nbformat.validate())

  • inspect head or tail cells of notebooks

  • dump notebooks compactly on the terminal

  • summarize notebooks, with statistics (stats)

  • view notebooks in the browser

  • catenate multiple notebooks into one notebook

  • clean notebooks

  • run notebooks, with pre/post cleaning (a wrapper for nbconvert.PreProcessor.execute())

  • split notebooks

  • punch notebooks (shoot holes in them, to produce frameworks useful for exercises)

The next sections briefly discuss some other tools.

nbconvert

You can use Jupyter’s nbconvert on the command line:

jupyter nbconvert --to notebook --execute --allow-errors notebook.ipynb

to execute notebook.nbconvert.ipynb capturing the execution results, including cells that produce errors. See the nbconvert documentation for further details.

nbdime

You can use nbdime for selectively showing, diffing, and merging of notebooks. For instance, when you have installed nbdime, the command

nbshow -O nb.ipynb

will show the notebook without outputs of executed code cells. See the nbdime documentation for further details.

Installation

To install nbtoolbelt from PyPI (the Python Package Index):

pip install nbtoolbelt

For users who install from a locally saved wheel:

pip install --no-index --find-links=<path/to/wheel/dir> nbtoolbelt

where <path/to/wheel/dir> is the (absolute or relative) path to the directory where you saved the wheel. The wheel has a name of the form nbtoolbelt-*.whl.

Dependencies

nbtoolbelt depends on

  • nbformat for notebook structure, and reading and writing of notebooks;

  • nbconvert for notebook validation and execution;

  • pandas and numpy for summary statistics in the stats tool.

For testing, it depends on pytest and pytest-mock.

Upgrading

To upgrade your nbtoolbelt installation, add the --upgrade flag to the above commands:

pip install --upgrade nbtoolbelt

pip install --upgrade --no-index --find-links=<path/to/wheel/dir> nbtoolbelt

Uninstall

To uninstall nbtoolbelt:

pip uninstall nbtoolbelt

Developers

To install for testing:

pip install nbtoolbelt[test]

Usage Instructions

nbtoolbelt on Command Line

nbtoolbelt as Library

nbtoolbelt Development

nbtoolbelt Change Log

References

  • The structure of Jupyter notebooks is specified in nbformat (documentation). The library nbformat facilitates programmatic manipulation of notebooks.

  • Tool to convert notebooks: nbconvert (documentation); can be used on the command line and as a library for conversion to various other formats, including notebook execution and other notebook versions. It also provides a set of notebook preprocessors.

  • Tools for showing, diffing, and merging Jupyter notebooks, including Git integration: nbdime (documentation)

License and Source Code

This software is made available under the terms of the MIT License.

Copyright (c) 2017-2020 - Eindhoven University of Technology, The Netherlands

The source code and issue tracker are at <https://gitlab.tue.nl/jupyter-projects/nbtoolbelt/>.

Indices and tables