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

File Type	Double-click Behavior	"Open With" Menu
_mo.py	Opens in marimo	marimo available
.py	Opens in standard editor	marimo available

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)

Package	Install Location	Why
marimo	User's environment	Access user's packages
marimo-jupyter-extension	Jupyter's environment	Jupyter must import it

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.

Issue	Solution
marimo icon missing	Install marimo-jupyter-extension in Jupyter's environment
marimo fails to launch	Ensure marimo is in PATH or configure MarimoProxyConfig.marimo_path
Modules not found	Install marimo in the same environment as your packages
Sandbox features not working	Upgrade to marimo[sandbox]>=0.23.14

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.