jupyterlab_notifications_extension
JupyterLab extension that shows notifications from external systems in the native notification system: a toast, the notification center, and optional action buttons. Messages may carry simple Markdown and a small HTML subset.
The extension is the notification backbone for Stellars JupyterHub Platform for Data Science. A notification is posted to one JupyterLab server and shown to every open tab of that server.
The command palette sends a notification by hand:
Features
- REST API for external systems, with token authentication
- Command palette dialog and the programmatic
jupyterlab-notifications:sendcommand - Six notification types: default, info, success, warning, error, in-progress
- Auto-close in milliseconds, manual dismiss, or silent mode that shows the center only
- Action buttons that run any JupyterLab command
- Markdown and sanitised HTML rendering, including colour and font-size spans
- Dynamic time-ago indicator on every notification
- WebSocket push of every notification to every open tab, with 30-second polling as the fallback
transientnotifications that leave nothing in the notification center
Agent Skill
.agents/skills/jupyterlab-notifications-extension/SKILL.md tells an AI assistant how to drive the jupyterlab-notify CLI. It carries the rules --help cannot state; the command reference stays in --help.
The skill ships in the repository and in the wheel, at <sys.prefix>/share/jupyter/agents/skills/jupyterlab-notifications-extension/SKILL.md. One of the two links below makes it readable:
# After pip install, with the Python that runs the lab
mkdir -p ~/.agents/skills && ln -sfn "$(python -c 'import sys; print(sys.prefix)')/share/jupyter/agents/skills/jupyterlab-notifications-extension" ~/.agents/skills/jupyterlab-notifications-extension
# From a clone, into Claude Code
ln -sfn "$PWD/.agents/skills/jupyterlab-notifications-extension" ~/.claude/skills/jupyterlab-notifications-extension
Installation
pip install jupyterlab_notifications_extension
Requires JupyterLab 4.6.0 or later and Python 3.12 or later.
API Reference
POST /jupyterlab-notifications-extension/ingest
Posts one notification. Authentication is an Authorization: token <TOKEN> header; do not put the token in the URL, where it lands in server and proxy access logs.
{
"message": "Your notification message",
"type": "info",
"autoClose": 5000,
"immediate": true,
"transient": true,
"actions": [
{
"label": "Click here",
"caption": "Additional info",
"displayType": "accent"
}
]
}
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
message |
string | Yes | - | Notification message, rendered as Markdown with limited HTML (see Message Formatting) |
type |
string | No | "info" |
Visual style: default, info, success, warning, error, in-progress |
autoClose |
number/boolean | No | 5000 |
Milliseconds before auto-dismiss. false = manual dismiss only. 0 = silent mode (notification center only, no toast) |
immediate |
boolean | No | false |
Accepted for compatibility; no longer changes delivery, because every notification is pushed (see Immediate Delivery) |
transient |
boolean | No | false |
Dismiss the notification when its toast closes, so it does not remain in the notification center |
data |
object | No | - | Arbitrary JSON attached to the notification; every number in it must be finite |
actions |
array | No | [] |
Action buttons (see below) |
A transient notification exists only while its toast is visible: its links and action buttons are removed with the toast.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
label |
string | Yes | - | Button text |
caption |
string | No | "" |
Tooltip text |
displayType |
string | No | "default" |
Visual style: default, accent, warn, link |
commandId |
string | No | - | JupyterLab command ID to execute (e.g., filebrowser:open-path) |
args |
object | No | {} |
Arguments passed to the command |
Any button click dismisses the notification; a commandId runs that command first.
Response 200 OK:
{
"success": true,
"notification_id": "notif_1762549476180_1"
}
Errors:
400 Bad Request- invalid JSON, a body that is not a JSON object, amessagethat is missing, empty or not a string, anactionsthat is not a list, an action element that is not an object with a stringlabel, atransientthat is nottrueorfalse, or a number anywhere in the payload that is not finite (NaN,Infinity, or a literal that overflows to one)403 Forbidden- missing or invalid authentication token500 Internal Server Error- server-side processing error
Usage Examples
From another JupyterLab extension
await app.commands.execute('jupyterlab-notifications:send', {
message: 'Build finished',
type: 'success',
autoClose: 3000
});
await app.commands.execute('jupyterlab-notifications:send', {
message: 'Report ready',
type: 'info',
autoClose: false,
actions: [
{
label: 'Open',
commandId: 'help:open',
args: { url: 'https://example.com/report' },
displayType: 'accent'
}
]
});
CLI
jupyterlab-notify is installed with the extension:
jupyterlab-notify -m "Deployment complete" -t success
jupyterlab-notify --url "http://127.0.0.1:8888/jupyterhub/user/alice" -m "Hello"
jupyterlab-notify -m "System maintenance in 1 hour" -t warning --no-auto-close
jupyterlab-notify -m "Task complete" --action "Dismiss"
jupyterlab-notify -m "Help Available!" --action "Open Help" \
--cmd "iframe:open" --command-args '{"path": "local:///welcome.html"}'
jupyterlab-notify -m "Background task finished" --auto-close 0
jupyterlab-notify -m "Deploy finished" --now
jupyterlab-notify -m "Build finished" --transient
URL detection:
- Listed servers -
jupyter server list --json; the URL comes from the record's scheme, host and port, with a loopback address substituted for a wildcard bind - Ambiguity - several servers and none matching
JUPYTERHUB_SERVICE_PREFIXprints the list and exits 2 - Fallback -
JUPYTERHUB_SERVICE_PREFIX, thenhttp://127.0.0.1:$JUPYTER_PORT, port 8888 when unset - Explicit
--url- a URL matching a listed record is re-addressed to that record's own host, so the host printed can differ from the host given - Query and fragment - dropped, because the endpoint path is appended to the URL
- No password in
--url- theuser:password@part is dropped from a URL that names a host; two malformed shapes keep it, one with no//at all and one whose password holds an unencoded/
Authentication:
JUPYTERLAB_NOTIFY_TOKEN- this tool's own variable, used for any target; prefer it over--token, which puts the secret in argv where every local account can read it- Server token - sent to the address the server's runtime record is reached at: 127.0.0.1 for a server bound to 0.0.0.0, and the bound address for
--ip <address> - Ambient hub variables -
JUPYTERHUB_API_TOKEN,JPY_API_TOKENandJUPYTER_TOKENbelong to this host, so they are sent only to a loopback target
--now is accepted for compatibility and no longer changes delivery: every notification is pushed over the WebSocket.
cURL
curl -X POST http://localhost:8888/jupyterlab-notifications-extension/ingest \
-H "Content-Type: application/json" \
-H "Authorization: token YOUR_JUPYTER_TOKEN" \
-d '{"message": "Build completed", "type": "success"}'
curl -X POST http://jupyterhub.example.com/user/alice/jupyterlab-notifications-extension/ingest \
-H "Content-Type: application/json" \
-H "Authorization: token YOUR_JUPYTER_TOKEN" \
-d '{"message": "Deploy finished", "type": "success", "immediate": true}'
Immediate Delivery
Every notification is pushed to every open tab over a WebSocket and also queued for the 30-second poll. immediate (REST) and --now (CLI) are accepted for compatibility and no longer change delivery.
- Transport - the frontend keeps a WebSocket open to
/jupyterlab-notifications-extension/stream - Every connected tab - the push reaches all open tabs at once
- Best-effort poll - the poll serves a tab whose socket is down or that opened later; the queue is a single-consumer destructive drain, so such a tab is not guaranteed that notification
- Keepalive - ping and pong survive proxy idle timeouts, including behind JupyterHub
- De-duplication - notification ids are tracked, so a notification arriving by both push and poll is shown once
- Reconnect - capped exponential backoff from 5 to 60 seconds, retrying while the tab stays open
Time-Ago Indicator
Each notification shows a relative timestamp that updates every 10 seconds: just now under a minute, then minutes, hours and days. The indicator sits below the message, or inline with the button bar when actions exist. The notification center shows the same indicator for every listed notification.
Message Formatting
message renders as GitHub-flavoured Markdown and a small HTML subset, sanitised before display, in both the toast and the center. A single newline becomes a line break.
- Rendered - paragraphs, bold, italic, strikethrough, inline and fenced code, block quotes, ordered and unordered lists, links and autolinks
- Tags kept -
p,br,strong,b,em,i,u,s,del,code,pre,blockquote,ul,ol,li,a,span - Attributes kept -
href,title,style,target,rel - Removed - everything else, including
script,style,iframe,object,embed,form,input,img,svg,math,id,name,class,data-*,aria-*and event handlers such asonclick - Links - http, https and mailto only; a kept link opens in a new tab with
target="_blank"andrel="noopener noreferrer", and clicking it does not dismiss the notification - Preview - at most 140 visible characters plus an ellipsis, counted after rendering
- Other sources - notifications from JupyterLab or another extension keep plain text and are never parsed
style accepts two properties:
| Property | Accepted values |
|---|---|
color |
3, 4, 6 or 8 digit hex; a colour keyword; rgb(), rgba(), hsl() or hsla() |
font-size |
0; 0 to 48 with px; 0 to 4 with em or rem; 0 to 300 with %; a CSS size keyword |
Other declarations, including background, position, url(), expression(), var() and !important, are removed.
jupyterlab-notify -m '**Backup complete** in <span style="color: #2e7d32">12 minutes</span>. Download the [report](https://example.com/report).'
Architecture
A notification is posted to one server; there is no per-recipient addressing. Flow: external POST → WebSocket push to every open tab, and in-memory queue → frontend poll every 30 seconds → JupyterLab notification manager → queue cleared after the fetch. The push and poll copies are deduplicated by id.
Troubleshooting
- Frontend installed but not working -
jupyter server extension listverifies the server extension - Server extension enabled but frontend missing -
jupyter labextension listverifies the frontend extension - Notifications not appearing - check the browser console for polling errors; restart JupyterLab after installation
Uninstall
pip uninstall jupyterlab_notifications_extension
Metadata
Release files for jupyterlab-notifications-extension 1.3.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jupyterlab_notifications_extension-1.3.7.tar.gz | 589.0 kB | Without provenance | Details for jupyterlab_notifications_extension-1.3.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jupyterlab_notifications_extension-1.3.7-py3-none-any.whl | Python 3 | none | any | Details for jupyterlab_notifications_extension-1.3.7-py3-none-any.whl |
Total release size: 732.9 kB
Release files / jupyterlab_notifications_extension-1.3.7.tar.gz
| Download URL | jupyterlab_notifications_extension-1.3.7.tar.gz |
|---|---|
| Size | 589.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9973e0be94c6b3ebd44660fc7576e42a75fd2bcf28e9d4dab0ce26bd52441e5d
|
|
BLAKE2b-256 checksum How to use checksums |
e8d170fd8d538ee6ce5b1176371d2278515548d3ed854efe75611b328f6dd5d6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.10
|
Release files / jupyterlab_notifications_extension-1.3.7-py3-none-any.whl
| Download URL | jupyterlab_notifications_extension-1.3.7-py3-none-any.whl |
|---|---|
| Size | 143.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3b90f7ebec56f8533f4627f4fc029b5f650dd7779f9246f8ef5b1d75a5fc73e2
|
|
BLAKE2b-256 checksum How to use checksums |
41e1a0026625d47c0bf605468bdbc4cea6fc920c334be48a54dc95b6c018d781
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.10
|
Security for jupyterlab-notifications-extension 1.3.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.