CLI#
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/envs/1881/lib/python3.12/site-packages (0.8.0a1)
Requirement already satisfied: doit<1,>=0.34 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/envs/1881/lib/python3.12/site-packages (from jupyterlite-core) (0.36.0)
Requirement already satisfied: jupyter-core>=4.7 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/envs/1881/lib/python3.12/site-packages (from jupyterlite-core) (5.9.1)
Requirement already satisfied: cloudpickle in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/envs/1881/lib/python3.12/site-packages (from doit<1,>=0.34->jupyterlite-core) (3.1.2)
Requirement already satisfied: importlib-metadata>=4.4 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/envs/1881/lib/python3.12/site-packages (from doit<1,>=0.34->jupyterlite-core) (8.7.1)
Requirement already satisfied: zipp>=3.20 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/envs/1881/lib/python3.12/site-packages (from importlib-metadata>=4.4->doit<1,>=0.34->jupyterlite-core) (3.23.0)
Requirement already satisfied: platformdirs>=2.5 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/envs/1881/lib/python3.12/site-packages (from jupyter-core>=4.7->jupyterlite-core) (4.5.1)
Requirement already satisfied: traitlets>=5.3 in /home/docs/checkouts/readthedocs.org/user_builds/jupyterlite/envs/1881/lib/python3.12/site-packages (from jupyter-core>=4.7->jupyterlite-core) (5.14.3)
0.8.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[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]
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:
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.
Well-known Files#
Some files in your --lite-dir that have special meaning:
look in path… |
… for file named |
… and if found |
|---|---|---|
|
|
merge with static in |
|
|
merge with static in |
|
|
copy verbatim to |
|
|
copy verbatim to |
|
|
copy verbatim to |
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 |
|---|---|---|---|
|
configuration and content for the site |
current working directory |
|
|
where the hostable site will be created |
|
|
|
a cache directory for downloads |
|
|
|
disable a specific addon by entrypoint name |
||
|
an alternate site to base off of |
bundled |
|
|
directory to copy to |
|
|
|
patterns that should never be included in |
various |
|
|
additional patterns that should never be included in |
||
|
the path to the archive |
|
|
|
port on |
|
|
|
the URL prefix to include before the site |
|
|
|
optionally enable additional reproducible build measures (best-effort!) |
|
|
|
paths to folders, |
||
|
don’t copy any contents, such as install labextensions, from |
|
|
|
additional settings overrides to enable |
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 |
|---|---|---|---|
|
the path or URL of a pyodide distribution (or .bz2 archive) |
|
PipliteAddon#
parameter |
description |
default |
environment variable |
|---|---|---|---|
|
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
Status#
Always safe to run, this command provides an overview of what JupyterLite has been doing.
!jupyter lite status
List#
Always safe to run, this command provides an overview of what JupyterLite might do.
TODO: improve on default output
!jupyter lite list
Init#
Copy all the static data to the --output-dir.
!jupyter lite init
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
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
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
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
But let’s talk about a more reproducible asset.
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 |
|
Windows |
|
Python |
|
SOURCE_DATE_EPOCH is 1772551448
/tmp/ipykernel_2048/711058523.py:4: DeprecationWarning: datetime.datetime.utcnow() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.now(datetime.UTC).
source_date_epoch = int(datetime.utcnow().timestamp())
if not RTD:
!jupyter lite archive --source-date-epoch {source_date_epoch} --output-archive ./a.tgz
If we clear out our _output…
…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
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
--contentsis provided, the default value of--contents fileswill be ignoredIf 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.orguses non-standard HTTP headers to S3 buckets to provide packagesthe
conda-forgechannel 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
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.