Migration Guide#

This guide provides an overview of major (potentially breaking) changes and the steps to follow to update JupyterLite from one version to another.

0.1.0 to 0.2.0#

Extensions#

JupyterLite 0.2.0 is based on the JupyterLab 4 and Jupyter Notebook 7 packages.

JupyterLab 4 comes with a couple of breaking changes which likely affect extensions.

If you were using JupyterLab 3 extensions in your JupyterLite deployment, you might have to update to a newer version of the extension that is compatible with JupyterLab 4.

Note

For extensions authors, check out the extension migration guide in the JupyterLab documentation.

Jupyter Notebook 7#

In JupyterLite 0.1.x the Notebook interface was provided by RetroLab.

In JupyterLite 0.2.0, the Notebook interface is now provided by Jupyter Notebook 7

Jupyter Notebook 7 is the successor of RetroLab and the Classic Notebook, based on JupyterLab components.

This means the URL have also changed to be aligned with the ones provided by Jupyter Notebook 7:

  • /retro/consoles -> /consoles

  • /retro/edit -> /edit

  • /retro/notebooks -> /notebooks

  • /retro/tree -> /tree

jupyterlite metapackage#

In version 0.1.x, installing the jupyterlite metapackage would automatically install the Pyodide kernel by default, since the jupyterlite metapackage would depend on jupyterlite-pyodide-kernel.

In version 0.2.0 this is not the case anymore. You will need to install the jupyterlite-pyodide-kernel explicitely in your build environment alongside jupyterlite-core (the package providing the jupyter-lite CLI).

See the documentation for adding kernels to learn more.

Service Worker#

The service worker file name has been changed. In 0.1.0, it was service-worker-[hash].js with the hash computed by webpack, in 0.2.0 the hash is removed and the new file name is service-worker.js.

API changes#

jupyterlite-core#

  • The Mathjax addon was removed from the jupyterlite-core package. As a consequence the mathjaxConfig and fullMathjaxUrl options in jupyter-lite.json can be removed as they do not have any effect anymore.

    If you would like to use Mathjax 2, it’s possible to install jupyterlab-mathjax2. See the jupyter-renderers repository for more information.

    For reference, see the JupyterLab Pull Request that updated to Mathjax 3

@jupyterlite packages#

These API changes are only relevant if you are reusing @jupyterlite packages in downstream applications.

  • The IKernel interface exposed by @jupyterlite/kernels has a new get method to retrieve a running kernel by id.

0.1.0b19 to 0.1.0b20#

jupyterlite-core#

The static assets distributed via the jupyterlite-core package do not include the JavaScript kernel anymore.

Instead the JavaScript kernel is now distributed via the separate jupyterlite-javascript-kernel package.

If you would like to include the JavaScript kernel in your deployment you will have to first install it before building the JupyterLite site. For example with:

python -m pip install jupyterlite-javascript-kernel

Or add it to the LiteBuildConfig/federated_extensions config entry.

Currently the jupyterlite package still includes the JavaScript kernel via a dependency on jupyterlite-javascript-kernel. But this might change in a future version.

We recommend you start using the jupyterlite-core package directly for your deployments, and explicitly add more kernels such as jupyterlite-pyodide-kernel or jupyterlite-javascript-kernel.

0.1.0b18 to 0.1.0b19#

jupyterlite-core#

This release introduces a new jupyterlite-core package in addition to the existing jupyterlite package.

The jupyterlite-core package provides the core functionality for building JupyterLite websites CLI extension points. Currently it only includes a JavaScript kernel that runs in Web Worker. If you would like to include a Python kernel in your deployment yyou will have to first install it before building the JupyterLite site. For example with:

python -m pip install jupyterlite-pyodide-kernel

Or add it to the LiteBuildConfig/federated_extensions config entry.

The jupyterlite package currently provides a couple of shims as well as the Pyodide kernel for better compatibility with existing deployments.

We recommend you start using the jupyterlite-core package for your deployments, and additionally install a Python kernel such as jupyterlite-pyodide-kernel or jupyterlite-xeus-python.

jupyterlite-pyodide-kernel#

The Pyodide kernel has been moved to its own repo: jupyterlite/pyodide-kernel

Currently it is still installed by default with jupyterlite for convenience, but it is not part of jupyterlite-core.

A consequence of this change is the renaming of the pyolite JavaScript packages:

  • @jupyterlite/pyolite-kernel -> @jupyterlite/pyodide-kernel

  • @jupyterlite/pyolite-kernel-extension -> @jupyterlite/pyodide-kernel-extension

Make sure to update your config if you were making use of litePluginSettings.

0.1.0b17 to 0.1.0b18#

The JavaScript kernel now runs in a Web Worker instead of an IFrame, to streamline how default kernels run in JupyterLite.

This might affect custom kernel authors extending the base JavaScriptKernel like https://github.com/jupyterlite/p5-kernel.

This was changed in the following PR: #711

0.1.0b16 to 0.1.0b17#

Use PipliteAddon.piplite_urls instead of LiteBuildConfig.piplite_urls#

If you were configuring the piplite_urls option (described in https://jupyterlite.readthedocs.io/en/latest/howto/python/wheels.html) to ship additional wheels at build time, this configuration option has now been moved from LiteBuildConfig.piplite_urls to PipliteAddon.piplite_urls.

If using a jupyter_lite_build.json file, the configuration should look like the following:

{
  "PipliteAddon": {
    "piplite_urls": ["url-to-wheel1", "url-to-wheel2", "..."]
  }
}

This was changed in the following PR: #934