Open in new tab
Lab
Retro
REPL

jupyterlite-pyodide-kernel#

A Python kernel for JupyterLite powered by Pyodide,

Install#

To install the Pyodide kernel labextension and the CLI addons for jupyter lite, run:

pip install jupyterlite-pyodide-kernel

or with conda, mamba, micromamba, etc.

conda install -c conda-forge jupyterlite-pyodide-kernel

For more options see the development install or contributing guide.

Optional Features#

Lock#

Install the [lock] extra for compatible versions of pyodide-lock and uv, used to add local or PyPI packages and their import name and dependency information to the Pyodide lockfile:

from PyPI: jupyterlite-pyodide-kernel[lock]
from conda-forge: jupyterlite-pyodide-kernel-with-lock

Compatibility#

With Jupyter#

status	`jupyterlite-pyodide-kernel`	`jupyterlite-core`	`jupyterlab`	`notebook`	`retrolab`
stable	`0.8.*`	`>=0.8,<0.9`	`>=4.6.0,<4.7`	`>=7.6.0,<7.7`	-
stable	`0.7.*`	`>=0.7,<0.8`	`>=4.5.0,<4.6`	`>=7.5.0,<7.6`	-
stable	`0.6.*`	`>=0.6,<0.7`	`>=4.4.3,<4.5`	`>=7.4.3,<7.5`	-
stable	`0.5.*`	`>=0.5,<0.6`	`>=4.3.0,<4.4`	`>=7.3.0,<7.4`	-
stable	`0.4.*`	`>=0.4,<0.5`	`>=4.2.0,<4.3`	`>=7.2.0,<7.3`	-
stable	`0.3.*`	`>=0.3,<0.4`	`>=4.1.1,<4.2`	`>=7.1.0,<7.2`	-
stable	`0.2.*`	`>=0.2,<0.3`	`>=4.0.7,<4.1`	`>=7.0.5,<7.1`	-
stable	`0.1.*`	`>=0.1,<0.2`	`>=3.5,<3.6`	-	`>=0.3,<0.4`

Installing the matching version of JupyterLab with your package manager can help ensure matching labextension assets and kernel dependencies, even though this kernel does not yet work in a full, jupyter_server-hosted client such as JupyterLab or Notebook.

With Pyodide#

`jupyterlite-pyodide-kernel`	`pyodide`	`python`	`emscripten`	`pyodide-lock`	`uv`
`>=0.1.0,<=0.1.1`	`0.23.*`	`3.10.*`	`3.1.29`
`>=0.1.2,<=0.2.1`	`0.24.*`	`3.10.*`	`3.1.45`
`>=0.2.2,<=0.2.3`	`0.25.*`	`3.11.*`	`3.1.46`
`>=0.3.*,<=0.4.0`	`0.25.*`	`3.11.*`	`3.1.46`
`>=0.4.*,<=0.4.6`	`0.26.*`	`3.12.*`	`3.1.58`
`>=0.4.7,<=0.5.0`	`0.27.*`	`3.12.*`	`3.1.58`
`>=0.5.0,<=0.6.0`	`0.27.*`	`3.12.*`	`3.1.58`
`>=0.6.0,<=0.7.0`	`0.27.*`	`3.12.*`	`3.1.58`
`>=0.7.0,<=0.8.0`	`0.29.*`	`3.13.*`	`4.0.9`
`>=0.8.0,<=0.9.0`	`0.29.*`	`3.13.*`	`4.0.9`	`>=0.1.3,<0.2`	`>=0.9.27`

Note: the Emscripten version is strict down to the patch version.

Usage#

Once installed, building a JupyterLite site will include a kernel which uses the full Pyodide CDN distribution:

jupyter lite build

The build configuration of the Pyodide distribution, the kernel, and package import behavior can be configured in jupyter_lite_config.json. Some features can be configured with CLI aliases and flags. See the full current list by running:

jupyter lite --help

This should show something like the following:

... for configuring the Pyodide distribution

  --pyodide=<Unicode>
      Local path or URL of a pyodide distribution tarball
      Default: ''
      Equivalent to: [--PyodideAddon.pyodide_url]

... adding extra wheels, installable at runtime with %pip

  --piplite-wheels=<typedtuple-item-1>...
      Local paths or URLs of piplite-compatible wheels to copy and index
      Default: ()
      Equivalent to: [--PipliteAddon.piplite_urls]

.... patching the Pyodide lockfile for automatically imported packages

# flags
--pyodide-lock
    Use pyodide-lock and uv to customize pyodide-lock.json
    Equivalent to: [--PyodideLockAddon.enabled=True]
--pyodide-lock-no-constrain-extensions
    Add ``LiteBuildConfig.federated_extensions`` to constraints
    Equivalent to: [--PyodideLockAddon.constrain_extensions=False]

# options
--pyodide-lock-url=<Unicode>
    URL of a remote pyodide-lock.json:
    https://cdn.jsdelivr.net/pyodide/v0.29.3/full/pyodide-lock.json
    Default: ''
    Equivalent to: [--PyodideLockAddon.pyodide_lock_url]
--pyodide-lock-wheels=<typedtuple-item-1>...
    paths to local wheels or folders to include in pyodide-lock.json
    Default: ()
    Equivalent to: [--PyodideLockAddon.wheels]
--pyodide-lock-constraints=<typedtuple-item-1>...
    PEP-508 specs for Python packages to lock only if required in pyodide-
    lock.json; may include ``-r/--requirements`` and  ``-g/--group`` relative to
    ``lite_dir``
    Default: ()
    Equivalent to: [--PyodideLockAddon.constraints]
--pyodide-lock-lite-constraints=<Unicode>
    path relative to ``lite_dir`` to a ``requirements.txt``-style file with
    versions of all `none-any.whl` packages from pyodide-lock.json written if
    missing, otherwise added to ``constraints`` and left unchanged
    Default: ''
    Equivalent to: [--PyodideLockAddon.lite_constraints_file]
--pyodide-lock-specs=<typedtuple-item-1>...
    PEP-508 specs for Python packages to include in pyodide-lock.json; may
    include ``-r/--requirements`` and ``-g/--group`` relative to ``lite_dir``
    Default: ()
    Equivalent to: [--PyodideLockAddon.specs]
--pyodide-lock-excludes=<typedtuple-item-1>...
    extra Python package names to exclude from pyodide-lock.json
    Default: ()
    Equivalent to: [--PyodideLockAddon.excludes_extra]
--pyodide-lock-prefetch=<typedtuple-item-1>...
    extra Python package names from pyodide-lock.json to prefetch while
    initializing Pyodide
    Default: ()
    Equivalent to: [--PyodideLockAddon.prefetch_extra]

Learn more#

⚠️ The documentation for advanced configuration is available from the main JupyterLite documentation site:

Uninstall#

To remove the extension, run:

pip uninstall jupyterlite-pyodide-kernel  # or however you installed it

Prerelease Versions#

To install pre-release versions with pip:

pip install --upgrade --pre jupyterlite-pyodide-kernel

Or, similarly for the conda ecosystem, for alpha packages:

conda install \
  -c conda-forge/label/jupyterlite_core_alpha \
  -c conda-forge/label/jupyterlite_pyodide_kernel_alpha \
  -c conda-forge \
  jupyterlite-pyodide-kernel

Note: _beta and _rc packages would follow a similar channel naming convention

Development Install#

Below is an short overview of getting up and running quickly. Please see the contributing guide for full details.

Development Requirements#

Recommended a Python virtual environment provided by a tool of choice, e.g. one of:

virtualenv
mamba
conda

Ensure the local development environment has:

git
nodejs 22
python >=3.8

Development Quick Start#

git clone https://github.com/jupyterlite/pyodide-kernel
cd pyodide-kernel
npm run quickstart

Then, serve the built demo site, documentation, and test reports with Python’s built-in HTTP server:

jlpm serve