Deploy your first JupyterLite website on GitHub Pages#
If you first want to get familiar with the interface, check out the User Guide.
JupyterLite can easily be deployed on GitHub Pages, using the
jupyter-lite CLI to
add content and extensions.
Deploying to GitHub Pages requires a Github account.
Generate a new repository from the template#
The jupyterlite demo repository is a template to easily:
build a JupyterLite website using prebuilt JupyterLite assets bundling a collection of pre-existing Jupyter Notebooks as part of the distribution
deploy the website to GitHub Pages
The process is automated using Github Actions.
Click on “Use this template” to generate a repository of your own from this template:
From the Actions tab on your repository, ensure that workflows are enabled. When you
make a commit to the
main branch, a Github Action will build your JupyterLite release
and deploy it to the repository’s Github Pages. By default, the Github Pages site will
be found at
YOUR_GITHUB_USERNAME.github.io/YOUR_REPOSITORY-NAME. You can also check
the URL from the Repository
Pages menu item.
If the deployment failed, go to “Settings - Actions - General”, in the “Workflow
permissions” section, check “Read and write permissions”. Check that you have Github
Pages enabled for your repository: from your repository Settings tab, select the
Pages menu item and ensure that the source is set to
When you commit a file, an updated website will be built and published on Github Pages.
Note that it may take a few minutes for the Github Pages site to be updated. Do a hard refresh on your Github Pages site in your web browser to see the new version of the website.
Alternatively, you can use the JupyterLite demo using xeus-python to publish a deployment on Github pages that uses xeus-python by default and allows to pre-install packages using
Accessing the JupyterLite website#
After the build has completed, the site will be available on GitHub Pages. Go to
https://YOUR_GITHUB_USERNAME.github.io/YOUR_REPOSITORY-NAME to access it:
By default the deployment provided by the
jupyterlite/demo repo includes a
to bypass Jekyll processing on GitHub Pages.
See this blog post for more information.
Deploy a new version of JupyterLite#
To change the version of the prebuilt JupyterLite assets, update the
package version in the
Commit and push the changes. The site will be deployed on the next push to the
Add additional requirements to the deployment#
The jupyterlite/demo repository uses a
requirements.txt file to specify the dependencies. For demo purposes this file may contain extra kernels and extensions you might want to remove from your deployment. If that’s the case you can stick to a more minimal
requirements.txt file such as:
# core package for building the JupyterLite website
# the Python kernel powered by Pyodide
# dependency for indexing the content
requirements.txt file can be used to add extra prebuilt (also called federated)
JupyterLab extensions to the deployed JupyterLite website. Follow the
extension guide to learn more.
Using the xeus-python kernel and emscripten-forge#
a JupyterLite deployment with xeus-python,
you can pre-install packages available both on
specifying them to the
By pre-installing packages, they are readily usable in the kernel and can be imported
without the need for
You can add and update the default notebooks and files by clicking on the
directory and dragging notebooks from your desktop onto the contents listing. Wait for
the files to be uploaded and then save them (commit them) to the
main branch of the
Check out the how-to guide on managing content to learn more.
If you would like to customize your JupyterLite website, check out the different how-to guides.