View the original notebook on nbviewer
The Jupyter Notebook client and server application are both deeply customizable. Their behavior can be extended by creating, respectively:
- nbextension: a notebook extension
- a single JS file, or directory of JavaScript, Cascading StyleSheets, etc. that contain at minimum a JavaScript module packaged as an AMD modules that exports a function
load_ipython_extension
- a single JS file, or directory of JavaScript, Cascading StyleSheets, etc. that contain at minimum a JavaScript module packaged as an AMD modules that exports a function
- server extension: an importable Python module
- that implements
load_jupyter_server_extension
- that implements
Since it is rare to have a server extension that does not have any frontend components (an nbextension), for convenience and consistency, all these client and server extensions with their assets can be packaged and versioned together as a Python package with a few simple commands. This makes installing the package of extensions easier and less error-prone for the user.
There are several ways that you may get a Python package containing Jupyter Extensions. Commonly, you will use a package manager for your system:
pip install helpful_package
# or
conda install helpful_package
# or
apt-get install helpful_package
# where 'helpful_package' is a Python package containing one or more Jupyter Extensions
The simplest case would be to enable a server extension which has no frontend components.
A pip
user that wants their configuration stored in their home directory would type the following command:
jupyter serverextension enable --py helpful_package
Alternatively, a virtualenv
or conda
user can pass --sys-prefix
which keeps their environment isolated and reproducible. For example:
# Make sure that your virtualenv or conda environment is activated
[source] activate my-environment
jupyter serverextension enable --py helpful_package --sys-prefix
If a package also has an nbextension with frontend assets that must be available (but not neccessarily enabled by default), install these assets with the following command:
jupyter nbextension install --py helpful_package # or --sys-prefix if using virtualenv or conda
If a package has assets that should be loaded every time a Jupyter app (e.g. lab, notebook, dashboard, terminal) is loaded in the browser, the following command can be used to enable the nbextension:
jupyter nbextension enable --py helpful_package # or --sys-prefix if using virtualenv or conda
After running one or more extension installation steps, you can list what is presently known about nbextensions or server extension. The following commands will list which extensions are available, whether they are enabled, and other extension details:
jupyter nbextension list
jupyter serverextension list
Of course, in addition to the files listed, there are number of other files one needs to build a proper package. Here are some good resources: - The Hitchhiker's Guide to Packaging - Repository Structure and Python by Kenneth Reitz
How you distribute them, too, is important: - Packaging and Distributing Projects - conda: Building packages
Here are some tools to get you started: -generator-nbextension
Here is an example of a python module which contains a server extension directly on itself. It has this directory structure:
- setup.py
- MANIFEST.in
- my_module/
- __init__.py
This example shows that the server extension and its load_jupyter_server_extension
function are defined in the __init__.py
file.
def _jupyter_server_extension_paths():
return [{
"module": "my_module"
}]
def load_jupyter_server_extension(nbapp):
nbapp.log.info("my module enabled!")
Which a user can install with:
jupyter serverextension enable --py my_module [--sys-prefix]
Here is another server extension, with a front-end module. It assumes this directory structure:
- setup.py
- MANIFEST.in
- my_fancy_module/
- __init__.py
- static/
index.js
This example again shows that the server extension and its load_jupyter_server_extension
function are defined in the __init__.py
file. This time, there is also a function _jupyter_nbextension_path
for the nbextension.
def _jupyter_server_extension_paths():
return [{
"module": "my_fancy_module"
}]
# Jupyter Extension points
def _jupyter_nbextension_paths():
return [dict(
section="notebook",
# the path is relative to the `my_fancy_module` directory
src="static",
# directory in the `nbextension/` namespace
dest="my_fancy_module",
# _also_ in the `nbextension/` namespace
require="my_fancy_module/index")]
def load_jupyter_server_extension(nbapp):
nbapp.log.info("my module enabled!")
The user can install and enable the extensions with the following set of commands:
jupyter nbextension install --py my_fancy_module [--sys-prefix|--user]
jupyter nbextension enable --py my_fancy_module [--sys-prefix|--system]
jupyter serverextension enable --py my_fancy_module [--sys-prefix|--system]