Jupyter Events
raw JSON → 0.12.0 verified Tue May 12 auth: no python install: verified quickstart: stale
Jupyter Events is an event system library that enables Jupyter Python applications (e.g., Jupyter Server, JupyterLab Server, JupyterHub) and extensions to emit structured data describing internal happenings. Other software can then listen and respond to these events. The current version is 0.12.0, with releases occurring periodically to introduce new features, improvements, and bug fixes.
pip install jupyter_events Common errors
error TypeError: create.<locals>.Validator.__init__() got an unexpected keyword argument 'registry' ↓
cause This error occurs due to an incompatibility between `jupyter-events` and newer versions of its `jsonschema` dependency, where the `Validator` class in `jsonschema` no longer accepts the `registry` argument that `jupyter-events` expects.
fix
Downgrade
jsonschema to a compatible version (e.g., jsonschema==4.19.2) or upgrade jupyter-events to its latest version, which may have resolved the dependency conflict. error JupyterEventsVersionWarning: The `version` property of an event schema must be a string. It has been type coerced, but in a future version of this library, it will fail to validate. Please update schema: <schema_url> ↓
cause An event schema being used by `jupyter-events` has its `version` property defined with a non-string type, which is deprecated and will lead to validation errors in future library versions.
fix
Modify the event schema to ensure the
version property is explicitly a string type. error ModuleNotFoundError: No module named 'jupyter_events' ↓
cause The `jupyter_events` package is either not installed in the Python environment that Jupyter is currently using, or there is a discrepancy between the environment where the package was installed and the active Jupyter kernel's environment.
fix
Install
jupyter-events using pip install jupyter_events (or conda install -c conda-forge jupyter_events if using Anaconda) in the correct Python environment, and then restart your Jupyter kernel or server. error ValidationError: '$id' is a required property ↓
cause This error indicates that an event schema being registered or validated by `jupyter-events` is missing the mandatory `'$id'` key, which is required for identifying the schema.
fix
Ensure all event schemas include a unique
"$id" property, which should be a valid URI, to correctly identify the schema. error ValidationError: 'version' is a required property ↓
cause This error signifies that an event schema being registered or validated by `jupyter-events` lacks the mandatory `'version'` key, which is essential for schema versioning.
fix
Ensure all event schemas include a
"version" property with a string value to specify the schema's version. Warnings
breaking Applications previously using `jupyter-telemetry` (e.g., JupyterHub) must migrate to `jupyter-events`. The API for event emission and schema definition is different and direct compatibility is not maintained. ↓
fix Review `jupyter-events` documentation for equivalent functionalities and update event emission calls and schema definitions. Consult the changelog of dependent applications (like JupyterHub) for specific migration guides.
gotcha Event schemas must be explicitly registered with the `EventLogger` using `register_event_schema()` before emitting events. If an event is emitted for an unregistered schema ID, it will not be recorded and may raise an error or be silently dropped depending on the `EventLogger`'s configuration or version. ↓
fix Always call `event_logger.register_event_schema(your_schema_dict)` for each schema ID that your application intends to emit events for. Ensure the `$id` field in your schema dictionary matches the `schema_id` used in `emit()` calls.
gotcha Sensitive data in event payloads requires careful handling, especially if event data is routed to client applications or persistent storage. While `jupyter-events` allows for redaction policies, an incorrect or missing policy could expose sensitive information. ↓
fix Define and apply appropriate redaction policies within your event schemas. Thoroughly test event flows to ensure sensitive data is not inadvertently exposed or logged in plaintext, especially when integrating with client-side listeners or external logging services.
breaking Event schemas submitted for registration must conform to the `jupyter-events` meta-schema. Specifically, they must include top-level `version`, `$id`, and `properties` fields. Failure to include these required properties will result in a `jsonschema.exceptions.ValidationError` during schema registration. ↓
fix Ensure your event schema dictionary includes the `version`, `$id`, and `properties` fields at the root level. For example:
```json
{
"$id": "https://example.com/schemas/my_event.json",
"version": "1",
"title": "My Custom Event",
"description": "A simple custom event for demonstration.",
"type": "object",
"properties": {
"message": {"type": "string"},
"level": {"type": "string", "enum": ["info", "warning", "error"]}
},
"required": ["message", "level"]
}
```
gotcha Event schemas registered with `jupyter-events` must conform to the `jupyter-events` meta-schema. This meta-schema requires specific top-level properties like `$id`, `version`, and `properties` to be present. Omitting a required meta-schema property will result in a `jsonschema.exceptions.ValidationError` during schema registration. ↓
fix Ensure your event schema dictionary includes all required top-level fields such as `$id`, `version` (e.g., `'version': '1'`), and `properties` as specified by the `jupyter-events` meta-schema. Consult the `jupyter-events` documentation for the full meta-schema specification.
Install
conda install -c conda-forge jupyter_events Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 6.14s 32.0M
3.10 alpine (musl) - - 6.82s 31.9M
3.10 slim (glibc) wheel 3.7s 4.51s 33M
3.10 slim (glibc) - - 4.34s 33M
3.11 alpine (musl) wheel - 6.69s 35.2M
3.11 alpine (musl) - - 7.86s 35.0M
3.11 slim (glibc) wheel 3.8s 6.21s 36M
3.11 slim (glibc) - - 5.80s 36M
3.12 alpine (musl) wheel - 6.44s 26.8M
3.12 alpine (musl) - - 7.22s 26.6M
3.12 slim (glibc) wheel 3.3s 6.84s 28M
3.12 slim (glibc) - - 7.77s 27M
3.13 alpine (musl) wheel - 5.95s 26.2M
3.13 alpine (musl) - - 6.66s 25.9M
3.13 slim (glibc) wheel 3.3s 6.39s 27M
3.13 slim (glibc) - - 6.98s 27M
3.9 alpine (musl) wheel - 6.04s 31.4M
3.9 alpine (musl) - - 6.69s 31.2M
3.9 slim (glibc) wheel 4.3s 5.42s 32M
3.9 slim (glibc) - - 5.73s 32M
Imports
- EventLogger
from jupyter_events import EventLogger
Quickstart stale last tested: 2026-04-24
import logging
from jupyter_events import EventLogger
import json
import os
# Define a simple event schema (in-memory for this example)
my_event_schema = {
"$id": "https://example.com/schemas/my_event.json",
"title": "My Custom Event",
"description": "A simple custom event for demonstration.",
"type": "object",
"properties": {
"message": {"type": "string"},
"level": {"type": "string", "enum": ["info", "warning", "error"]}
},
"required": ["message", "level"]
}
# Create a temporary log file
event_log_file = 'quickstart_events.log'
# Initialize EventLogger with a FileHandler and register the schema
logger = EventLogger(
handlers=[logging.FileHandler(event_log_file)],
allowed_schemas=[my_event_schema["$id"]]
)
logger.register_event_schema(my_event_schema)
# Emit an event
print(f"Emitting an 'info' event...")
logger.emit(schema_id=my_event_schema["$id"], data={'message': 'This is a test event!', 'level': 'info'})
print(f"Event emitted to {event_log_file}")
# Read the logged event
with open(event_log_file, 'r') as f:
logged_event = json.loads(f.readline())
print(f"Logged event: {logged_event}")
# Clean up the log file
os.remove(event_log_file)