Deploy JupyterLite on a standalone server or locally#

Deploying a JupyterLite site requires:

  • a copy of the JupyterLite site assets

    • often provided by the pip-installable python package jupyterlite-core

  • an option set of configurations for the site and different apps

    • different options offer trade-offs between reproducibility, build speed, deployment size, and end-user performance, privacy, and security

Get an Empty JupyterLite Site#

The minimum deployable site archive contains enough to run all of the default applications, but no content.

Hint

Use of the CLI is optional, but recommended. It offers substantially better integration with other Jupyter tools.

To get the Python CLI and API from PyPI:

python -m pip install jupyterlite-core

You can also install the CLI from conda forge with conda:

conda install -c conda-forge jupyterlite-core

Or mamba:

mamba install -c conda-forge jupyterlite-core

To build an empty site (just the JupyterLite static assets):

jupyter lite init

By default the JupyterLite website will be placed in the _output folder. You can specific a different with --output-dir parameter. For instance:

jupyter lite build --output-dir dist

Note

By default the jupyterlite-core package does not provide any kernels. If you would like to install one in your environment you would need to install it in your build environment. For example to install the Pyodide kernel for JupyterLite:

python -m pip install jupyterlite-pyodide-kernel

Then make sure to rerun the jupyter lite build command.

Customizing the site#

By default the JupyterLite site will be empty, but you can customize it by adding your own content and configuration.

The documentation includes several how-to guides for customizing the site:

Check out the list of how-to guides for more information.

Standalone Servers#

Now that the static assets have been built, you can use a plain HTTP server to serve them and access JupyterLite from a web browser.

Suitable for local development, many languages provide easy-to-use servers that can serve your JupyterLite locally while you get it working the way you want.

Warning

Serving some of the kernels requires that your web server supports serving application/wasm files with the correct headers

Hint

An HTTPS-capable server is recommended for all but the simplest localhost cases.

jupyter lite serve#

The jupyter lite serve command offers either a web server powered by Python’s built-in http.server or tornado, which is likely to be available if any other Jupyter tools are installed.

In the same directory, run the following command to start the server:

jupyter lite serve

Note

More options are also available such as changing the port and log level. Check out the help with jupyter lite serve --help to learn more.

Jupyter#

If you’re already running a Jupyter Server-powered app, such as JupyterLab, your files will be served correctly on e.g. http://localhost:8888/files.

Python#

http.server#

The http module in the Python standard library is a suitably-effective server for local purposes.

python -m http.server -b 127.0.0.1

If you are using a recently-released Python 3.7+, this will correctly serve application/wasm files for WebAssembly kernels.

NodeJS#

Most nodejs-based servers will be able to host JupyterLite without any problems. Note, however, that http-server does not support the application/wasm MIME type.

Using a release archive#

As an alternative to using the jupyterlite CLI, you can also download a release archive from the GitHub Releases page.

Download it an extract it, then use one of the approaches mentioned above to start the server.

Nightly and work-in-progress archives are also available from GitHub actions.