jupyterlab/tutorial/labextensions.md

JupyterLab Extensions

A JupyterLab extension provides additional, optional functionality to JupyterLab's built-in capabilities. An extension is a module that provides one or more plugins to the JupyterLab application. To streamline third-party development of extensions, this library provides a build script for generating third party extension JavaScript bundles.

For information on creating a lab extension, please see the documentation for the @jupyterlab/extension-builder.

Installing and enabling extensions

You can install your labextension with the command:

jupyter labextension install path/to/my_extension my_extension [--user|--sys-prefix]

The default installation is system-wide. You can use --user to do a per-user installation, or --sys-prefix to install to Python's prefix (e.g. in a virtual or conda environment). Where my_extension is the directory containing the JavaScript files. This will copy it to a Jupyter data directory (the exact location is platform dependent - see :ref:jupyter_path).

For development, you can use the --symlink flag to symlink your extension rather than copying it, so there's no need to reinstall after changes.

To use your extension, you'll also need to enable it, which tells the notebook interface to load it. You can do that with another command:

jupyter labextension enable my_extension [--sys-prefix]

There is a corresponding disable command to stop using an extension without uninstalling it.

Example

Here is an an example of creating a Python package with a labextension. It assumes this directory structure:

- setup.py
- MANIFEST.in
- my_fancy_module/
  - __init__.py
  - static/
    index.js

Defining the labextension This example shows that the labextension is defined in the __init__.py file. The first function, _jupyter_labextension_paths is required to register the lab extension. The _jupyter_labextension_config is for extensions that require passing dynamic config data to the JupyterLab frontend.

my_fancy_module/__init__.py

# Jupyter Lab Extension paths
def _jupyter_labextension_paths():
    return [dict(
        name="my_fancy_module",
        # the path is relative to the `my_fancy_module` directory
        src="static"
    )]


# Jupyter Lab Extension config data.
def _jupyter_labextension_config():
  """Get a dictionary of configuration data to provide to the JupyterLab frontend.

  This is called at each launch of the `/lab` page, and makes data available 
  through the `getConfigOption` [function](http://jupyterlab.github.io/services/globals.html#getconfigoption).

  Example in ES6 JavaScript:
  import { utils } from '@jupyterlab/services';
  let myVar = utils.getConfigOption('my_fancy_module_variable');
  """
  return dict(my_fancy_module_variable=1)