Skip to main content

jupyterlab_kernel_terminal_workspace_culler_extension

GitHub Actions npm version PyPI version Total PyPI downloads JupyterLab 4 Brought To You By KOLOMOLO Donate PayPal

Automatically cull idle kernels, terminals, and workspaces after configurable timeout periods. Helps manage system resources by cleaning up unused resources that accumulate during long JupyterLab usage.

Resource Culler Screenshot

Features

  • Idle kernel culling - Shut down kernels idle beyond timeout (checks execution_state and last_activity)
  • Idle terminal culling - Close terminals with no WebSocket activity beyond timeout, and any terminal idle beyond a maximum (7 days by default)
  • Workspace culling - Remove stale JupyterLab workspaces, named and auto-generated (auto-0, auto-k, etc.), based on last modified time; the default workspace is kept
  • Configurable timeouts - All timeouts adjustable via JupyterLab Settings
  • Notifications - Optional toast notifications when resources are culled (requires jupyterlab-notifications)
  • Server-side detection - Uses tornado PeriodicCallback for accurate activity tracking

Default Settings

Setting Default Description
Kernel timeout 60 min (1 hour) Idle kernels culled after this period
Terminal timeout 60 min (1 hour) Inactive terminals culled after this period
Terminal maximum 10080 min (7 days) Culled after this period even with an open tab or a workspace reference
Disconnected only enabled Only cull terminals with no open browser tab, until the terminal maximum
Workspace culling enabled Cull stale workspaces (default workspace protected)
Workspace timeout 10080 min (7 days) Stale workspaces culled after this period
Check interval 5 min How often the culler checks for idle resources
Notifications enabled Show notification when resources are culled

How Idle Detection Works

Kernels: Checked for execution_state (busy kernels are never culled) and last_activity timestamp. A kernel is idle when it's not executing and hasn't had activity beyond the timeout.

Terminals: A terminal referenced by any existing workspace is not culled - the workspace must be culled first, which releases its terminals unless another surviving workspace still references them (the cascade). Beyond that, only terminals with no active browser tab are culled by default (controlled by "Only Cull Disconnected Terminals" setting). When a terminal tab is open, it maintains a WebSocket connection and the terminal is kept. Once the tab is closed or disconnected, the terminal becomes eligible for culling one full idle timeout later. None of this protection lasts past the terminal maximum idle ("Terminal Maximum Idle", 7 days by default): a terminal with no input or output for that long is culled even with an open tab or a workspace reference. A terminal counts as culled only once the server has actually removed it: a terminal whose shell has exited but whose pty is still held open by a surviving process is closed the way an end-of-file would have closed it, and a terminal that survives a cull anyway is attempted once and then left alone.

Workspaces: Based on the workspace file's last_modified timestamp. Every workspace except the default one is culled once idle past the workspace timeout: the auto-named workspaces (auto-0, auto-k, etc.) JupyterLab creates when you open multiple windows, and named workspaces you saved yourself. Culling a workspace releases the terminals it referenced, so they can be culled in the same pass (the cascade).

Note: Terminal culling signals the terminal's own shell, starting with SIGHUP and escalating through SIGINT and SIGTERM to SIGKILL if it does not exit. Processes started with nohup, screen or tmux are detached from that shell and survive culling.

Installation

Requires JupyterLab 4.6.0 or higher.

pip install jupyterlab-kernel-terminal-workspace-culler-extension

Configuration

Open JupyterLab Settings (Settings -> Settings Editor) and search for "Resource Culler" to adjust timeouts and enable/disable culling for each resource type.

Logs

Culling actions are logged at INFO level with [Culler] prefix:

[Culler] CULLING KERNEL abc123 - idle 65.2 minutes (threshold: 60)
[Culler] Kernel abc123 culled successfully
[Culler] CULLING TERMINAL 1 - idle 62.1 minutes (threshold: 60)
[Culler] Terminal 1 culled successfully

Run JupyterLab with --log-level=INFO to see culling activity.

FAQ

Q: My long-running calculation was killed. How do I prevent this?

Two options:

  1. Increase timeout: Go to Settings -> Settings Editor -> Resource Culler and increase the kernel/terminal timeout; for a terminal that stays open in a tab, increase "Terminal Maximum Idle"
  2. Use a terminal multiplexer: Run calculations inside screen or tmux - these survive terminal culling
# Using screen
screen -S mysession
python long_calculation.py
# Detach with Ctrl+A, D

# Using tmux
tmux new -s mysession
python long_calculation.py
# Detach with Ctrl+B, D

Q: Will closing my browser tab kill my running process?

For terminals: By default a terminal with an open browser tab is kept until it has had no input or output for the terminal maximum idle (7 days by default), even while a command runs; after the tab closes, it is culled once the idle timeout expires unless a workspace still references it; closing the browser tab leaves the terminal in the saved workspace, which keeps it until that workspace is culled or the terminal maximum idle passes. Foreground processes receive SIGHUP. Use nohup, screen, or tmux for processes that must survive.

For kernels: The kernel continues running. Activity is tracked server-side, so a busy kernel won't be culled even if the browser is closed.

Q: What happens to processes started with nohup?

They survive terminal culling. nohup makes processes ignore SIGHUP, which is the signal sent when a terminal closes.

Q: How do I disable culling entirely?

Go to Settings -> Settings Editor -> Resource Culler and uncheck "Enable Kernel Culling" and "Enable Terminal Culling".

Q: Can I see when resources were culled?

Yes. Run JupyterLab with --log-level=INFO to see [Culler] log messages. If you have jupyterlab-notifications installed, you'll also see toast notifications.

CLI

The extension includes a command-line tool for listing and culling resources from the terminal.

# Show help
jupyterlab_kernel_terminal_workspace_culler

# List all resources and their idle times
jupyterlab_kernel_terminal_workspace_culler list

# List as JSON
jupyterlab_kernel_terminal_workspace_culler list --json

# Show what would be culled (dry run)
jupyterlab_kernel_terminal_workspace_culler cull --dry-run

# Cull idle resources
jupyterlab_kernel_terminal_workspace_culler cull

# Cull and output as JSON
jupyterlab_kernel_terminal_workspace_culler cull --json

# Custom timeouts (minutes)
jupyterlab_kernel_terminal_workspace_culler cull --kernel-timeout 30 --terminal-timeout 120

# Cull workspaces idle > 1 minute (default is 7 days)
jupyterlab_kernel_terminal_workspace_culler cull --workspace-timeout 1

# Also cull terminals with an open browser tab or a workspace reference (default: skip them)
jupyterlab_kernel_terminal_workspace_culler cull --include-connected

By default cull skips terminals with an open browser tab or a workspace reference; unlike the extension, it does not apply the terminal maximum idle. Pass --include-connected to cull them anyway. A terminal is printed as culled only when the server removed it; one that is still registered afterwards is printed as failed. list marks the workspaces the server never culls as (protected).

The CLI auto-discovers running Jupyter servers. You can also set environment variables:

  • JUPYTER_SERVER_URL - server URL (e.g., http://localhost:8888/)
  • JUPYTER_TOKEN - authentication token

Agent skill

The package ships a skill that tells an AI assistant how to use the CLI: .agents/skills/jupyterlab-kernel-terminal-workspace-culler-extension/SKILL.md. pip install copies it to <sys.prefix>/share/jupyter/agents/skills/, a directory no assistant reads, so link it once.

# After pip install, with the Python that runs JupyterLab
mkdir -p ~/.agents/skills && ln -s "$(python -c 'import sys; print(sys.prefix)')/share/jupyter/agents/skills/jupyterlab-kernel-terminal-workspace-culler-extension" ~/.agents/skills/jupyterlab-kernel-terminal-workspace-culler-extension

# From a clone of this repository
ln -s "$PWD/.agents/skills/jupyterlab-kernel-terminal-workspace-culler-extension" ~/.claude/skills/jupyterlab-kernel-terminal-workspace-culler-extension

Uninstall

pip uninstall jupyterlab-kernel-terminal-workspace-culler-extension

Metadata

Release files for jupyterlab-kernel-terminal-workspace-culler-extension 1.0.32

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jupyterlab-kernel-terminal-workspace-culler-extension 1.0.32
File Size Uploaded Provenance Actions
jupyterlab_kernel_terminal_workspace_culler_extension-1.0.32.tar.gz 1.7 MB Without provenance Details for jupyterlab_kernel_terminal_workspace_culler_extension-1.0.32.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jupyterlab-kernel-terminal-workspace-culler-extension 1.0.32
File Interpreter ABI Platform Actions
jupyterlab_kernel_terminal_workspace_culler_extension-1.0.32-py3-none-any.whl Python 3 none any Details for jupyterlab_kernel_terminal_workspace_culler_extension-1.0.32-py3-none-any.whl

Total release size: 1.8 MB

Release files / jupyterlab_kernel_terminal_workspace_culler_extension-1.0.32.tar.gz

Download URL jupyterlab_kernel_terminal_workspace_culler_extension-1.0.32.tar.gz
Size 1.7 MB
Tags Source
SHA-256 checksum
How to use checksums
386f9354df48d52d026807996f767252b4297c9b292dfb5b40594420e88ecf3a
BLAKE2b-256 checksum
How to use checksums
056cc10d8425183635626c607281aa0f1f58533cae002ce5499e7f236b542384
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / jupyterlab_kernel_terminal_workspace_culler_extension-1.0.32-py3-none-any.whl

Download URL jupyterlab_kernel_terminal_workspace_culler_extension-1.0.32-py3-none-any.whl
Size 75.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
257757a518ff1900df7de3fd50ac11771ce2eb514b2fc4710fc51230fab615a6
BLAKE2b-256 checksum
How to use checksums
0ca74fc66e9e6aaeaf9dc5489b9f89bd38b2fbea607908096f76ea270b35ec59
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Security for jupyterlab-kernel-terminal-workspace-culler-extension 1.0.32

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page