Emscripten Environment#

Pre-installed packages#

jupyterlite-xeus allows you to pre-install packages in the runtime. You can pre-install packages by adding an environment.yml file in the JupyterLite build directory, this file will be found automatically by jupyterlite-xeus which will pre-build the environment when running jupyter lite build.

Furthermore, this automatically installs any labextension that it founds, for example installing ipyleaflet will make ipyleaflet work without the need to manually install the jupyter-leaflet labextension.

Say you want to install NumPy, Matplotlib and ipycanvas, it can be done by creating the environment.yml file with the following content:

name: xeus-python-kernel
channels:
  - https://repo.mamba.pm/emscripten-forge
  - conda-forge
dependencies:
  - xeus-python
  - numpy
  - matplotlib
  - ipycanvas

Then you only need to build JupyterLite:

jupyter lite build

You can also pick another name for that environment file (e.g. custom.yml), by doing so, you will need to specify that name to xeus-python:

jupyter lite build --XeusAddon.environment_file=custom.yml

Warning

It is common to provide pip dependencies in a conda environment file. This is currently partially supported by jupyterlite-xeus. See “pip packages” section.

Then those packages are usable directly:

Try it!

Python 3.13 support#

If you specify the emscripten-forge mirror published on prefix.dev, you will be able to use Python 3.13 in your deployment.

⚠ This is still a work-in-progress feature and some packages may be missing ⚠

name: xeus-python-kernel
channels:
  - https://repo.prefix.dev/emscripten-forge-dev
  - conda-forge
dependencies:
  - xeus-python
  - numpy

Multi environment support#

Starting with jupyterlite-xeus v4.0.0a0, you can now pass multiple environment files or prefixes.

jupyter lite build --XeusAddon.environment_file=environment-python.yml --XeusAddon.environment_file=environment-r.yml

⚠ This feature is experimental, installing the same kernel in two environments does not work currently. This feature is only useful for e.g. splitting a R environment from a Python environment ⚠

pip packages#

⚠ This feature is experimental. You won’t have the same user-experience as when using conda/mamba in a “normal” setup ⚠

jupyterlite-xeus provides a way to install packages with pip.

There are a couple of limitations that you should be aware of:

  • it can only install pure Python packages (Python code + data files)

  • it does not install the package dependencies, you should make sure to install them yourself using conda-forge/emscripten-forge.

  • it does not work (yet?) using -r requirements.txt in your environment file

For example, if you were to install ipycanvas from PyPI, you would need to install the ipycanvas dependencies for it to work (pillow, numpy and ipywidgets):

name: xeus-python-kernel
channels:
  - https://repo.mamba.pm/emscripten-forge
  - conda-forge
dependencies:
  - xeus-python
  - numpy
  - pillow
  - ipywidgets
  - pip:
      - ipycanvas

You can also install a local Python package, this is very practical if you want to embed a jupyterlite deployment in your Package documentation, allowing to test the very latest dev version:

name: xeus-python-kernel
channels:
  - https://repo.mamba.pm/emscripten-forge
  - conda-forge
dependencies:
  - xeus-python
  - pip:
      - ..