Deploying a JupyterLite site requires:

  • a copy of the JupyterLite site assets

    • often provided by the pip-installable python package jupyterlite

  • 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

  • a local, on-premises, or hosted HTTP server (doesn’t presently work with file:// URLs)


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


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

Get an Empty JupyterLite Site#

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


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 --pre jupyterlite
# TODO: mamba install jupyterlite

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

jupyter lite init

Static Site: The Hard Way#

  • download a release archive from GitHub Releases

  • download nightly/work-in-progress builds from GitHub actions

  • clone/fork the [repository] and do a development build

  • TBD: use cookiecutter-jupyterlite

  • TBD: yarn add @jupyterlite/builder from


It is recommended to put these files under revision control. See Configuring for what you can configure in your JupyterLite.

Build Tools#

While the JupyterLite CLI will create the correct assets for JupyterLite, it might not be enough to deploy along with the rest of your content.


At present, the core JupyterLite site and apps are not published as reusable packages. At some point in the future, a WebPack plugin might allow for integrating at this level.


Sphinx is the workhorse of documentation of not only the scientific Python documentation community, but also the broader Python ecosystem, and many languages beyond it. It is well adapted to building sites of any size, and tools like myst-nb enable make it very palletable to include executable, and even interactive, content.

JupyterLite assets can be copied to the default static directory in, e.g. docs/_static with html_static_path, or replace the entire site with html_extra_path


This search path can be merged several layers deep, such that your theme assets, the “gold master” JupyterLite assets, and any customizations you wish to make are combined.

html_static_path = [
    "../my-jupyterlite"        # <- these "win"

The composite directory will end up in docs/_build/_static.


See the JupyterLite for an example approach, though it’s likely a good deal more complicated than you will need, because it needs to build itself first! This complexity is managed in


A slightly more aggressive approach is to use html_extra_path to simply dump the assets directly into the doc folder. This approach can be used to deploy a site that launches directly into your JupyterLite.

Adapting the example above:

html_extra_path = ["../upstream-jupyterlite", "../my-jupyterlite"]

Again, the last-written index.html will “win” and be shown to visitors to /, which will immediately redirect to appUrl as defined in the schema.

Standalone Servers#


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.

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.


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.



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

python -m http.server -b

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


If using Sphinx, sphinx-autobuild provides a convenient way to manage both static content and rich interactive HTML like your JupyterLite.

sphinx-autobuild docs docs/_build

This will regenerate your docs site and automatically refresh any browsers you have open. As your JupyterLite is mostly comprised of static assets, changes will not trigger a refresh by default.

Enabling the -a flag will allow reloading when static assets change, but at the price rebuild the whole site when any file changes… this can be improved with the -j<N> flag, but is not compatible with all sphinx extensions.

sphinx-autobuild docs docs/_build -aj8


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.










A JupyterLite can be deployed behind jupyter-server-proxy using any local server method. This is a good way to preview deployment interactively of a e.g. Lab extension that can work in both the “full” binder experience, and as a static preview.


See the JupyterLite binder configuration for an example.


The Sphinx deployment approach will work almost transparently with ReadTheDocs, for the small price of a .readthedocs.yml file in the root of your repository.


See the JupyterLite .readthedocs.yml for an example.


You might also want to enable the Autobuild Documentation for Pull Requests feature of Read The Docs to automatically get a preview link when opening a new pull request:



Netlify makes it easy and convenient to host static websites from existing git repositories, and make them widely available via their CDN.

To deploy your own JupyterLite on Netlify, you can start from the JupyterLite Demo by generating a new repository from the template.

Then add a runtime.txt file with 3.7 as the content to specify Python 3.7 as dependency.

Finally specify jupyter lite build --output-dir dist as the “Build Command”, and dist as “Published Directory”:


You might also want to specify the --debug flag to get extra log messages:



Just like Netlify, Vercel can connect to an existing git repository and seamlessly deploy static files on push and PR events (previews).

Unfortunately, their build image only includes Python 3.6 and JupyterLite requires Python 3.7+.

Fortunately it is possible to run arbitrary bash scripts, which provides a convenient escape hatch.

Specify the Python packages in a requirements-deploy.txt file with additional dependencies if needed:


Then create a new file with the following content:


yum install wget

wget -qO- | tar -xvj bin/micromamba

./bin/micromamba shell init -s bash -p ~/micromamba
source ~/.bashrc

# activate the environment and install a new version of Python
micromamba activate
micromamba install python=3.9 -c conda-forge -y

# install the dependencies
python -m pip install -r requirements-deploy.txt

# build the JupyterLite site
jupyter lite --version
jupyter lite build --output-dir dist

Micromamba creates a new self-contained environment, which makes it very convenient to install any required package without being limited by the build image.

Then configure the build command and output directory on Vercel:


You might also want to specify the --debug flag to get extra log messages:

jupyter lite build --debug

GitHub Pages#

JupyterLite can easily be deployed on GitHub Pages, using the jupyterlite CLI to add content and extensions.


See the JupyterLite Demo for an example. That repository is a GitHub template repository which makes it convenient to generate a new JupyterLite site with a single click.

GitLab Pages#

JupyterLite can easily be deployed on GitLab Pages, using the jupyterlite CLI and setting the output_path to the public folder in your .gitlab-ci.yml file.

Suppose that your notebooks are stored in the content folder; and you don’t require any additional python dependencies and configuration overrides, the .gitlab-ci.yml could look like.

image: python
  stage: deploy
    - python -m pip install jupyterlite
    - jupyter lite build --contents content --output-dir public
      - public # mandatory, other folder won't work
    - main # the branch you want to publish


See the gitlab pages template for a more involved example.