Jupyter notebook extensions
The IPython-contrib repository is maintained independently by a group of users and developers and not officially related to the IPython development team.
IPython/Jupyter version support
|IPython 2.x||checkout 2.x branch|
|IPython 3.x||checkout 3.x branch|
|Jupyter 4.x||checkout master branch|
There are different branches of the notebook extensions in this repository. Please make sure you use the branch corresponding to your IPython/Jupyter version.
Documentation for all maintained extensions can be found at jupyter-contrib-nbextensions.readthedocs.io
In the 4.x Jupyter repository, all extensions that are maintained and active
have at least a yaml file to allow them being configured using the
server extension, which is installed as a dependency of this package.
Most also have a markdown readme file for documentation.
jupyter_nbextensions_configurator server extension shows an nbextensions
tab on the main notebook dashboard (file tree page) from which you can see each
nbextension's markdown readme, and configure its options.
To view documentation without installing, you can browse the nbextensions
directory to read markdown readmes on github at
For older releases (2.x and 3.x), look at the Wiki
Some extensions are not documented. We encourage you to add documentation for them.
To install the
jupyter_contrib_nbextensions notebook extensions, three steps
are required. First, the Python pip package needs to be installed. Then, the
notebook extensions themselves need to be copied to the Jupyter data directory.
Finally, the installed notebook extensions can be enabled, either by using
built-in Jupyter commands, or more conveniently by using the
server extension, which is installed as a dependency of this repo.
The Python package installation step is necessary to allow painless installation of the nbextensions together with additional items like nbconvert templates, pre-/postprocessors, and exporters.
1. Install the python package
All of the nbextensions in this repo are provided as parts of a python package,
which is installable in the usual manner, using
pip or the
To install the current version from PyPi, simply type
pip install jupyter_contrib_nbextensions
Alternatively, you can install directly from the current master branch of the repository
pip install https://github.com/ipython-contrib/jupyter_contrib_nbextensions/tarball/master
All the usual pip options apply, e.g. using pip's
--upgrade flag to force an
-e for an editable install.
conda install -c conda-forge jupyter_contrib_nbextensions
jupyter contrib nbextension install --sys-prefix), so the second
installation step below can therefore be skipped.
Installation from cloned Repo
You can also install from a cloned repo, which can be useful for development. You can clone the repo using
git clone https://github.com/ipython-contrib/jupyter_contrib_nbextensions.git
Then perform an editable pip install using
pip install -e jupyter_contrib_nbextensions
server's search directory, and edits some jupyter config files.
jupyter subcommand is provided for the purpose:
jupyter contrib nbextension install --user
The command does two things: installs nbextension files, and edits nbconvert
config files. The first part is essentially a wrapper around the
and css files to the appropriate jupyter data directory.
The second part edits the config files
jupyter_notebook_config.json as noted below in the options.
The command can take most of the same options as the jupyter-provided versions,
--userto install into the user's home jupyter directories
--systemto perform installation into system-wide jupyter directories
--sys-prefixto install into python's
sys.prefix, useful for instance in virtual environments, such as with conda
--symlinkto symlink the nbextensions rather than copying each file (recommended, on non-Windows platforms).
--debug, for more-verbose output
In addition, two further option flags are provided to perform either only the config-editing operations, or only the file-copy operations:
--only-filesto install nbextension files without editing any config files
--only-configto edit the config files without copying/symlinking any nbextension files. This edits the following files in the applicable jupyter config directory:
jupyter_nbconvert_config.jsonto use some of the classes provided in the python module
jupyter_notebook_config.jsonto enable the serverextension
--perform-running-check option flag is provided in order to
prevent the installation from proceeding if a notebook server appears to be
(by default, the install will still be performed, even if a notebook server
appears to be running).
uninstall command is also provided, to remove all of the
nbextension files from the jupyter directories.
3. Enabling/Disabling extensions
To use an nbextension, you'll also need to enable it, which tells the notebook interface to load it. To do this, you can use a Jupyter subcommand:
jupyter nbextension enable <nbextension require path>
jupyter nbextension enable codefolding/main
To disable the extension again, use
jupyter nbextension disable <nbextension require path>
Alternatively, and more conveniently, you can use the
server extension, which is installed as a dependency of this repo, and can be
used to enable and disable the individual nbextensions, as well as configure
their options. You can then open the
nbextensions tab on the tree
(dashboard/file browser) notebook page to configure nbextensions.
You will have access there to a dashboard where extensions can be
enabled/disabled via checkboxes.
Additionally a short documentation for each extension is displayed, and
configuration options are presented.
4. Migrating from older versions of this repo
jupyter contrib nbextensions command also offers a
- uninstall the old repository version's files, config and python package
- adapt all
requirepaths which have changed. E.g. if you had the collapsible headings nbextension enabled with its old require path of
migratecommand will alter this to match the new require path of
For complex or customized installation scenarios, please look at the documentation for installing notebook extensions, server extensions, nbconvert pre/postprocessors and templates on the Jupyter homepage. More information can also be found in the Wiki.
See also installing Jupyter
Notebook extension structure
The nbextensions are stored in the repository each as a separate subdirectory of
Each notebook extension typically has its own directory named after the extension, containing:
thisextension/thisextension.yml- file describing the nbextension to the
thisextension/README.md- readme file describing the nbextension in markdown format
For further details, see the documentation at jupyter-contrib-nbextensions.readthedocs.io.
For changes, see the CHANGELOG.md