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 Python environment when creating new notebooks (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.4' 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, running sessions with kill 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.

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

Installation

See Installation Guide for detailed setup instructions.

Single Environment

uv pip install 'marimo[sandbox]>=0.23.4' 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.4

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.