Seamlessly integrate marimo notebooks into JupyterLab and JupyterHub

---

marimo-jupyter-extension brings the power of marimo reactive notebooks to your existing Jupyter infrastructure. Launch marimo directly from JupyterLab's launcher, manage running sessions, and convert Jupyter notebooks to marimo format.

Highlights

• 🚀 Launcher Integration - marimo appears in the JupyterLab launcher with its own icon
• 🍃 First-Class Marimo Notebook Support - Double-click _mo.py files to open directly in marimo
• 📊 Sidebar Panel - Monitor server status, view running sessions, and quick actions
• 🐍 Venv Selection - Choose or change a notebook's Python environment (with PEP 723 metadata)
• 📁 Context Menus - Right-click .py files to edit with marimo, .ipynb files to convert
• 🏢 JupyterHub Compatible - Works with existing authenticators and spawners
• 🔒 Secure - Token-based authentication between proxy and marimo
• 📦 Sandbox Mode - Run marimo in isolated environments with uvx

Quick Start

uv pip install 'marimo[sandbox]>=0.23.14' marimo-jupyter-extension

Launch JupyterLab and click the marimo icon in the launcher, or use the sidebar panel.

Features

Launcher & Sidebar

Create new marimo notebooks from the launcher. The sidebar shows server status, clickable running sessions with separate shutdown buttons, and quick actions.

Joy Division-style plot from pulsar CP 1919 (PSR B1919+21) made with wigglystuff

Environment Selection

When creating a new notebook, select from available Python environments. The extension discovers Jupyter kernel specs and embeds the venv path using PEP 723 script metadata. To switch an existing notebook, right-click its .py file and choose Change Python Environment. If the notebook is running, the extension asks before restarting its session.

File Type Handling

Context Menu Actions

• Edit with marimo: Right-click any .py or _mo.py file to open it in the marimo editor
• Convert to marimo: Right-click any .ipynb file to convert it to marimo format

Tab Restoration

Saved marimo notebooks and live unsaved notebooks are reopened when the JupyterLab page reloads. Unsaved notebooks reconnect to their existing marimo session. If that session has ended, the stale tab is discarded.

Installation

See Installation Guide for detailed setup instructions.

Single Environment

uv pip install 'marimo[sandbox]>=0.23.14' marimo-jupyter-extension

Multiple Environments (JupyterHub)

Configuration

Configure in jupyterhub_config.py:

# Explicit marimo path
c.MarimoProxyConfig.marimo_path = "/opt/bin/marimo"

# Or use uvx mode (sandbox)
c.MarimoProxyConfig.uvx_path = "/usr/local/bin/uvx"

# Startup timeout (default: 60s)
c.MarimoProxyConfig.timeout = 120

# Enable marimo debug logging for spawn troubleshooting
c.MarimoProxyConfig.debug = True

# Watch files for external edits (Claude Code, Cursor, vim, etc.)
c.MarimoProxyConfig.watch = True

# Allowed CORS origins (default: same-origin only)
c.MarimoProxyConfig.allow_origins = ["*"]

# Suppress version-check network call on startup
c.MarimoProxyConfig.skip_update_check = True

# Shut down after N minutes of no browser connection
c.MarimoProxyConfig.idle_timeout = 30.0

# Keep sessions alive N seconds after websocket disconnect
c.MarimoProxyConfig.session_ttl = 300

See Configuration Guide, Troubleshooting Guide, and JupyterHub Deployment for more details.

Migrating from jupyter-marimo-proxy

pip uninstall jupyter-marimo-proxy
pip install marimo-jupyter-extension

Configuration via c.MarimoProxyConfig in jupyterhub_config.py remains the same. This package is a drop-in replacement with additional features.

Attribution

This project is based on jupyter-marimo-proxy by Jiang Yio, which provided the original server proxy implementation.

Additional inspiration from b-data/jupyter-marimo-proxy.

This fork adds:

• Full JupyterLab extension with sidebar UI
• Venv/kernel selection with PEP 723 metadata
• Context menu integration for file operations
• Notebook conversion support
• Server restart capabilities

Troubleshooting

See Troubleshooting Guide for common issues.

Community

• marimo Discord - Chat with the community
• GitHub Issues - Report bugs or request features
• marimo Documentation - Learn about marimo notebooks
• Contributing Guidelines - Help improve marimo

License

Apache License 2.0 - see LICENSE and NOTICE for details.