CLI#

Hide code cell content 
import os, pathlib, tempfile, shutil, atexit, hashlib, pprint
from IPython.display import *
from IPython import get_ipython  # needed for `jupyter_execute` because magics?

RTD = os.environ.get("READTHEDOCS")

The jupyter lite (or jupyter-lite) CLI provides tools for lifecycle of combining…

  • the core JupyterLite static assets

  • extra application features like Lab Extensions and settings

  • kernel-specific resources like Python wheels

  • user-authored content like Notebooks

… into a ready-to-deploy (and optionally reproducible) Jupyter sites which require an HTTP server, but no application server.

Installation#

!pip install jupyterlite-core
!jupyter lite --version

Requirement already satisfied: jupyterlite-core in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (0.2.0a1)
Requirement already satisfied: doit<1,>=0.34 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite-core) (0.36.0)
Requirement already satisfied: jupyter-core>=4.7 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite-core) (5.3.1)
Requirement already satisfied: cloudpickle in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from doit<1,>=0.34->jupyterlite-core) (2.2.1)
Requirement already satisfied: importlib-metadata>=4.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from doit<1,>=0.34->jupyterlite-core) (6.8.0)
Requirement already satisfied: platformdirs>=2.5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-core>=4.7->jupyterlite-core) (3.10.0)
Requirement already satisfied: traitlets>=5.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-core>=4.7->jupyterlite-core) (5.10.0)

Requirement already satisfied: zipp>=0.5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from importlib-metadata>=4.4->doit<1,>=0.34->jupyterlite-core) (3.17.0)

DEPRECATION: sphinxext-rediraffe main has a non-standard version number. pip 23.3 will enforce this behaviour change. A possible replacement is to upgrade to a newer version of sphinxext-rediraffe or contact the author to suggest that they release a version with a conforming version number. Discussion can be found at https://github.com/pypa/pip/issues/12063


0.2.0a1

Addon Dependencies#

Some extra features of different addons have additional dependencies.

pip install jupyterlite-core[contents] # jupyter_server for contents API indexing
pip install jupyterlite-core[serve]    # tornado for better local previewing with `serve`
pip install jupyterlite-core[mathjax]  # reuse the MathJax assets from jupyter-server-mathjax
pip install jupyterlite-core[check]    # validate more data with jsonschema
pip install jupyterlite-core[lab]      # a known-compatible jupyterlab (entails `contents`, `serve`, `check`)

…or, for everything:

pip install jupyterlite-core[all]      # all of the above!

!pip install jupyterlite-core[all]
Hide code cell output 
Requirement already satisfied: jupyterlite-core[all] in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (0.2.0a1)

Requirement already satisfied: doit<1,>=0.34 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite-core[all]) (0.36.0)
Requirement already satisfied: jupyter-core>=4.7 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite-core[all]) (5.3.1)
Requirement already satisfied: jsonschema>=3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite-core[all]) (4.19.1)
Requirement already satisfied: jupyter-server in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite-core[all]) (2.7.3)
Requirement already satisfied: jupyter-server-mathjax>=0.2.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite-core[all]) (0.2.6)
Requirement already satisfied: jupyterlab-server<3,>=2.8.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite-core[all]) (2.25.0)
Requirement already satisfied: jupyterlab<5.0,>=4.0.5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite-core[all]) (4.0.6)
Requirement already satisfied: libarchive-c>=4.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite-core[all]) (5.0)
Requirement already satisfied: pkginfo in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite-core[all]) (1.9.6)
Requirement already satisfied: tornado>=6.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlite-core[all]) (6.3.3)
Requirement already satisfied: cloudpickle in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from doit<1,>=0.34->jupyterlite-core[all]) (2.2.1)
Requirement already satisfied: importlib-metadata>=4.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from doit<1,>=0.34->jupyterlite-core[all]) (6.8.0)
Requirement already satisfied: attrs>=22.2.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jsonschema>=3->jupyterlite-core[all]) (23.1.0)
Requirement already satisfied: jsonschema-specifications>=2023.03.6 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jsonschema>=3->jupyterlite-core[all]) (2023.7.1)
Requirement already satisfied: referencing>=0.28.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jsonschema>=3->jupyterlite-core[all]) (0.30.2)
Requirement already satisfied: rpds-py>=0.7.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jsonschema>=3->jupyterlite-core[all]) (0.10.3)
Requirement already satisfied: platformdirs>=2.5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-core>=4.7->jupyterlite-core[all]) (3.10.0)
Requirement already satisfied: traitlets>=5.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-core>=4.7->jupyterlite-core[all]) (5.10.0)

Requirement already satisfied: anyio>=3.1.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (4.0.0)
Requirement already satisfied: argon2-cffi in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (23.1.0)
Requirement already satisfied: jinja2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (3.1.2)
Requirement already satisfied: jupyter-client>=7.4.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (8.3.1)
Requirement already satisfied: jupyter-events>=0.6.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (0.7.0)
Requirement already satisfied: jupyter-server-terminals in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (0.4.4)
Requirement already satisfied: nbconvert>=6.4.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (7.8.0)
Requirement already satisfied: nbformat>=5.3.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (5.9.2)
Requirement already satisfied: overrides in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (7.4.0)
Requirement already satisfied: packaging in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (23.1)
Requirement already satisfied: prometheus-client in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (0.17.1)
Requirement already satisfied: pyzmq>=24 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (25.1.1)
Requirement already satisfied: send2trash>=1.8.2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (1.8.2)
Requirement already satisfied: terminado>=0.8.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (0.17.1)
Requirement already satisfied: websocket-client in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-server->jupyterlite-core[all]) (1.6.3)

Requirement already satisfied: async-lru>=1.0.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (2.0.4)
Requirement already satisfied: ipykernel in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (6.25.2)
Requirement already satisfied: jupyter-lsp>=2.0.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (2.2.0)
Requirement already satisfied: notebook-shim>=0.2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (0.2.3)
Requirement already satisfied: tomli in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (2.0.1)

Requirement already satisfied: babel>=2.10 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab-server<3,>=2.8.1->jupyterlite-core[all]) (2.12.1)
Requirement already satisfied: json5>=0.9.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab-server<3,>=2.8.1->jupyterlite-core[all]) (0.9.14)
Requirement already satisfied: requests>=2.31 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyterlab-server<3,>=2.8.1->jupyterlite-core[all]) (2.31.0)
Requirement already satisfied: idna>=2.8 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from anyio>=3.1.0->jupyter-server->jupyterlite-core[all]) (3.4)
Requirement already satisfied: sniffio>=1.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from anyio>=3.1.0->jupyter-server->jupyterlite-core[all]) (1.3.0)
Requirement already satisfied: exceptiongroup>=1.0.2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from anyio>=3.1.0->jupyter-server->jupyterlite-core[all]) (1.1.3)
Requirement already satisfied: typing-extensions>=4.0.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from async-lru>=1.0.0->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (4.8.0)

Requirement already satisfied: zipp>=0.5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from importlib-metadata>=4.4->doit<1,>=0.34->jupyterlite-core[all]) (3.17.0)
Requirement already satisfied: MarkupSafe>=2.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jinja2->jupyter-server->jupyterlite-core[all]) (2.1.3)

Requirement already satisfied: python-dateutil>=2.8.2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-client>=7.4.4->jupyter-server->jupyterlite-core[all]) (2.8.2)
Requirement already satisfied: python-json-logger>=2.0.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-events>=0.6.0->jupyter-server->jupyterlite-core[all]) (2.0.7)
Requirement already satisfied: pyyaml>=5.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-events>=0.6.0->jupyter-server->jupyterlite-core[all]) (6.0.1)
Requirement already satisfied: rfc3339-validator in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-events>=0.6.0->jupyter-server->jupyterlite-core[all]) (0.1.4)
Requirement already satisfied: rfc3986-validator>=0.1.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jupyter-events>=0.6.0->jupyter-server->jupyterlite-core[all]) (0.1.1)

Requirement already satisfied: beautifulsoup4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter-server->jupyterlite-core[all]) (4.12.2)
Requirement already satisfied: bleach!=5.0.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter-server->jupyterlite-core[all]) (6.0.0)
Requirement already satisfied: defusedxml in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter-server->jupyterlite-core[all]) (0.7.1)
Requirement already satisfied: jupyterlab-pygments in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter-server->jupyterlite-core[all]) (0.2.2)
Requirement already satisfied: mistune<4,>=2.0.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter-server->jupyterlite-core[all]) (3.0.1)
Requirement already satisfied: nbclient>=0.5.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter-server->jupyterlite-core[all]) (0.7.4)
Requirement already satisfied: pandocfilters>=1.4.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter-server->jupyterlite-core[all]) (1.5.0)
Requirement already satisfied: pygments>=2.4.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter-server->jupyterlite-core[all]) (2.16.1)
Requirement already satisfied: tinycss2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbconvert>=6.4.4->jupyter-server->jupyterlite-core[all]) (1.2.1)
Requirement already satisfied: fastjsonschema in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from nbformat>=5.3.0->jupyter-server->jupyterlite-core[all]) (2.18.0)

Requirement already satisfied: charset-normalizer<4,>=2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from requests>=2.31->jupyterlab-server<3,>=2.8.1->jupyterlite-core[all]) (3.2.0)
Requirement already satisfied: urllib3<3,>=1.21.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from requests>=2.31->jupyterlab-server<3,>=2.8.1->jupyterlite-core[all]) (2.0.5)
Requirement already satisfied: certifi>=2017.4.17 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from requests>=2.31->jupyterlab-server<3,>=2.8.1->jupyterlite-core[all]) (2023.7.22)

Requirement already satisfied: ptyprocess in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from terminado>=0.8.3->jupyter-server->jupyterlite-core[all]) (0.7.0)
Requirement already satisfied: argon2-cffi-bindings in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from argon2-cffi->jupyter-server->jupyterlite-core[all]) (21.2.0)

Requirement already satisfied: comm>=0.1.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (0.1.4)
Requirement already satisfied: debugpy>=1.6.5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (1.8.0)
Requirement already satisfied: ipython>=7.23.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (8.15.0)
Requirement already satisfied: matplotlib-inline>=0.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (0.1.6)
Requirement already satisfied: nest-asyncio in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (1.5.6)
Requirement already satisfied: psutil in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (5.9.5)

Requirement already satisfied: six>=1.9.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from bleach!=5.0.0->nbconvert>=6.4.4->jupyter-server->jupyterlite-core[all]) (1.16.0)
Requirement already satisfied: webencodings in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from bleach!=5.0.0->nbconvert>=6.4.4->jupyter-server->jupyterlite-core[all]) (0.5.1)

Requirement already satisfied: backcall in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython>=7.23.1->ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (0.2.0)
Requirement already satisfied: decorator in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython>=7.23.1->ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (5.1.1)
Requirement already satisfied: jedi>=0.16 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython>=7.23.1->ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (0.19.0)
Requirement already satisfied: pickleshare in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython>=7.23.1->ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (0.7.5)
Requirement already satisfied: prompt-toolkit!=3.0.37,<3.1.0,>=3.0.30 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython>=7.23.1->ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (3.0.39)
Requirement already satisfied: stack-data in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython>=7.23.1->ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (0.6.2)

Requirement already satisfied: pexpect>4.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from ipython>=7.23.1->ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (4.8.0)
Requirement already satisfied: fqdn in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jsonschema>=3->jupyterlite-core[all]) (1.5.1)
Requirement already satisfied: isoduration in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jsonschema>=3->jupyterlite-core[all]) (20.11.0)
Requirement already satisfied: jsonpointer>1.13 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jsonschema>=3->jupyterlite-core[all]) (2.4)
Requirement already satisfied: uri-template in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jsonschema>=3->jupyterlite-core[all]) (1.3.0)
Requirement already satisfied: webcolors>=1.11 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jsonschema>=3->jupyterlite-core[all]) (1.13)

Requirement already satisfied: cffi>=1.0.1 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from argon2-cffi-bindings->argon2-cffi->jupyter-server->jupyterlite-core[all]) (1.15.1)

Requirement already satisfied: soupsieve>1.2 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from beautifulsoup4->nbconvert>=6.4.4->jupyter-server->jupyterlite-core[all]) (2.5)

Requirement already satisfied: pycparser in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from cffi>=1.0.1->argon2-cffi-bindings->argon2-cffi->jupyter-server->jupyterlite-core[all]) (2.21)

Requirement already satisfied: parso<0.9.0,>=0.8.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from jedi>=0.16->ipython>=7.23.1->ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (0.8.3)
Requirement already satisfied: wcwidth in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from prompt-toolkit!=3.0.37,<3.1.0,>=3.0.30->ipython>=7.23.1->ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (0.2.6)

Requirement already satisfied: arrow>=0.15.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from isoduration->jsonschema>=3->jupyterlite-core[all]) (1.2.3)

Requirement already satisfied: executing>=1.2.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from stack-data->ipython>=7.23.1->ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (1.2.0)
Requirement already satisfied: asttokens>=2.1.0 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from stack-data->ipython>=7.23.1->ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (2.4.0)
Requirement already satisfied: pure-eval in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages (from stack-data->ipython>=7.23.1->ipykernel->jupyterlab<5.0,>=4.0.5->jupyterlite-core[all]) (0.2.2)

DEPRECATION: sphinxext-rediraffe main has a non-standard version number. pip 23.3 will enforce this behaviour change. A possible replacement is to upgrade to a newer version of sphinxext-rediraffe or contact the author to suggest that they release a version with a conforming version number. Discussion can be found at https://github.com/pypa/pip/issues/12063

Installing a kernel#

The jupyterlite-core package provides the core functionality for building JupyterLite websites and does not install any kernels by default.

If you would like to include a kernel in your JupyterLite deployment you need to install it before building the site.

For example to also include the Python kernel based on Pyodide:

pip install jupyterlite-pyodide-kernel

Quick Start#

Once installed, one can get to a locally-hosted, empty JupyterLite site with:

jupyter lite serve

This will:

  • init the baseline assets

  • build all extra assets

    • if a files/ folder is found, those will be copied into _output/files

      • … and indexed if jupyter_server is installed

  • serve the site locally and print out a URL

The Lite Dir#

When you run jupyter lite commands, it assumes your current working directory is the partial contents of a JupyterLite site. You can override this with --lite-dir. By default, the built site will be created in _output, but can be overridden with --output-dir.

Hide code cell content 
if "TMP_DIR" not in globals():
    TMP_DIR = pathlib.Path(tempfile.mkdtemp(prefix="_my_lite_dir_"))

    def clean():
        shutil.rmtree(TMP_DIR)

    atexit.register(clean)
os.chdir(TMP_DIR)
print(pathlib.Path.cwd())

/tmp/_my_lite_dir_rxh0u12h

Well-known Files#

Some files in your --lite-dir that have special meaning:

look in path…

… for file named

… and if found

.
./lab
./notebook

jupyter-lite.{json,ipynb}

merge with static in _output/{path}/jupyter-lite.{json,ipynb}

.
./lab
./notebook

overrides.json

merge with static in _output/{*}/jupyter-lite.json

./files/

*

copy verbatim to _output/files/* and index in /api/contents

./pypi/

*.whl

copy verbatim to _output/pypi/* and index

./static/pyodide

pyodide.js, *.data, *.js

copy verbatim to _output/pyodide/*

See more about merging contents.

Usage#

Common Parameters#

All of the below are configured in jupyter_lite_config.json#LiteBuildConfig.

parameter

description

default

environment variable

--lite-dir

configuration and content for the site

current working directory

JUPYTERLITE_DIR

--output-dir

where the hostable site will be created

_output

JUPYTERLITE_OUTPUT_DIR

--cache-dir

a cache directory for downloads

<lite_dir>/.cache

JUPYTERLITE_CACHE_DIR

--disable-addons

disable a specific addon by entrypoint name

--app-archive

an alternate site to base off of

bundled

--contents

directory to copy to _output/files/ and available as Contents

./files

--ignore-contents

patterns that should never be included in /files/ (even if found in lite-dir)

various

--extra-ignore-contents

additional patterns that should never be included in /files/ (even if found in lite-dir)

--output-archive

the path to the archive

<directory>-jupyterlite.tgz

JUPYTERLAB_OUTPUT_ARCHIVE

--port

port on 127.0.0.1 to serve the test server

8000

JUPYTERLITE_PORT

--base-url

the URL prefix to include before the site

/

JUPYTERLITE_BASE_URL

--source-date-epoch

optionally enable additional reproducible build measures (best-effort!)

SOURCE_DATE_EPOCH

--federated-extensions

paths to folders, pip/conda packages with extensions see note

--ignore-sys-prefix

don’t copy any contents, such as install labextensions, from sys.prefix

False

--settings-overrides

additional settings overrides to enable

--mathjax-dir

the path to a MathJax 2 distribution

Addon configuration#

Some build-time addons provide their own CLI flags and configurable values. These may also configure runtime options in jupyter-lite.json.

PyodideAddon#

parameter

description

default

environment variable

--pyodide

the path or URL of a pyodide distribution (or .bz2 archive)

JUPYTERLITE_PYODIDE_URL
PipliteAddon#

parameter

description

default

environment variable

--piplite-wheels

additional wheels to make available to the pyodide kernel at runtime

All parameters may be configured via a jupyter_lite_config.json in the directory where jupyter lite is launched, or given via --config.

Hint

For an advanced example, see the configuration used for this documentation.

Help#

The CLI provides its own documentation, under --help (or -h).

!jupyter lite --help
Hide code cell output 
A Jupyter Application

Subcommands
===========
Subcommands are launched as `jupyter cmd [args]`. For information on using
subcommand 'cmd', do: `jupyter cmd -h`.

list
    describe a JupyterLite site
status
    report about what a JupyterLite build _might_ do
init
    initialize a JupyterLite site from an app archive baseline
build
    build a JupyterLite site, including user content
check
    verify a JupyterLite site, using available schema and rules
serve
    serve a JupyterLite site, using best available HTTP server
archive
    build a JupyterLite app archive, which can be used as a baseline
doit
    use the full doit CLI, see https://pydoit.org/contents.html

Options
=======
The options below are convenience aliases to configurable class-options,
as listed in the "Equivalent to" description-line of the aliases.
To see all configurable class-options for some <cmd>, use:
    <cmd> --help-all

--debug
    set log level to logging.DEBUG (maximize logging output)
    Equivalent to: [--Application.log_level=10]
-y
    Answer yes to any questions instead of prompting.
    Equivalent to: [--JupyterApp.answer_yes=True]
--ignore-sys-prefix
    Do not copy anything from sys.prefix
    Equivalent to: [--LiteBuildConfig.ignore_sys_prefix=True]
--no-sourcemaps
    Strip all sourcemaps from applications and extensions
    Equivalent to: [--LiteBuildConfig.no_sourcemaps=True]
--no-unused-shared-packages
    Remove shared packages not used by --apps
    Equivalent to: [--LiteBuildConfig.no_unused_shared_packages=True]
--no-libarchive
    Do not try to use libarchive-c for archive operations
    Equivalent to: [--LiteBuildConfig.no_libarchive=True]
--log-level=<Enum>
    Set the log level by value or name.
    Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
    Default: 30
    Equivalent to: [--Application.log_level]
--config=<Unicode>
    Full path of a config file.
    Default: ''
    Equivalent to: [--JupyterApp.config_file]
--disable-addons=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.disable_addons]
--app-archive=<CPath>
    The app archive to use. env: JUPYTERLITE_APP_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.app_archive]
--apps=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.apps]
--lite-dir=<CPath>
    The root folder of a JupyterLite project. env: JUPYTERLITE_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.lite_dir]
--contents=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.contents]
--ignore-contents=<tuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.ignore_contents]
--extra-ignore-contents=<tuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.extra_ignore_contents]
--settings-overrides=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.settings_overrides]
--mathjax-dir=<CPath>
    A local path to a complete/sufficient installation of MathJax 2
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.mathjax_dir]
--output-dir=<CPath>
    Where to build the JupyterLite site. env: JUPYTERLITE_OUTPUT_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_dir]
--output-archive=<CPath>
    Archive to create. env: JUPYTERLITE_OUTPUT_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_archive]
--source-date-epoch=<CInt>
    Trigger reproducible builds, clamping timestamps to this value
    Default: 0
    Equivalent to: [--LiteBuildConfig.source_date_epoch]
--port=<CInt>
    [serve] the port to (insecurely) expose on http://127.0.0.1. env:
    JUPYTERLITE_PORT
    Default: 0
    Equivalent to: [--LiteBuildConfig.port]
--base-url=<Unicode>
    [serve] the prefix to use. env: JUPYTERLITE_BASE_URL
    Default: ''
    Equivalent to: [--LiteBuildConfig.base_url]

To see all available configurables, use `--help-all`.

Status#

Always safe to run, this command provides an overview of what JupyterLite has been doing.

!jupyter lite status
Hide code cell output 
static:jupyter-lite.json
.  pre_status:static:jupyter-lite.json
    tarball:         jupyterlite-app-0.2.0-alpha.1.tgz 9MB
    output:          /tmp/_my_lite_dir_rxh0u12h/_output
    lite dir:        /tmp/_my_lite_dir_rxh0u12h
    apps:            
    sourcemaps:      True
    unused packages: True
archive:archive
contents:contents
lite:jupyter-lite.json
mathjax:status
mimetypes:jupyter-lite.json
serve:contents
settings:overrides
translation:translation
.  status:archive:archive
[LiteStatusApp] No archive (yet): _my_lite_dir_rxh0u12h-jupyterlite.tgz
.  status:contents:contents
    contents: 0 files
.  status:lite:jupyter-lite.json
[LiteStatusApp]     jupyter-lite.(json|ipynb): 0 files
.  status:mathjax:status
     jupyter-server-mathjax: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static 
     configured MathJax dir: /tmp/_my_lite_dir_rxh0u12h/traitlets.Undefined
     effective MathJax dir: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static
.  status:mimetypes:jupyter-lite.json
    filetypes:         26 
.  status:serve:contents
    url: http://127.0.0.1:8000/
    server: tornado
    headers:
.  status:settings:overrides
    overrides.json: 0
.  status:translation:translation
    translation files: 0 files

List#

Always safe to run, this command provides an overview of what JupyterLite might do.

TODO: improve on default output

!jupyter lite list
Hide code cell output 
static:jupyter-lite.json
archive:archive
contents:contents
lite:jupyter-lite.json
mathjax:status
mimetypes:jupyter-lite.json
serve:contents
settings:overrides
translation:translation
static:output_dir
static:unpack

federated_extensions:copy:ext:jupyterlab_pygments
federated_extensions:copy:ext:@jupyter-notebook/lab-extension
mathjax:copy

translation:copy
federated_extensions:patch
mathjax:patch
mimetypes:patch
mathjax:config
serve:tornado
report:SHA256SUMS
archive:archive:_my_lite_dir_rxh0u12h-jupyterlite.tgz
R archive                                                                   
R archive:archive:archive:_my_lite_dir_rxh0u12h-jupyterlite.tgz             generate a new app archive
R build                                                                     
R build:mathjax:copy                                                        copy MathJax into the output dir
R build:translation:copy                                                    create the translation data
R check                                                                     
E check:mathjax:config                                                      
R init                                                                      
R init:static:unpack                                                        unpack a 'gold master' JupyterLite from jupyterlite-app-0.2.0-alpha.1.tgz
R post_archive                                                              
R post_build                                                                
E post_build:federated_extensions:patch                                     ensure jupyter-lite.json includes the federated_extensions
E post_build:mathjax:patch                                                  ensure jupyter-lite.json includes the mathjax url
R post_build:mimetypes:patch                                                ensure /tmp/_my_lite_dir_rxh0u12h/_output/jupyter-lite.json includes the file_types
R post_check                                                                
R post_init                                                                 
R post_serve                                                                
R post_status                                                               
R pre_archive                                                               
R pre_archive:report:SHA256SUMS                                             hash all of the files
R pre_build                                                                 
R pre_build:federated_extensions:copy:ext:@jupyter-notebook/lab-extension   
R pre_build:federated_extensions:copy:ext:jupyterlab_pygments               
R pre_check                                                                 
R pre_init                                                                  
R pre_init:static:output_dir                                                clean out the lite directory
R pre_serve                                                                 
R pre_status                                                                
R pre_status:static:jupyter-lite.json                                       
R serve                                                                     
R serve:serve:tornado                                                       run server at http://127.0.0.1:8000/ for /tmp/_my_lite_dir_rxh0u12h/_output
R status                                                                    
R status:archive:archive                                                    
R status:contents:contents                                                  
R status:lite:jupyter-lite.json                                             
R status:mathjax:status                                                     Get information about offline MathJax
R status:mimetypes:jupyter-lite.json                                        
R status:serve:contents                                                     
R status:settings:overrides                                                 
R status:translation:translation

Init#

Copy all the static data to the --output-dir.

!jupyter lite init
Hide code cell output 
static:jupyter-lite.json
.  pre_status:static:jupyter-lite.json
    tarball:         jupyterlite-app-0.2.0-alpha.1.tgz 9MB
    output:          /tmp/_my_lite_dir_rxh0u12h/_output
    lite dir:        /tmp/_my_lite_dir_rxh0u12h
    apps:            
    sourcemaps:      True
    unused packages: True
archive:archive
contents:contents
lite:jupyter-lite.json
mathjax:status
mimetypes:jupyter-lite.json
serve:contents
settings:overrides
translation:translation
.  status:archive:archive
[LiteInitApp] No archive (yet): _my_lite_dir_rxh0u12h-jupyterlite.tgz
.  status:contents:contents
    contents: 0 files
.  status:lite:jupyter-lite.json
[LiteInitApp]     jupyter-lite.(json|ipynb): 0 files
.  status:mathjax:status
     jupyter-server-mathjax: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static 
     configured MathJax dir: /tmp/_my_lite_dir_rxh0u12h/traitlets.Undefined
     effective MathJax dir: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static
.  status:mimetypes:jupyter-lite.json
    filetypes:         26 
.  status:serve:contents
    url: http://127.0.0.1:8000/
    server: tornado
    headers:
.  status:settings:overrides
    overrides.json: 0
.  status:translation:translation
    translation files: 0 files
static:output_dir
.  pre_init:static:output_dir

static:unpack
.  init:static:unpack

Build#

Copy all the user-authored content to the --output-dir, and applies appropriate changes to e.g. generated Contents API responses.

Special well-known files will be merged appropriately, but generally, files that exist in the user directory will overwrite any existing content.

!jupyter lite build
Hide code cell output 
static:jupyter-lite.json
.  pre_status:static:jupyter-lite.json
    tarball:         jupyterlite-app-0.2.0-alpha.1.tgz 9MB
    output:          /tmp/_my_lite_dir_rxh0u12h/_output
    lite dir:        /tmp/_my_lite_dir_rxh0u12h
    apps:            
    sourcemaps:      True
    unused packages: True
archive:archive
contents:contents
lite:jupyter-lite.json
mathjax:status
mimetypes:jupyter-lite.json
serve:contents
settings:overrides
translation:translation
.  status:archive:archive
[LiteBuildApp] No archive (yet): _my_lite_dir_rxh0u12h-jupyterlite.tgz
.  status:contents:contents
    contents: 0 files
.  status:lite:jupyter-lite.json
[LiteBuildApp]     jupyter-lite.(json|ipynb): 0 files
.  status:mathjax:status
     jupyter-server-mathjax: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static 
     configured MathJax dir: /tmp/_my_lite_dir_rxh0u12h/traitlets.Undefined
     effective MathJax dir: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static
.  status:mimetypes:jupyter-lite.json
    filetypes:         26 
.  status:serve:contents
    url: http://127.0.0.1:8000/
    server: tornado
    headers:
.  status:settings:overrides
    overrides.json: 0
.  status:translation:translation
    translation files: 0 files
static:output_dir
-- pre_init:static:output_dir

static:unpack
-- init:static:unpack

federated_extensions:copy:ext:jupyterlab_pygments
federated_extensions:copy:ext:@jupyter-notebook/lab-extension
.  pre_build:federated_extensions:copy:ext:jupyterlab_pygments
.  pre_build:federated_extensions:copy:ext:@jupyter-notebook/lab-extension
mathjax:copy

translation:copy
.  build:mathjax:copy

.  build:translation:copy
federated_extensions:patch
mathjax:patch
mimetypes:patch
.  post_build:federated_extensions:patch
.  post_build:mathjax:patch
.  post_build:mimetypes:patch

Serve#

Serve the --output-dir on http://127.0.0.1:{--port=8000}{--base-url=/}.

Warning

This is not a production server. Please consider any of the deployment options before trying to make this something it isn’t.

!jupyter lite serve --help
Hide code cell output 
A Jupyter Application

Options
=======
The options below are convenience aliases to configurable class-options,
as listed in the "Equivalent to" description-line of the aliases.
To see all configurable class-options for some <cmd>, use:
    <cmd> --help-all

--debug
    set log level to logging.DEBUG (maximize logging output)
    Equivalent to: [--Application.log_level=10]
-y
    Answer yes to any questions instead of prompting.
    Equivalent to: [--JupyterApp.answer_yes=True]
--ignore-sys-prefix
    Do not copy anything from sys.prefix
    Equivalent to: [--LiteBuildConfig.ignore_sys_prefix=True]
--no-sourcemaps
    Strip all sourcemaps from applications and extensions
    Equivalent to: [--LiteBuildConfig.no_sourcemaps=True]
--no-unused-shared-packages
    Remove shared packages not used by --apps
    Equivalent to: [--LiteBuildConfig.no_unused_shared_packages=True]
--no-libarchive
    Do not try to use libarchive-c for archive operations
    Equivalent to: [--LiteBuildConfig.no_libarchive=True]
--force
    forget previous runs of task and re-run from the beginning
    Equivalent to: [--LiteTaskApp.force=True]
--log-level=<Enum>
    Set the log level by value or name.
    Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
    Default: 30
    Equivalent to: [--Application.log_level]
--config=<Unicode>
    Full path of a config file.
    Default: ''
    Equivalent to: [--JupyterApp.config_file]
--disable-addons=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.disable_addons]
--app-archive=<CPath>
    The app archive to use. env: JUPYTERLITE_APP_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.app_archive]
--apps=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.apps]
--lite-dir=<CPath>
    The root folder of a JupyterLite project. env: JUPYTERLITE_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.lite_dir]
--contents=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.contents]
--ignore-contents=<tuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.ignore_contents]
--extra-ignore-contents=<tuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.extra_ignore_contents]
--settings-overrides=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.settings_overrides]
--mathjax-dir=<CPath>
    A local path to a complete/sufficient installation of MathJax 2
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.mathjax_dir]
--output-dir=<CPath>
    Where to build the JupyterLite site. env: JUPYTERLITE_OUTPUT_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_dir]
--output-archive=<CPath>
    Archive to create. env: JUPYTERLITE_OUTPUT_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_archive]
--source-date-epoch=<CInt>
    Trigger reproducible builds, clamping timestamps to this value
    Default: 0
    Equivalent to: [--LiteBuildConfig.source_date_epoch]
--port=<CInt>
    [serve] the port to (insecurely) expose on http://127.0.0.1. env:
    JUPYTERLITE_PORT
    Default: 0
    Equivalent to: [--LiteBuildConfig.port]
--base-url=<Unicode>
    [serve] the prefix to use. env: JUPYTERLITE_BASE_URL
    Default: ''
    Equivalent to: [--LiteBuildConfig.base_url]

To see all available configurables, use `--help-all`.

HTTP headers#

When working locally, it can be convenient to emulate HTTP headers that would match how a site would work when deployed. As these get rather complicated, the following options are configurable, but only affect jupyter lite serve, such as emulating a “permissive” host with extra_http_headers (which extend the default headers) or http_headers (replacing any default headers):

{
  "LiteBuildConfig": {
    "http_headers": {
      "Access-Control-Allow-Headers": "x-requested-with",
      "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
      "Access-Control-Allow-Origin": "*"
    }
  }
}

Check#

Use all available mechanisms to verify that the build folder conforms to schema, etc.

!jupyter lite check
Hide code cell output 
static:jupyter-lite.json
.  pre_status:static:jupyter-lite.json
    tarball:         jupyterlite-app-0.2.0-alpha.1.tgz 9MB
    output:          /tmp/_my_lite_dir_rxh0u12h/_output
    lite dir:        /tmp/_my_lite_dir_rxh0u12h
    apps:            
    sourcemaps:      True
    unused packages: True
archive:archive
contents:contents
lite:jupyter-lite.json
mathjax:status
mimetypes:jupyter-lite.json
serve:contents
settings:overrides
translation:translation
.  status:archive:archive
[LiteCheckApp] No archive (yet): _my_lite_dir_rxh0u12h-jupyterlite.tgz
.  status:contents:contents
    contents: 0 files
.  status:lite:jupyter-lite.json

[LiteCheckApp]     jupyter-lite.(json|ipynb): 0 files
.  status:mathjax:status
     jupyter-server-mathjax: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static 
     configured MathJax dir: /tmp/_my_lite_dir_rxh0u12h/traitlets.Undefined
     effective MathJax dir: /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/conda/latest/lib/python3.10/site-packages/jupyter_server_mathjax/static
.  status:mimetypes:jupyter-lite.json
    filetypes:         26 
.  status:serve:contents
    url: http://127.0.0.1:8000/
    server: tornado
    headers:
.  status:settings:overrides
    overrides.json: 0
.  status:translation:translation
    translation files: 4 files
static:output_dir
-- pre_init:static:output_dir
static:unpack
-- init:static:unpack

federated_extensions:copy:ext:jupyterlab_pygments
federated_extensions:copy:ext:@jupyter-notebook/lab-extension
-- pre_build:federated_extensions:copy:ext:jupyterlab_pygments
-- pre_build:federated_extensions:copy:ext:@jupyter-notebook/lab-extension

mathjax:copy

translation:copy
-- build:mathjax:copy
-- build:translation:copy
federated_extensions:patch
mathjax:patch
mimetypes:patch
.  post_build:federated_extensions:patch
.  post_build:mathjax:patch
-- post_build:mimetypes:patch
lite:validate:jupyter-lite.json
lite:validate:repl/jupyter-lite.json
lite:validate:notebooks/jupyter-lite.json
lite:validate:edit/jupyter-lite.json
lite:validate:lab/jupyter-lite.json
lite:validate:tree/jupyter-lite.json
lite:validate:consoles/jupyter-lite.json
lite:validate:jupyter-lite.ipynb
lite:validate:repl/jupyter-lite.ipynb
lite:validate:notebooks/jupyter-lite.ipynb
lite:validate:edit/jupyter-lite.ipynb
lite:validate:lab/jupyter-lite.ipynb
lite:validate:tree/jupyter-lite.ipynb
lite:validate:consoles/jupyter-lite.ipynb
mathjax:config
translation:validate:translation:all.json
.  check:lite:validate:jupyter-lite.json

.  check:lite:validate:repl/jupyter-lite.json
.  check:lite:validate:notebooks/jupyter-lite.json
.  check:lite:validate:edit/jupyter-lite.json
.  check:lite:validate:lab/jupyter-lite.json
.  check:lite:validate:tree/jupyter-lite.json
.  check:lite:validate:consoles/jupyter-lite.json
.  check:lite:validate:jupyter-lite.ipynb
.  check:lite:validate:repl/jupyter-lite.ipynb
.  check:lite:validate:notebooks/jupyter-lite.ipynb
.  check:lite:validate:edit/jupyter-lite.ipynb
.  check:lite:validate:lab/jupyter-lite.ipynb
.  check:lite:validate:tree/jupyter-lite.ipynb
.  check:lite:validate:consoles/jupyter-lite.ipynb
.  check:mathjax:config
.  check:translation:validate:translation:all.json

Archive#

Turn the output directory into a .tgz file. This is usually easier to move around than (sometimes) hundreds of files, and can be used as the baseline for future sites.

This command is relatively expensive, and is skipped for documentation purposes

!jupyter lite archive --help
if not RTD:
    !jupyter lite archive
Hide code cell output 
A Jupyter Application

Options
=======
The options below are convenience aliases to configurable class-options,
as listed in the "Equivalent to" description-line of the aliases.
To see all configurable class-options for some <cmd>, use:
    <cmd> --help-all

--debug
    set log level to logging.DEBUG (maximize logging output)
    Equivalent to: [--Application.log_level=10]
-y
    Answer yes to any questions instead of prompting.
    Equivalent to: [--JupyterApp.answer_yes=True]
--ignore-sys-prefix
    Do not copy anything from sys.prefix
    Equivalent to: [--LiteBuildConfig.ignore_sys_prefix=True]
--no-sourcemaps
    Strip all sourcemaps from applications and extensions
    Equivalent to: [--LiteBuildConfig.no_sourcemaps=True]
--no-unused-shared-packages
    Remove shared packages not used by --apps
    Equivalent to: [--LiteBuildConfig.no_unused_shared_packages=True]
--no-libarchive
    Do not try to use libarchive-c for archive operations
    Equivalent to: [--LiteBuildConfig.no_libarchive=True]
--force
    forget previous runs of task and re-run from the beginning
    Equivalent to: [--LiteTaskApp.force=True]
--log-level=<Enum>
    Set the log level by value or name.
    Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
    Default: 30
    Equivalent to: [--Application.log_level]
--config=<Unicode>
    Full path of a config file.
    Default: ''
    Equivalent to: [--JupyterApp.config_file]
--disable-addons=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.disable_addons]
--app-archive=<CPath>
    The app archive to use. env: JUPYTERLITE_APP_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.app_archive]
--apps=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.apps]
--lite-dir=<CPath>
    The root folder of a JupyterLite project. env: JUPYTERLITE_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.lite_dir]
--contents=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.contents]
--ignore-contents=<tuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.ignore_contents]
--extra-ignore-contents=<tuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.extra_ignore_contents]
--settings-overrides=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.settings_overrides]
--mathjax-dir=<CPath>
    A local path to a complete/sufficient installation of MathJax 2
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.mathjax_dir]
--output-dir=<CPath>
    Where to build the JupyterLite site. env: JUPYTERLITE_OUTPUT_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_dir]
--output-archive=<CPath>
    Archive to create. env: JUPYTERLITE_OUTPUT_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_archive]
--source-date-epoch=<CInt>
    Trigger reproducible builds, clamping timestamps to this value
    Default: 0
    Equivalent to: [--LiteBuildConfig.source_date_epoch]
--port=<CInt>
    [serve] the port to (insecurely) expose on http://127.0.0.1. env:
    JUPYTERLITE_PORT
    Default: 0
    Equivalent to: [--LiteBuildConfig.port]
--base-url=<Unicode>
    [serve] the prefix to use. env: JUPYTERLITE_BASE_URL
    Default: ''
    Equivalent to: [--LiteBuildConfig.base_url]

To see all available configurables, use `--help-all`.

But let’s talk about a more reproducible asset.

Hide code cell content 
# we clean out the TMP_DIR for the reproducibility examples
shutil.rmtree(TMP_DIR / "_output", ignore_errors=True)

Reproducible Archives#

🛠️ This feature is a work-in-progress, and should not be relied upon by any production workflows Just Yet.

If --source-date-epoch is given, a number of measures will be taken to try to ensure that the output of jupyter lite archive, an npm-compatible tgz package, always returns a bit-for-bit reproducible build.

The most obvious change is that the modified time of each file “clamped” to that time. Some other changes:

  • file ownership will be reset

  • predictable sorting will be used

  • additional checks will be applied

Note

This is a shortcut for setting the environment variable SOURCE_DATE_EPOCH:

platform

command

Linux
MacOS

export SOURCE_DATE_EPOCH=<a timestamp>

Windows

set SOURCE_DATE_EPOCH=<a timestamp>

Python

os.environ.update(SOURCE_DATE_EPOCH, <a timestamp>)
Hide code cell source 
if not "source_date_epoch" in globals():
    from datetime import datetime

    source_date_epoch = int(datetime.utcnow().timestamp())

print("SOURCE_DATE_EPOCH is", source_date_epoch)

SOURCE_DATE_EPOCH is 1695646093

if not RTD:
    !jupyter lite archive --source-date-epoch {source_date_epoch} --output-archive ./a.tgz

If we clear out our _output…

Hide code cell source 
if not RTD:
    shutil.rmtree(TMP_DIR / "_output", ignore_errors=True)
    pprint.pprint([*TMP_DIR.rglob("*")])

…and rebuild, we should always get the same file.

if not RTD:
    !jupyter lite archive --source-date-epoch {source_date_epoch} --output-archive ./b.tgz
Hide code cell source 
if not RTD:
    a, b = [
        hashlib.sha256((TMP_DIR / f"{x}.tgz").read_bytes()).hexdigest() for x in "ab"
    ]
    print("We built app archives with the SHA256SUMS of:\n", a, "\n", b)
    try:
        assert a == b, "We did not reproducibly build today.\n- {}\n- {}\n\n".format(
            a, b
        )
    except AssertionError as err:
        if shutil.which("diffoscope"):
            print(
                "We did NOT reproducibly build today, checking in with `diffoscope`..."
            )
            !diffoscope a.tgz b.tgz
        print("...but at least we tried REALLY hard!\n")

Miscellaneous#

Merging Contents#

In addition to the default files/ path, provide additional files to show in the File Manager or Tree when JupyterLite launches with --contents, which can be provided multiple times.

Note

  • If --contents is provided, the default value of --contents files will be ignored

  • If given multiple times, and child folder/file names would collide, the last path wins

Hint

For complex file layouts, a jupyter_lite_config.json is highly recommended.

Contents Example#

Given a directory like:

my-lite-dir/
  files/
    README.md
    a.md
  more-files/
    README.md
    b.md

Running jupyter lite build without any arguments will yield:

my-lite-dir/
  _output/
    README.md
    a.md

Whereas jupyter lite build --contents more-files --contents files will yield:

my-lite-dir/
  _output/
    files/
      README.md # this will be from my-lite-dir/files
      a.md
      b.md

And jupyter lite build --contents files --contents more-files will yield:

my-lite-dir/
  _output/
    files/
      README.md # this will be from my-lite-dir/more-files
      a.md
      b.md

conda packages#

While --federated-extensions support the .tar.bz2 created by most conda packages, there are some issues:

  • anaconda.org uses non-standard HTTP headers to S3 buckets to provide packages

  • the conda-forge channel provides all of its builds as GitHub releases, and can be predictably transformed, e.g.

https://anaconda.org/conda-forge/jupyterlab_widgets/1.0.0/download/noarch/jupyterlab_widgets-1.0.0-pyhd8ed1ab_1.tar.bz2
                                                                   |      |
                                                                   |      +---------------------------------------------+
                                                                   v      v                                             v
         https://conda.anaconda.org/conda-forge/noarch/jupyterlab_widgets-1.0.0-pyhd8ed1ab_1.tar.bz2

Pyodide wheels#

Prebuilt Lab Extension developers who wish to include wheels for use with the Pyodide kernel may use this command to pre-index wheels they wish to distribute. This can be useful if a package needs upstream patches, etc.

!jupyter lite pip index --help
Hide code cell output 
A Jupyter Application

Subcommands
===========
Subcommands are launched as `jupyter cmd [args]`. For information on using
subcommand 'cmd', do: `jupyter cmd -h`.

list
    describe a JupyterLite site
status
    report about what a JupyterLite build _might_ do
init
    initialize a JupyterLite site from an app archive baseline
build
    build a JupyterLite site, including user content
check
    verify a JupyterLite site, using available schema and rules
serve
    serve a JupyterLite site, using best available HTTP server
archive
    build a JupyterLite app archive, which can be used as a baseline
doit
    use the full doit CLI, see https://pydoit.org/contents.html

Options
=======
The options below are convenience aliases to configurable class-options,
as listed in the "Equivalent to" description-line of the aliases.
To see all configurable class-options for some <cmd>, use:
    <cmd> --help-all

--debug
    set log level to logging.DEBUG (maximize logging output)
    Equivalent to: [--Application.log_level=10]
-y
    Answer yes to any questions instead of prompting.
    Equivalent to: [--JupyterApp.answer_yes=True]
--ignore-sys-prefix
    Do not copy anything from sys.prefix
    Equivalent to: [--LiteBuildConfig.ignore_sys_prefix=True]
--no-sourcemaps
    Strip all sourcemaps from applications and extensions
    Equivalent to: [--LiteBuildConfig.no_sourcemaps=True]
--no-unused-shared-packages
    Remove shared packages not used by --apps
    Equivalent to: [--LiteBuildConfig.no_unused_shared_packages=True]
--no-libarchive
    Do not try to use libarchive-c for archive operations
    Equivalent to: [--LiteBuildConfig.no_libarchive=True]
--log-level=<Enum>
    Set the log level by value or name.
    Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
    Default: 30
    Equivalent to: [--Application.log_level]
--config=<Unicode>
    Full path of a config file.
    Default: ''
    Equivalent to: [--JupyterApp.config_file]
--disable-addons=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.disable_addons]
--app-archive=<CPath>
    The app archive to use. env: JUPYTERLITE_APP_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.app_archive]
--apps=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.apps]
--lite-dir=<CPath>
    The root folder of a JupyterLite project. env: JUPYTERLITE_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.lite_dir]
--contents=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.contents]
--ignore-contents=<tuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.ignore_contents]
--extra-ignore-contents=<tuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.extra_ignore_contents]
--settings-overrides=<typedtuple-item-1>...
    Default: ()
    Equivalent to: [--LiteBuildConfig.settings_overrides]
--mathjax-dir=<CPath>
    A local path to a complete/sufficient installation of MathJax 2
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.mathjax_dir]
--output-dir=<CPath>
    Where to build the JupyterLite site. env: JUPYTERLITE_OUTPUT_DIR
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_dir]
--output-archive=<CPath>
    Archive to create. env: JUPYTERLITE_OUTPUT_ARCHIVE
    Default: traitlets.Undefined
    Equivalent to: [--LiteBuildConfig.output_archive]
--source-date-epoch=<CInt>
    Trigger reproducible builds, clamping timestamps to this value
    Default: 0
    Equivalent to: [--LiteBuildConfig.source_date_epoch]
--port=<CInt>
    [serve] the port to (insecurely) expose on http://127.0.0.1. env:
    JUPYTERLITE_PORT
    Default: 0
    Equivalent to: [--LiteBuildConfig.port]
--base-url=<Unicode>
    [serve] the prefix to use. env: JUPYTERLITE_BASE_URL
    Default: ''
    Equivalent to: [--LiteBuildConfig.base_url]

To see all available configurables, use `--help-all`.

Pyodide#

Pyodide is a WebAssembly distribution of CPython and powers the Pyodide kernel kernel. At nearly 200mb, compressed, a full pyodide distribution includes both the Python interpreter and key anchor packages from the scientific computing stack. Parts of it are fetched as needed by the user’s browser, by default, from the official pyodide CDN.

The --pyodide CLI option (or alternately pyodide_url config option or JUPYTERLITE_PYODIDE_URL environment variable) allows for fetching either a compressed pyodide .bz2, or folder containing such an archive’s contents. This might be from the official pyodide release page, a nightly or PR asset, or otherwise customized build. Once fetched, it is copied to the output folder, and configured.

$\LaTeX$#

If jupyter-server-mathjax is installed, the MathJax 2 assets it provides will be copied and configured during the build. This behavior can be:

  • disabled with --ignore-sys-prefix or --disable-addons mathjax, defaulting to fetching the assets from CDN.

  • overridden with --mathjax-dir <path>, which must be a full folder of a MathJax 2 distribution