Extensions

Fundamentally, JupyterLab is designed as an extensible environment. JupyterLab extensions can customize or enhance any part of JupyterLab. They can provide new themes, file viewers and editors, or renderers for rich outputs in notebooks. Extensions can add items to the menu or command palette, keyboard shortcuts, or settings in the settings system. Extensions can provide an API for other extensions to use and can depend on other extensions. In fact, the whole of JupyterLab itself is simply a collection of extensions that are no more powerful or privileged than any custom extension.

For information about developing extensions, see the developer documentation.

Installing Extensions

A JupyterLab extension is a JavaScript package that runs in the browser. An extension’s JavaScript can be distributed as a single JavaScript package (which requires a rebuild of JupyterLab to activate it), or starting in JupyterLab 3.0, can be bundled together with its dependencies (which does not require a rebuild of JupyterLab to activate it). Rebuilding JupyterLab requires Node.js to be installed.

An extension can be installed using the pip or conda package managers, or using the Jupyter Lab tools to install packages from npm.

  • Python pip or conda packages can include extensions as either single JavaScript packages (requiring Node.js and a JupyterLab rebuild) or bundled with their dependencies (not requiring Node.js nor a JupyterLab rebuild). These packages may also include by a server-side component necessary for the extension to function.

  • The Extension Manager in JupyterLab and the jupyter labextension install command install extension packages from npm. These require Node.js and a JupyterLab rebuild to activate. See Installing Node.js and Managing Extensions with jupyter labextension.

Installing Node.js

Some extensions require Node.js to rebuild JupyterLab and activate the extension. If you use conda with conda-forge packages, you can get Node.js with:

conda install -c conda-forge nodejs

If you use conda with default Anaconda packages (i.e., you don’t normally use conda-forge), you should install Node.js from the Anaconda default channel with conda install nodejs instead.

You may also be able to get Node.js from your system package manager, or you can download Node.js from the Node.js website and install it directly.

Managing Extensions with jupyter labextension

The jupyter labextension command enables you to install or uninstall extensions from npm, list all installed extensions, or disable any extension. See the help with jupyter labextension --help.

Installing and Uninstalling Extensions

You can install extensions from npm with:

jupyter labextension install my-extension my-other-extension

Use the my-extension@version syntax to install a specific version of an extension, for example:

jupyter labextension install my-extension@1.2.3

You can also install an extension that is not uploaded to npm, i.e., my-extension can be a local directory containing the extension, a gzipped tarball, or a URL to a gzipped tarball.

Note

Any extension installed from npm will require installing Node.js and require a rebuild of JupyterLab.

Uninstall extensions that were installed from npm using the command:

jupyter labextension uninstall my-extension my-other-extension

If you are installing/uninstalling several extensions in several stages, you may want to defer rebuilding the application by including the flag --no-build in the install/uninstall step. Once you are ready to rebuild, you can run the command:

jupyter lab build

Note

If you are rebuilding JupyterLab on Windows, you may encounter a FileNotFoundError due to the default path length on Windows. Node modules are stored in a deeply nested directory structure, so paths can get quite long. If you have administrative access and are on Windows 8 or 10, you can update the registry setting using these instructions: https://stackoverflow.com/a/37528731.

Listing installed extensions

List all installed extensions, including those installed with pip or conda, with:

jupyter labextension list

Note

jupyter labextension identifies an extension by its JavaScript package name, which may be different from the name of the pip or conda package used to distribute the extension.

Enabling and Disabling Extensions

Disabling an extension prevents the extension from running in JupyterLab (though the code is still loaded). You can disable specific JupyterLab extensions (including core extensions) without rebuilding JupyterLab with:

jupyter labextension disable my-extension

You can enable a disabled extension with:

jupyter labextension enable my-extension

Managing Extensions Using the Extension Manager

You can use the Extension Manager in JupyterLab to manage extensions that are distributed as single JavaScript packages on npm.

The Extension Manager is in the left sidebar.

TODO: update screenshots

Figure: The default view has three components: a search bar, an “Installed” section, and a “Discover” section.

Disclaimer

Danger

Installing an extension allows it to execute arbitrary code on the server, kernel, and the browser. Therefore, we ask you to explicitly acknowledge this.

By default, the disclaimer is not acknowledged.

Figure: User has not acknowledged the disclaimer

As the disclaimer is not acknowledged, you can search for an extension, but can not install it (no install button is available).

Figure: With Disclaimer unchecked, you can not install an extension

To install an extension, you first have to explicitly acknowledge the disclaimer. Once done, this will remain across sessions and the user does not have to check it again.

Figure: Disclaimer checked

For ease of use, you can hide the disclaimer so it takes less space on your screen.

Figure: Disclaimer is hidden

Finding Extensions

You can use the extension manager to find extensions for JupyterLab. To discovery freely among the currently available extensions, expand the “Discovery” section. This triggers a search for all JupyterLab extensions on the NPM registry, and the results are listed according to the registry’s sort order. An exception to this sort order is that extensions released by the Jupyter organization are always placed first. These extensions are distinguished by a small Jupyter icon next to their name.

Alternatively, you can limit your discovery by using the search bar. This performs a free-text search of JupyterLab extensions on the NPM registry.

Installing an Extension

Once you have found an extension that you think is interesting, install it by clicking the “Install” button of the extension list entry.

Danger

Installing an extension allows it to execute arbitrary code on the server, kernel, and in the client’s browser. You should therefore avoid installing extensions you do not trust, and watch out for any extensions trying to masquerade as a trusted extension.

A short while after starting the install of an extension, a drop-down should appear under the search bar indicating that the extension has been downloaded, but that a rebuild is needed to complete the installation.

If you want to install/uninstall other extensions as well, you can ignore the rebuild notice until you have made all the changes you want. Once satisfied, click the ‘Rebuild’ button to start a rebuild in the background. Once the rebuild completes, a dialog will pop up, indicating that a reload of the page is needed in order to load the latest build into the browser.

If you ignore the rebuild notice by mistake, simply refresh your browser window to trigger a new rebuild check.

Managing Installed Extensions

When there are some installed extensions, they will be shown in the “Installed” section. These can then be uninstalled or disabled. Disabling an extension will prevent it from being activated, but without rebuilding the application.

Companion packages

During installation of an extension, JupyterLab will inspect the package metadata for any instructions on companion packages. Companion packages can be:

  • Notebook server extensions (or any other packages that need to be installed on the Notebook server).

  • Kernel packages. An example of companion packages for the kernel are Jupyter Widget packages, like the ipywidgets Python package for the @jupyter-widgets/jupyterlab-manager package.

If JupyterLab finds instructions for companion packages, it will present a dialog to notify you about these. These are informational only, and it will be up to you to take these into account or not.

Listings

When searching extensions in the Extension Manager, JupyterLab displays the complete search result and the user is free to install any extension. This is the Default mode.

To bring more security, you or your administrator can enable blocklists or allowlists mode. JupyterLab will check the extensions against the defined listings.

Warning

Only one mode at a time is allowed. If you or your server administrator configures both block and allow listings, the JupyterLab server will not start.

Figure: Simultaneous block and allow listings

The following details the behavior for the Blocklist mode and the Allowlist mode. The details to enable configure the listings can be read Listing Configuration.

Default mode

In the default mode, no listing is enabled and the search behavior is unchanged and is the one described previously.

Blocklist mode

Extensions can be freely downloaded without going through a vetting process. However, users can add malicious extensions to a blocklist. The extension manager will show all extensions except for those that have been explicitly added to the blocklist. Therfore, the extension manager does not allow you to install blocklisted extensions.

If you, or your administrator, has enabled the blocklist mode, JupyterLab will use the blocklist and remove all blocklisted extensions from your search result.

If you have installed an extension before it has been blocklisted, the extension entry in the installed list will be highlighted in red. It is recommended that you uninstall it. You can move your mouse on the question mark icon to read the instructions.

Figure: Blocklisted installed extension which should be removed

Allowlist mode

An allowlist maintains a set of approved extensions that users can freely search and install. Extensions need to go through some sort of vetting process before they are added to the allowlist. When using an allowlist, the extension manager will only show extensions that have been explicitly added to the allowlist.

If you, or your administrator, has enabled the allowlist mode JupyterLab will use the allowlist and only show extensions present in the withelist. The other extensions will not be show in the search result.

If you have installed an allowlisted extension and at some point in time that extension is removed from the allowlist, the extension entry in the installed list will be highlighted in red. It is recommended that you uninstall it. You can move your mouse on the question mark icon to read the instructions.

Figure: The second of the installed extensions was removed from the allowlist and should be removed

Listing Configuration

You or your administrator can use the following traits to define the listings loading.

  • blocklist_uris: A list of comma-separated URIs to fetch a blocklist file from

  • allowlist_uris: A list of comma-separated URIs to fetch an allowlist file from

  • listings_refresh_seconds: The interval delay in seconds to refresh the lists

  • listings_request_options: The optional kwargs to use for the listings HTTP requests

For example, to enable blocklist, launch the server with --LabServerApp.blocklist_uris=http://example.com/blocklist.json where http://example.com/blocklist.json is a blocklist JSON file as described below.

The details for the listings_request_options are listed on this page (for example, you could pass {'timeout': 10} to change the HTTP request timeout value).

The listings are json files hosted on the URIs you have given.

For each entry, you have to define the name of the extension as published in the NPM registry. The name attribute supports regular expressions.

Optionally, you can also add some more fields for your records (type, reason, creation_date, last_update_date). These optional fields are not used in the user interface.

This is an example of a blocklist file.

{
"blocklist": [
   {
      "name": "@jupyterlab-examples/launcher",
      "type": "jupyterlab",
      "reason": "@jupyterlab-examples/launcher is blocklisted for test purpose - Do NOT take this for granted!!!",
      "creation_date": "2020-03-11T03:28:56.782Z",
      "last_update_date":  "2020-03-11T03:28:56.782Z"
   }
]
}

In the following allowlist example a @jupyterlab/* will allowlist all jupyterlab organization extensions.

{
"allowlist": [
   {
      "name": "@jupyterlab/*",
      "type": "jupyterlab",
      "reason": "All @jupyterlab org extensions are allowlisted, of course...",
      "creation_date": "2020-03-11T03:28:56.782Z",
      "last_update_date":  "2020-03-11T03:28:56.782Z"
   }
]
}