Adding extensions#

JupyterLite reuses the same system of prebuilt extensions as in JupyterLab 3.0+. Prebuilt extensions are also sometimes called federated extensions. In JupyterLab they can be installed via pip and conda without rebuilding the whole JupyterLab application.

All the applications shipped with JupyterLite by default are built with JupyterLab components. This allows for most of the existing third-party JupyterLab extensions to also work with JupyterLite.

Adding new extensions from an environment#

Creating a new environment#

The easiest way to add new extensions is to use the JupyterLite CLI in a Python environment where extensions have already been installed.

You can choose the tool of your choice to manage these dependencies, such as pip, conda or mamba. For conda and mamba there are typically defined in environment.yml, and in requirements.txt for pip.

If you want to build a JupyterLite website locally on your machine, it is preferable to first create a new environment.

This can be done with the venv module:

python -m venv .
source bin/activate

Or with conda / mamba:

mamba create -n my-jupyterlite-deployment -c conda-forge python -y
mamba activate my-jupyterlite-deployment

Installing the extensions in the environment#

As an example let’s use the following requirements.txt:

jupyterlab-tour
jupyterlab-night

This file defines list two extensions, one of them is a theme. Run the following command to install them:

python -m pip install -r requirements.txt

If you have jupyterlab installed, you can verify they are correctly installed with:

jupyter labextension list

Which should return something similar to the following:

JupyterLab v4.*.*
PREFIX/share/jupyter/labextensions
        jupyterlab-tour  v4.0.1 enabled OK
        jupyterlab-night v0.4.0 enabled OK

Build the JupyterLite website#

Now we need to produce the JupyterLite archive that will include these extensions. This can be done with the following command:

jupyter lite build

When you run jupyter lite build, all pre-built extensions in your JupyterLab environment, e.g. {sys.prefix}/share/jupyter/labextensions will be:

copied to {output-dir}/extensions
have their theme information copied to {output-dir}/{app/?}theme/

The case of Jupyter Widgets and custom renderers#

Some extensions like Jupyter Widgets and custom renderers also need a Python package to be installed at runtime when working with a notebook. This is for example the case with ipyleaflet, bqplot or plotly.

To install the frontend extensions, simply add it to the list of requirements. For example continuing from the requirements.txt file defined above:

jupyterlab-tour
jupyterlab-night
ipywidgets
bqplot
plotly

The end users of your JupyterLite instance will still need to install the dependencies at runtime in their notebooks with the IPython-compatible %pip magic:

%pip install -q ipywidgets bqplot plotly

which translates to:

import piplite
await piplite.install(["ipywidgets", "bqplot", "plotly"])

Avoid the drift of versions between the frontend extension and the Python package#

In some situations, the versions of the packages installed at runtime with %pip install or piplite.install might not be compatible with the deployed frontend extension anymore. This can for example happen when a JupyterLite website was built and deployed a couple of weeks ago, and new versions of the Python packages were released since. In that case the frontend extension have not been updated since they are still available as static files as part of the deployment.

One way to avoid this mismatch is to pin the dependencies more explicitly. For example:

ipywidgets==7.7.0
bqplot==0.12.30
plotly==5.8.0

The user-facing code in the notebook will then also have to use the same versions to stay compatible:

%pip install -q "ipywidgets==7.7.0" "bqplot==0.12.30" "plotly==5.8.0"

which translates to:

import piplite
await piplite.install(["ipywidgets==7.7.0", "bqplot==0.12.30", "plotly==5.8.0"])

This is unfortunately a little bit brittle but does the job for now. There is chance this will be improved in future versions of JupyterLite.

Check out the guide on configuring the piplite URLs if you want to have more control on your dependencies.

How to know if an extension is compatible with JupyterLite?#

A good starting point for extensions that might work is the JupyterLab issue Extension Compatibility with 3.0 (#9461). Additionally, this site demonstrates a few extensions.

Advanced extension configuration#

If you are looking for more options to configure extensions, check out the dedicated guide on Advanced extension configuration.