Jupyter Resource Usage

1.2.1 verified Mon Apr 27 auth: no python

Jupyter extension displaying real-time memory, CPU, and disk usage for notebooks and the Jupyter server. Current version 1.2.1, released Dec 2024, with monthly releases.

pip install jupyter-resource-usage

Common errors

error ModuleNotFoundError: No module named 'jupyter_resource_usage' ↓

cause Installed only the JupyterLab extension (npm) without the Python package.

fix

Run pip install jupyter-resource-usage to install the Python server extension.

error 500 Internal Server Error on /api/metrics/v1 ↓

cause The server extension is not enabled or the Jupyter config lacks required permissions.

fix

Enable the extension with jupyter server extension enable jupyter_resource_usage and restart Jupyter.

error ImportError: cannot import name 'ResourceUsage' from 'jupyter_resource_usage' ↓

cause Trying to import a class that does not exist in the public API.

fix

The Python API is mainly for configuration; use from jupyter_resource_usage import _load_jupyter_server_extension if needed.

Warnings

breaking Version 1.0.0 moved from `jupyter-resource-usage` npm package to `@jupyter-server/resource-usage`. The Python package name changed from `jupyter-resource-usage` to `jupyter-server-resource-usage`? No, keep using jupyter-resource-usage. The breaking change is in the frontend extension. If you are using JupyterLab <3, you must pin to <1.0.0. ↓

fix Upgrade to JupyterLab 3+ or pin jupyter-resource-usage to 0.x.

gotcha The extension only reports memory/CPU of the notebook server process, not individual kernels. For per-kernel usage, use `jupyterlab-system-monitor`. ↓

fix Install jupyterlab-system-monitor for granular per-kernel metrics.

deprecated The `/api/metrics/v1` endpoint is deprecated in favor of the Jupyter Server's `/api/kernels` and `psutil`-based metrics. Future versions may remove it. ↓

fix Use the Jupyter Server's REST API with `psutil` directly for custom monitoring.

Install

conda install -c conda-forge jupyter-resource-usage

Imports

ResourceUsage

from jupyter_resource_usage import ResourceUsage

Correct import path for Python package

Quickstart

Fetch resource usage metrics from the Jupyter server API.

from jupyter_resource_usage import ResourceUsage

# Requires a running Jupyter server; the extension auto-activates
# To fetch current resource usage:
import requests
from notebook.auth import passwd

response = requests.get(
    'http://localhost:8888/api/metrics/v1',
    headers={'Authorization': 'token ' + os.environ.get('JUPYTER_TOKEN', '')}
)
print(response.json())