Command line¶
The package installs jupyter workshop, a command line tool for people
who write workshops. Its lint, render and pages commands run the
same TypeScript code the extension uses, bundled for Node.js and shipped
inside the package, so they need node (18 or newer) on the path. The
other commands are pure Python.
init¶
jupyter workshop init my-workshop [--name NAME] [--title TITLE] [--ci]
[--template starter|blank|notebook]
[--platform NAME]... [--frontend NAME]...
[--capability NAME]... [--gating off|soft|strict]
[--no-git]
Creates a directory with a workshop.yaml, starter pages, an empty
files/ for starter files (copied into the learner’s work/
workspace when the workshop opens), a
README and a .gitignore, and makes it a git repository on main, with
nothing committed yet, so the workshop’s history starts with it. A
directory inside a repository already, such as a course’s workshops/,
joins that repository instead, and --no-git leaves a new directory
as a plain one. The starter template’s pages show commands,
a check,
a file write and a quiz; blank is one page of prose; notebook
creates a notebook, runs its cells and checks a value in its kernel. The
name defaults to a slug of the directory name. --platform,
--frontend and --capability may be repeated and set the manifest
lists (the defaults are linux and macos, JupyterLab only, which
needs no frontends list, and the template’s capabilities); --gating
sets the page gating. With --ci it also writes a GitHub Actions
workflow that lints and self-tests the workshop on Linux, macOS and
Windows. Each job runs on a fresh runner, which is also the safest place
to self-test a workshop that changes anything outside its own directory;
see the warning under test.
lint¶
jupyter workshop lint my-workshop [--json] [--platform linux|macos|windows] [--frontend jupyterlab|jupyterlite]
jupyter workshop lint collection.json [--json]
jupyter workshop lint catalog.json [--json]
Given a workshop directory, parses the manifest and every page and
reports problems: unknown
directives and options, missing bodies, a directive closed early by the
fence of a block inside it, capabilities used but not
declared (or declared but unused), invalid checks, quizzes and forms,
requirements that name nothing, variables used before the form that sets
them, danger heuristics such as piping a download into a shell,
variants missing for a listed platform or frontend, and actions a
listed frontend cannot run. Exits
with 1 when there are errors. --json prints the report as JSON for
other tools. --platform renders the pages as that platform sees them,
selecting its command variants and built-in variables, so a Linux CI
job can check the Windows version of a workshop; --frontend jupyterlite does the same for JupyterLite, whose platform is always
emscripten, and switches on the JupyterLite rules.
Given a collection.json or catalog.json file, checks that it parses
as one, and for a catalog that every collection it names can be read
from where the catalog says it is, relative to the catalog file when not
a URL. Exits with 1 when something is wrong, which gives a repository of
workshops a CI check.
render¶
jupyter workshop render my-workshop [PAGE] [--out FILE] [--platform NAME] [--frontend NAME]
Renders the pages to a standalone HTML document for previewing or for
static hosting. Action blocks are shown as boxes with their type and
body, so a quiz, choice or form appears as its source rather than as
the panel renders it. Give a page id or path to render one page, and --platform or
--frontend to render another platform’s or frontend’s command
variants.
pages¶
jupyter workshop pages my-workshop
Lists page ids, titles, paths and requirements.
schema¶
jupyter workshop schema [--collection | --catalog | --events | --library]
Prints the JSON schema of workshop.yaml, for editors and validators,
or with --collection the schema of a collection index file, with
--catalog the schema of a catalog, with --events the schema of
the progress events a workshop reports, for a service
that receives them, or with --library the schema of a
workshop library’s library.json.
publish¶
jupyter workshop publish my-workshop [--out dist] [--url URL]
Builds dist/<name>-<version>.tar.gz (excluding _workshop, .git,
scratch and similar), writes its SHA-256 next to it, and writes a
collection entry JSON snippet, <name>-<version>.collection.json, with
the hash and, when given, the URL the archive will be published at. The
archive is built with fixed ownership and timestamps so the hash is the
same on every machine.
gist¶
jupyter workshop gist my-workshop [--out dist/gist] [--create [--public] | --update [GIST]]
[--token TOKEN] [--site URL | --python X.Y]
[--binder URL | --no-binder]
[--append-readme] [--frontend NAME]
Lays a workshop out as a GitHub gist holds
it and, with --create or --update, sends it there. A gist is a git
repository with no directories, so every file is stored under its path
with the directory separators turned into --, pages/01-welcome.md
as pages--01-welcome.md, and a workshop-tree.json maps each path
back to its gist file. Nothing in the workshop is rewritten: a download
of the gist puts every file back at its path. The files carried are the
ones publish would archive, less hidden files, editor
droppings and the workshop’s own README.md; the command prints each
file it stores under a different name, and reports what it left out. A
file that is not text is stored as base64 under a name ending
.base64, and an empty file is recorded in the tree alone, since the
gists API carries neither. The workshop is linted before, and after
writing the flat copy under dist/gist/<name>/ the command puts the
copy back together the way a download would and lints that, with
--frontend jupyterlite selecting the JupyterLite rules for a gist
meant for the demo site.
A README.md is generated as well, which GitHub pins to the top of
the gist page: the title, description, version, authors, duration,
tags, platforms and frontends from the manifest, then how to open the
workshop, starting by saying that the gist is a workshop to take rather
than pages to read. Each way to start it is a button with a plain link
beside it: one that opens the gist in a JupyterLite site, when the
manifest lists jupyterlite among its frontends, and one that opens it
in JupyterLab on mybinder.org, and it always gives the JupyterLab
routes: the “Open Workshop from URL…” command, a launch link and
jupyter workshop launch. The
workshop’s own README.md is left out unless --append-readme adds it
below the generated part. In the flat copy on disk the README names a
gist that does not exist yet; creating or updating the gist writes it
again with the real address.
The button opens one of the project’s published launcher
sites, each of which carries
one Python version. The version is chosen from the manifest: a python
or python3 entry under requires.tools with a version requirement
picks the newest launcher that meets it, and a manifest that says
nothing gets the newest; a requirement no launcher meets is an error.
--python X.Y names the launcher outright, and --site URL points the
button at a JupyterLite site of your own instead. The chosen launcher
is printed as launcher.
The README also carries a button that opens the gist in JupyterLab on
mybinder.org, through the project’s Binder
launcher,
a repository that installs JupyterLab with the extension and nothing
else, with the gist named by the launch link in mybinder’s urlpath.
It is left out when the manifest’s frontends leave out jupyterlab, or
its platforms leave out linux, which is what Binder runs. --binder URL points the button at a launcher repository of your own, given as
its https://mybinder.org/v2/... address, and --no-binder leaves the
button out.
--create makes a new gist, secret unless --public is given, and
--update replaces the files of an existing one, given by URL or id,
removing any the flat copy no longer has. Each update is one revision
in the gist’s history, where removed files stay readable. Either way the
gist is recorded in the workshop’s _workshop/gist.json (its address,
id, whether it is public, and when it was created and last updated), so
--update with no gist named updates the recorded one; with nothing
recorded it is an error. --create with a gist already recorded makes
a new one and records that instead. Both need a
GitHub token with
the gist scope, from --token, else GH_TOKEN or GITHUB_TOKEN,
else gh auth token for someone signed in to the gh command. See A
workshop in a gist.
github¶
jupyter workshop github [DIRECTORY] [--name OWNER/NAME] [--public] [--description TEXT]
Publishes a workshop’s or a course’s repository to GitHub, or pushes to
the one it already has, through the gh
command, which must be signed in (gh auth login) with the repo scope (gh auth refresh -s repo adds it to a
classic token). The directory, the current one by default, must be the
top of a git repository with everything committed: an uncommitted tree
or one with no commits is refused, so what is published is what was
committed, and a workshop inside a course is published with the course.
Without an origin remote the command creates a repository, called by
--name, as OWNER/NAME or as NAME under your account, or by the
directory’s name, private unless --public, with --description as
its description; adds it as origin; and pushes. With an origin it
pushes the current branch there, and --public makes a private
repository public. Either way it prints the repository’s address.
A course scaffolded by course init before it had a
repository names a placeholder address in its Justfile, README.md
and launch configuration; once the repository exists the command
rewrites those files, where they are still as generated, with the real
address and records it in course.json, and prints each file
refreshed. Commit them and run the command again to push them. A course
written with --lite publishes its JupyterLite site from its Pages
workflow once GitHub Pages is set to build from GitHub Actions in the
repository’s settings, which the command says; on a private repository
Pages needs a paid plan. See A repository on
GitHub.
gitignore¶
jupyter workshop gitignore [DIRECTORY] [--fix]
Compares a workshop’s or a course’s .gitignore with what one written
by init or course init ignores: for a workshop the
_workshop/ progress, work/, dist/, scratch/, JupyterLab’s
.ipynb_checkpoints/ and Claude Code’s .claude/; for a course
.workshop/, the same state under workshops/*/, .venv/, the skill
link and Claude Code’s local files, and the JupyterLite site when the
course has one. A repository brought into a library from
elsewhere, or made before an entry existed, may lack some. The command
lists each missing pattern with why it matters and exits with status 1;
--fix appends them to the file, comments and all, and exits with 0.
Each pattern is tried against git itself, so a pattern written another
way counts as present; without git, or outside a repository, the file’s
own lines are read instead and the command says so. course
link runs the check on the repository it links, and
Workshop Author runs it before a commit
and offers the fix.
collection¶
jupyter workshop collection collection.json ENTRY... [METADATA...]
Merges the entry files written by publish into a collection index,
creating it if needed. An entry for a name that is already listed is
updated in place, keeping its position and the earlier versions, newest
first; a new entry is appended. The metadata options set the
collection’s own fields and keep an existing index’s values when not
given: --title, --description, --publisher, --publisher-url,
--homepage, --icon (a URL, a path relative to the file, or a data:
URI) and --tag, which may be repeated; --ordered says the workshops
form a sequence to take in the order listed, and --unordered takes
that back. See Finding and installing workshops for
the index format and how the extension uses it.
index¶
jupyter workshop index [DIRECTORY...] [--root ROOT] [--out FILE] [--repo URL] [--ref REF] [METADATA...]
Builds a collection index of every workshop found under the directories
given (the current directory by default), so a repository holding
several workshops can list them all without publishing archives. Each
entry’s source is the workshop’s path relative to --root, the git
checkout holding the first directory unless given, fetched from --repo
at --ref, which default to the checkout’s origin and current branch; an
SSH remote is rewritten as the https URL. The index is written to
collection.json under the root, or --out, and an existing index is
updated: entries already listed keep their position and other versions,
new ones are appended in the order found, which for a directory that is
searched is path order. When every directory given is itself a workshop
directory, and between them they account for every workshop already
listed, the index is instead written in the order they are given, which
sets the order of a new index, moves a new workshop into the middle of
an existing one, or rearranges it. The metadata options are those
of collection. A collection.yaml in the root supplies what the
manifests cannot, the collection’s analytics block, which is checked
and copied into the index; an existing index’s block is kept when the
file is absent. Hidden directories, node_modules, build outputs and
_workshop state are not searched, nor are the contents of a workshop.
See Several workshops in one repository.
catalog¶
jupyter workshop catalog catalog.json [COLLECTION...] [--relative] [METADATA...]
Builds or refreshes a catalog from collection indexes. Each collection,
given as a URL or a file, is read and its entry written or refreshed
from the index’s own title, description, publisher, icon and tags,
keeping an existing entry’s position and appending new ones. With no
collections named, every entry already listed is re-read from where the
catalog says it is. --relative records a file by its path relative to
the catalog, for a repository that holds a catalog and its collections.
The metadata options set the catalog’s own fields: --title,
--description, --publisher, --publisher-url, --homepage and
--icon. See Catalogs.
install¶
jupyter workshop install COLLECTION [--root ROOT] [--directory DIR] [--only NAME...] [--platform PLATFORM] [--frontend FRONTEND]
Installs every workshop of a collection that is not installed yet, the
way the browser’s “Install all” does, for building an image or setting
up a classroom machine from a script. COLLECTION is the index’s URL
or a file. The workshops land under --directory (workshops) beneath
--root (the current directory), which should be the JupyterLab root
so the browser lists them as installed; each records the collection it
came from, by URL or by the file’s path relative to the root, so a
JupyterLab subscribed to the same collection matches them to their
entries and offers updates. Entries are taken in the collection’s
order, the newest listed version of each, with the same hash check and
the same directory naming as the browser, so a name another
collection’s workshop already occupies gets the collection’s hash
appended. Workshops already installed are skipped. --only names one
workshop to install and may be repeated; --platform skips entries
whose platforms do not include the one given, and --frontend those
not written for the frontend given, where an entry listing no frontends
is for JupyterLab only; by default every entry is installed, since the
person building an image knows its platform. One line is printed per workshop and a count at the end, and
the exit status is 1 when any download failed, so a build stops on a
missing archive. See Installing a whole collection.
In a workshop library, each workshop goes in its
collection’s own directory under installed/collections/, and the
library is subscribed to the collection.
library¶
jupyter workshop library [DIR] [--init-only] [--yes] [--collection URL...] [--trust LEVEL] [--port PORT] [--no-browser] [--fresh] [--token TOKEN] [-- ARGS...]
Starts JupyterLab with a workshop library as its root,
creating the library the first time. DIR defaults to the
JUPYTER_WORKSHOP_LIBRARY environment variable when it is set, and
otherwise to ~/Workshops. The library’s registry is library.json in
DIR, and workshopsDirectory is set to . for the session, so the
root is the library. A library made before 0.28.0, which keeps its
workshops in the previous layout,
is offered an upgrade first, which --yes accepts without asking; a
linked course whose link has gone while its repository is still there
is relinked. --init-only creates the library and stops; the other
options are those of launch, and arguments after -- go to
jupyter lab.
subscribe and unsubscribe¶
jupyter workshop subscribe LOCATION [--catalog] [--root ROOT] [--directory DIR | --library]
jupyter workshop unsubscribe LOCATION [--catalog] [--root ROOT] [--directory DIR | --library]
Adds a collection, or with --catalog a catalog, to a workshop
library’s subscriptions, or removes it. LOCATION is the index’s URL
or a path relative to the JupyterLab root, matched however it is
spelled. The library is --directory (workshops) under --root (the
current directory), or with --library the default library that
library opens. A directory that is not a library is
refused, since outside a library subscriptions live in the JupyterLab
settings, which the workshop browser changes.
list¶
jupyter workshop list [--json] [--root ROOT] [--directory DIR | --library]
Lists the installed workshops, with where each is, its version and its
progress, and in a library its subscriptions. In a library each
workshop has its kind: installed, personal or course. --json
prints an object with directory, library (whether it is one),
collections and catalogs (the registry’s lists, or null when the
settings apply) and workshops, the records the browser reads; the
shape is stable for scripts to rely on.
journal¶
jupyter workshop journal [--json] [--root ROOT] [--directory DIR | --library]
jupyter workshop journal --reset [--profile] [--yes] [--root ROOT] [--directory DIR | --library]
Shows the learning journal a
workshop library keeps in its journal/ directory: whether the profile
has been written, and a line per workshop or course with its status
(not started, in progress, finished or removed), its title,
when it was last touched, its path under the library and the pages
reached. A directory that is not a library has no journal, and a
library in which nothing has happened yet says so. --json prints an
object with directory, journal (whether anything has been
recorded), profile (whether it has been written) and history, the
frontmatter of every history file, most recently active first.
--reset moves the whole journal to journal-archive-<stamp>/ beside
it, so the library starts afresh; --reset --profile moves only
profile.md there and keeps the history. Either asks first unless
--yes is given, and nothing is deleted: moving the directory or the
file back undoes it.
update¶
jupyter workshop update [NAME...] [--yes] [--root ROOT] [--directory DIR | --library]
Installs the newest version a collection lists of each workshop
installed from it, where that differs from the installed version, as
the browser’s Update button does. NAME is a workshop’s name or its
path, and every installed workshop is checked when none is given; a
name two installs share must be given as a path. Updating replaces the
workshop, which resets its progress, so the command lists the updates
and asks first; --yes goes ahead without asking, and is needed when
there is no terminal to ask at.
remove¶
jupyter workshop remove NAME... [--delete] [--yes] [--root ROOT] [--directory DIR | --library]
Removes installed workshops as the browser’s Remove button does: a
downloaded workshop is deleted, and any other, a local directory, a
library’s own workshop or a course’s, loses only its recorded
progress, _workshop/, keeping its files. --delete deletes the
directory of such a workshop as well, as the browser’s Delete does for
one of your own. It lists what it will do and asks first unless given
--yes.
course¶
jupyter workshop course init DIRECTORY [--name NAME] [--title TITLE] [--description TEXT]
[--collection NAME[=TITLE]]... [--id-prefix PREFIX]
[--repo URL] [--lite] [--python X.Y] [--no-git]
[--link [--root ROOT] [--directory DIR]]
jupyter workshop course update [DIRECTORY] [--version X.Y.Z]
jupyter workshop course promote WORKSHOP COURSE [--collection NAME]
jupyter workshop course link PATH [--name NAME] [--workshops DIR] [--root ROOT] [--directory DIR]
jupyter workshop course unlink NAME [--root ROOT] [--directory DIR]
jupyter workshop course list [--json] [--root ROOT] [--directory DIR]
init writes a course repository:
a uv project pinning this release of the extension, AGENTS.md and
CLAUDE.md for agents, OUTLINE.md with the sections of the design
in place and nothing designed yet, a README.md, a Justfile holding
every common task and the order of each collection, .mcp.json,
jupyter_lab_config.py, an empty workshops/, a collection index for
each part of the course with catalog.json over them, the Binder and
Codespaces files, and a test workflow; with --lite the JupyterLite
site files and a Pages workflow as well, and lint and tests on both
frontends. Each --collection is a part of the course, with an index of
its own, named NAME and titled TITLE; with none, the course is one
collection named after it. Collection ids are
PREFIX/<course>/<collection>, where --id-prefix defaults to the
repository’s forge and owner when --repo is given, as
github.com/owner, and otherwise to the course’s name; an id is the
collection’s identity to subscribers and to analytics, so set it before
the first workshop is written and never change it. The directory
becomes a git repository on main, with nothing committed, unless
--no-git says otherwise, and --link links it into a workshop
library as well, the default library unless --root and --directory
name another. What was written, and the hash of each file, is recorded
in course.json.
update brings a course up to a release, this installation’s unless
--version names one: it moves the pin in pyproject.toml and
binder/requirements.txt whatever else is in them, writes again every
generated file that is still as the scaffold last wrote it, adds any
the scaffold now writes, and leaves alone, and reports, the files edited
since they were generated, which stay edited files to every later
update. Run just requirements afterwards to relock.
promote moves a workshop of its own into a course: the directory goes
whole into the course’s workshops/, with its progress and gist record,
and its own git repository and Workshop Author conversation end with
the move. --collection names the part of the course it joins, by the
index’s directory under collections/; a course with one collection
needs no name, and one with none takes the workshop into workshops/
alone. In the collection it joins, an entry written from the workshop’s
manifest and pages goes into OUTLINE.md at the end of that
collection’s workshops section, the index is rebuilt with the workshop
last, using the repository address the Justfile names, and the
Justfile’s order for the collection gains its name. The move is then
committed in the course as “Add the workshop NAME”; when git has no
identity to commit as, or the course is not a repository, the command
says so and leaves the commit to you. A workshop downloaded from a
collection, or one already inside the course, is refused. The browser’s
Move to course… button does the same, asking which course and which
part.
link, unlink and list manage the courses of
a workshop library. A repository kept under the library’s
personal/courses/ is a course without any of these; link brings in
one kept elsewhere, as a symbolic link, or a directory junction on
Windows, at personal/courses/NAME (the repository’s directory name by
default), recorded in the registry. --workshops names its workshops
directory when it is not workshops. unlink removes a linked course’s
link and entry, never its files, and works when the repository has gone.
list shows each course as kept, linked or missing; --json prints
them as an object with a courses list. These commands act on the
default library unless --root or --directory name another.
skill¶
jupyter workshop skill [--link [DIR]]
Prints where this installation keeps the jupyterlab-workshop-authoring
skill, the guide an AI agent follows to write workshops. --link makes
.claude/skills/jupyterlab-workshop-authoring in DIR (the current
directory by default) a symbolic link to it, so Claude Code working in
a repository has the skill that matches the installed release and
nothing is copied; a course’s just skill and just install run it.
kernels¶
jupyter workshop kernels [--prune]
Lists the kernels registered for workshop environments:
the kernelspecs whose Python lives under a workshop’s _workshop/venv
directory. Each line gives the name, ok or stale, and the Python it
starts; stale means that Python no longer exists, because the workshop
was removed or moved without its environment being removed first.
--prune unregisters the stale ones. Every other kernel, the server’s
own included, is left alone whatever its state.
record¶
jupyter workshop record RECORDING DIRECTORY [--name NAME] [--title TITLE]
Writes draft pages from a recording saved by the Record button in
JupyterLab (a JSON file under the workshop’s _workshop/recordings/).
When the directory is a workshop the pages are added to it and its
manifest gains the pages and capabilities they need; otherwise a new
workshop is created there. See Writing workshops in
JupyterLab for what the draft contains.
mcp¶
jupyter workshop mcp [--url URL --token TOKEN]
Serves the tools to AI agents over the Model Context Protocol on
standard input and output; needs the mcp extra. Lint, render, test,
init, publish and draft work on a directory the agent names on each
call, relative to where the client started the server. The live tools
drive a running JupyterLab that has a workshop open in author mode,
found through --url and --token, else the JUPYTER_SERVER_URL and
JUPYTER_TOKEN environment variables, else the first server that
jupyter server list reports; the workshop path they open is relative
to that server’s root. See Tools for AI
agents for how the tools work and
where to start the client and JupyterLab.
launch¶
jupyter workshop launch [TARGET] [--ref REF] [--subdir DIR] [--sha256 HASH]
[--collection URL]... [--catalog URL] [--install]
[--var NAME=VALUE]... [--restart[=force]]
[--welcome FILE] [--trust trusted|restricted|ask]
[--analytics always|never|ask]
[--root DIR] [--port PORT] [--no-browser] [--fresh]
[--container | --no-container] [--token TOKEN]
[--url URL] [-- jupyter lab options]
Starts JupyterLab with a workshop, collection or catalog open, so the
launch link that a learner would be
handed does not have to be typed by hand. TARGET is a workshop
directory under the root, a repository, forge tree or archive URL, or,
with --collection, the name of one of the collections’ workshops;
left out, JupyterLab starts in the workshop browser. --ref, --subdir
and --sha256 select within a URL as the link parameters of the same
names do, --collection, which can be repeated to list several in that
order, and --catalog add sources for the session,
--var sets workshop variables and --restart starts a workshop that
is already there over first, asking when it has recorded progress unless
=force is given. A collection, catalog or welcome file can be a URL or
a file under the root; a directory holding a collection.json or
catalog.json may be named in place of the file.
A collection or catalog named this way is added for the session, which
the browser keeps in the workspace’s saved state, so a later launch on
the same root and workspace still lists it, in its order, until it is
removed in the Collections dialog or promoted by Subscribe; --fresh
starts without it. With --install, every workshop of the collections
named that is not installed yet is installed before the server starts,
as install does, into the workshops directory the installed
overrides name, taking only the entries for this operating system and
for JupyterLab, so the learner finds them under Installed rather than
installing each on click; a workshop that cannot be downloaded stops the
launch. A catalog is added for the session only, since one can list far
more than a learner wants.
The server runs on a free port unless --port is given, with the current
directory as its root unless --root names another; everything it opens
has to sit under that root, and a target outside it is refused with a
message saying so. Once the server answers, the link is printed and
opened in the browser, or only printed with --no-browser. JupyterLab’s
log and its Ctrl-C handling are as for jupyter lab.
Three options settle the session rather than the link. --trust forces
the trust level, skipping the dialog, the way a deployment’s
trustPolicy does; it is merged into the installed overrides.json for
the session only, so a Binder image’s other settings still apply.
--analytics sets the report key of the analytics setting the same
way: always reports to the sink a collection or a workshop declares
without asking, never reports to none, and ask offers the opt-in in
the trust dialog, which is the installed default; see reporting to a
sink.
--fresh gives the server JupyterLab workspaces and user settings of its
own, as test does, so a demo is not shaped by the tabs and
preferences of other sessions. Anything after -- is passed to
jupyter lab unchanged, for options such as --ip. The session’s
overrides also turn off JupyterLab’s question about fetching Jupyter
news, unless the installed overrides settle it, so the first thing shown
is the workshop and not that prompt; see the Jupyter news
prompt.
Inside a container the command serves the container instead of a
desktop. Container mode is on when the platform detection finds a
container, or with --container anywhere, and --no-container turns
it off. In that mode the server listens on every interface on port
8888, the port Jupyter images publish, unless --port says otherwise;
the token is --token, or the JUPYTER_TOKEN variable when set, so a
restarted container keeps its link, and only otherwise generated; the
trust level is forced to trusted unless --trust chooses another,
since whoever ran the image or named the collection chose the
workshops; and no browser is opened. The link is printed against
http://127.0.0.1:8888, which is right when the container publishes
that port on the same machine, or against --url when it is reached at
another address, such as behind a proxy. The published image starts
with this command; see a container image.
Installed as a uv tool with the lab extra, uv tool install "jupyterlab-workshop[lab]", the command runs as jupyter-workshop launch from any directory without a project environment; see
getting started.
For a demo that must always start clean and never ask:
jupyter workshop launch workshops/git-basics --restart=force --trust trusted --fresh
lite¶
jupyter workshop lite [my-workshop ...] [--out DIR] [--python X.Y]
[--default NAME] [--trust LEVEL]
[--collection URL|FILE] [--catalog URL|FILE]
[--settings FILE] [--welcome FILE]
[--no-terminal] [--lite-dir DIR]
[--serve] [--port PORT]
Builds a static JupyterLite site carrying the workshops, with
the extension, the Pyodide kernel and the terminal, that any web host can
serve. Needs the lite extra; the terminal’s build step needs node,
npm and micromamba unless --no-terminal is given. --serve serves
the result locally to try it out.
With no workshop at all the site is a launcher: it starts in an empty
workshop browser and opens whatever a launch
link names in its workshop parameter,
such as a gist. The Python the site provides is whichever the installed
Pyodide kernel package carries, which jupyter workshop lite writes
into the site’s configuration so the preflight can check a workshop’s
Python requirement against it; --python X.Y makes the build fail
unless that is the version it would carry, for a site published under
a path that names its Python. See A launcher for launch
links.
A site with one workshop, or with --default NAME, opens that workshop
on start; any other site starts in the workshop browser. --collection
takes the URL of a collection index, or a local collection.json (or
the directory holding one) that is carried in the site, so the browser
lists the workshops under the collection’s title and in its order
without the build knowing where the site will be served from.
--catalog takes a URL or a local catalog.json in the same way, and
carries the collections the catalog names by relative path with it.
--settings FILE builds a settings file in the form of overrides.json
into the site, for an analytics block, disabled features and the like,
and --welcome FILE carries a Markdown file in the site and shows it as
the welcome message. The site’s settings turn off JupyterLab’s Jupyter
news prompt unless the file settles it. Publishing
workshops has the detail.
test¶
jupyter workshop test my-workshop [--junit FILE] [--json FILE] [--in-place]
[--headed] [--timeout SECONDS]
[--action-timeout SECONDS]
[--pace fast|demo|presentation]
[--start-delay SECONDS] [--step-delay SECONDS]
[--page-delay SECONDS]
[--trust trusted|restricted|ask]
[--lite | --frontend jupyterlite] [--lite-dir DIR]
Runs the workshop in a real JupyterLab: it copies the workshop to a
temporary directory (unless --in-place), starts a JupyterLab server on a
free port with trust forced to the chosen level and the Jupyter news
prompt off, opens it in a headless Chromium through Playwright, and runs
the extension’s self-test command.
That command walks every page, runs every action in order, waits for
each terminal command to finish, answers quizzes correctly, submits forms
with their defaults, and runs every check. Each action is reported as
pass, fail or skip, and the exit code is 1 when anything failed. --junit
writes a JUnit XML report for CI, --json the full results. Colour codes
and other control characters in a check’s message, such as the ones
Python puts in a traceback on a terminal, are removed from every report.
A check runs under test the way it runs for a learner. A verify that
declares a trigger is given the same time to settle
that the trigger would give it: when it fails, it is tried again over
the next few seconds before the failure stands, so a check that reads
what an earlier command is still writing passes under test as it does
on the page. Where the trigger has already fired, as after: does the
moment the action before it completes, the self-test reports that run’s
outcome rather than starting another. A verify with no trigger gets the
single attempt that clicking Check gives it.
Actions the page runs on its own are treated the same way. One with
:auto: page-enter fires as the page is entered, one reached by a
cascade or an :auto: after: follows the action before it, and the
learner sees each once; the self-test lets such a chain finish and
records the outcome of the run it made, reported with “Ran on its own”
where the action left no message, rather than running the action a
second time. Only what did not run on its own is run by the self-test,
and the same holds for Run actions and Run checks in author mode: to
run an automatic action again after editing it, click it.
Warning
The temporary copy protects the workshop’s own files and nothing else.
Every terminal command, execute-capture body, script verify and
kernel check runs as you, on this machine, with your home directory,
your environment variables and the Python environment JupyterLab is
running in. A workshop written for a throwaway container or a fresh
account may change global git configuration, append to shell start-up
files, install packages into your project’s environment, clone into
paths under your home directory, or remove paths it assumes it created.
Run a second time, such steps can fail or double up.
Read every command before testing a workshop you did not write, and test
one that reaches outside its own directory in CI, a container or a
disposable account rather than on a machine you care about; the
workflow written by init --ci runs on a fresh runner every time.
An action that is still running after --action-timeout seconds (default 300) is reported as failed and the run stops there, since later actions
would build on an unknown state. An execute, execute-capture or
verify whose directive names a longer :timeout: of its own (or that
inherits one from the manifest’s defaults.actions) is given that plus
half a minute instead, so a step that waits on a build or a rollout is
not cut short by the flat limit. An action that opens a dialog nothing
will answer, such as a kernel selection or a confirmation, is failed
sooner, after the dialog has been open for ten seconds, with the
dialog’s title in the message. --timeout (default 1200) bounds the
whole run: when it passes, the harness collects the results gathered so
far, records the action in flight as failed, and exits with code 1. All
three limits exist so that a stuck action in CI produces a report naming
it rather than a job that never ends.
Pacing a run for an audience¶
The same run can be slowed down to watch, to record as a video or to
step through live in front of an audience. --pace demo pauses briefly
before each action (2s before the first, 1.5s before each one, 3s on
each new page), for a screen recording that will be edited; --pace presentation pauses longer (5s, 4s and 8s), for people watching along.
A paced run scrolls each action into view in the instructions panel and
pulses it before the pause, so the viewer sees what is about to happen,
then runs it. The pauses are not charged against --action-timeout,
and a paced run takes a longer --timeout by default (2400s for demo,
3600s for presentation). --start-delay, --step-delay and
--page-delay set any one of the pauses in seconds on top of the pace.
Any pace but fast shows the browser, as --headed does, since there
is nothing to watch otherwise.
The MCP run_workshop and run_page tools take the same pace and
delays, and run in the JupyterLab you are looking at rather than a
headless one; see Tools for AI agents.
The server runs with JupyterLab workspace and user settings directories
of its own under the temporary directory, so nothing from your own
JupyterLab sessions reaches the run: no tabs the layout restorer would
put back (a console whose kernel the test server lacks would otherwise
raise a kernel selection dialog under the first action), no default
kernel, theme or disabled extension of yours, and the run writes nothing
into your JupyterLab state either. --in-place isolates the same way;
only the workshop directory is shared in that mode.
A workshop with an isolated environment creates it
inside the temporary copy, and registers its kernel for your user. The
test unregisters that kernel again when it removes the copy, so no
kernel pointing at a deleted directory is left in the kernel picker.
With --in-place the environment and its kernel stay, since the
workshop does.
The self-test follows the path where the learner gets everything right. What a check says on a wrong answer is tested by an attempt, a block the learner never sees: the self-test runs the actions it holds, then the check it names, and passes the attempt when the check fails saying what the attempt expects. Each attempt is one line of the report, with what the check said.
An action that waits for a person, dialog, upload-prompt or tour,
is not run and is reported as a skip. A tour is still checked as far
as it can be without stepping through it: a step whose selector matches
nothing on screen at that point of the page is reported as a failure,
as the tour would fail there for a learner.
The self-test waits for the instructions panel to show each page before
running the page’s actions, so a highlight, tooltip or tour may
point at part of the panel itself, such as its header or footer.
Requirements: the test extra, which installs Playwright, a library
that drives a browser from Python (uv add "jupyterlab-workshop[test]"
or pip install "jupyterlab-workshop[test]"), and a browser for it,
which playwright install chromium downloads into Playwright’s own
cache. Terminals started by the test use a non-interactive pager so
commands such as git diff do not wait for a key press.
Commands in the tested workshop should not need input. A check that depends on something only a person would do fails the self-test, which is the point: the self-test is what a workshop’s CI runs.
The self-test runs on Windows as well, where terminals are PowerShell
and :windows: command variants are selected; the workflow written by
init --ci covers Linux, macOS and Windows. --lite, or --frontend jupyterlite, builds a JupyterLite site with the workshop instead of
starting a server, serves it from a static file server and drives that,
with :jupyterlite: variants selected; see JupyterLite for
what it needs.