marimo

marimo is a next-generation Python notebook environment that solves the fundamental reproducibility problem of traditional notebooks like Jupyter. By statically analyzing cell code to build a directed acyclic dependency graph, marimo automatically re-executes only the cells affected by a change — and removes variables from scope when their defining cell is deleted, making hidden state impossible by design.

Notebooks are stored as plain Python files, making them diff-friendly for Git, importable as modules, executable as CLI scripts, and deployable as interactive web apps with a single command. SQL cells let you query dataframes, PostgreSQL, MySQL, DuckDB, SQLite, and CSVs directly in the notebook, with results returned as Python dataframes that feed back into the reactive graph.

marimo integrates natively with the AI tooling ecosystem: built-in AI code generation supports GitHub Copilot, custom API keys, and local LLMs, while the MCP server lets autonomous agent CLIs like Claude Code directly edit and execute cells. A content-addressed persistent caching system (mo.cache) speeds up expensive computations by invalidating based on input hashes rather than requiring manual cache management.

With over 21,000 GitHub stars, a release cadence of multiple versions per week, and adoption at institutions like SLAC National Accelerator Lab, marimo has established itself as a production-grade replacement for Jupyter that works the way developers expect Python to work.

What You Get

• Reactive DAG Execution - Cells automatically re-run when their upstream dependencies change, based on a directed acyclic graph derived from static analysis of variable references — no manual cell re-running required.
• SQL Cells with Python Integration - Write SQL queries that reference Python variables and execute them against DuckDB, PostgreSQL, MySQL, SQLite, CSVs, Google Sheets, or any DataFrame — results are returned as Python DataFrames that feed back into the reactive graph.
• Pure Python Storage - Notebooks are stored as .py files, not JSON blobs, enabling Git diffs, code reviews, pytest testing, and import of functions and classes from one notebook to another.
• Interactive UI Elements - Bind sliders, dropdowns, tables, chat interfaces, matplotlib plots, and matrix inputs to Python variables — values update reactively without callbacks or boilerplate.
• AI-Native Editing - Generate cells and entire notebooks with a built-in AI assistant, connect agent CLIs like Claude Code via MCP, or use marimo pair mode for collaborative AI-driven notebook editing.
• Deploy as Web App or WASM - Run marimo run notebook.py to serve a notebook as an interactive web application, or deploy to the browser via WebAssembly with no server required.
• Built-in Package Management - Install packages on import, serialize dependencies into notebook files using PEP 723 metadata, and auto-create isolated virtual environments with uv.
• Persistent Caching - mo.cache and mo.persistent_cache provide content-addressed caching that invalidates based on input hashes, avoiding redundant execution of expensive cells across sessions.
• MCP Server Integration - An experimental MCP (Model Context Protocol) server exposes notebook editing and execution tools to AI agents, enabling autonomous agentic workflows on live notebooks.
• Testable Notebooks - Run pytest directly on marimo notebooks to validate cell logic, outputs, and data transformations as part of CI/CD pipelines.

Common Use Cases

• Reproducible data science pipelines - A data scientist builds a notebook that ingests raw data via SQL, applies transformations in Python, and visualizes results — every colleague who opens the file gets identical outputs because there is no hidden kernel state to inherit.
• Interactive ML model dashboards - An ML engineer deploys a training analysis notebook as a web app where stakeholders can adjust hyperparameter sliders, see model metrics recompute reactively, and export results without touching any code.
• AI-assisted exploratory analysis - A data analyst connects Claude Code to marimo via MCP and asks it to write SQL queries and generate visualizations in natural language, with marimo’s reactive runtime keeping all downstream cells consistent after each AI-generated change.
• Collaborative research documentation - A scientific computing team at a national lab stores all experiment notebooks as .py files in Git, enabling code review of analysis logic, tracked history of result changes, and reuse of shared utility functions across notebooks.
• Self-contained deployable tools - A fintech team replaces a Streamlit dashboard with a marimo notebook that queries a live PostgreSQL database, runs in the browser via WASM for internal stakeholders, and is version-controlled alongside the rest of the codebase.
• Parameterized batch execution - A DevOps engineer runs marimo notebooks as CLI scripts with arguments (python notebook.py --param value), integrating them into scheduled data pipelines without any code modification.

Under The Hood

Architecture marimo’s architecture centers on a DirectedGraph coordinator that delegates to three specialized sub-systems: a MutableGraphTopology for node and edge storage, a DefinitionRegistry tracking which cells define which Python and SQL variables, and a CycleTracker that detects circular dependencies on every cell registration. This decomposition means each concern is independently testable and replaceable. The kernel runs in a separate process (using PyZMQ for IPC in sandbox mode) and communicates with a Starlette/Uvicorn ASGI server over WebSocket messages defined in _messaging — a clean RPC contract that decouples the execution layer from the UI layer entirely. The frontend is a React 19 SPA that subscribes to server events and re-renders affected components; it never calls the Python kernel directly, only through the message protocol. The Executor is a Protocol interface with both synchronous and async implementations, allowing the runtime to handle coroutine cells transparently.

Tech Stack The Python backend runs on Starlette and Uvicorn with Msgspec for high-performance binary serialization and Pydantic for validation. Narwhals provides a dataframe-agnostic abstraction layer that works with pandas, Polars, PyArrow, and other backends. SQL cells are powered by DuckDB with custom parsing that extracts Python variable references to weave them into the reactive dependency graph. The frontend is React 19 with TypeScript, built via Vite using a custom Rolldown fork, with CodeMirror 6 as the cell editor, DnD-Kit for drag-and-drop cell reordering, and TanStack Table for the high-performance dataframe viewer. End-to-end tests use Playwright, Python backend tests use pytest, and frontend unit tests use Vitest.

Code Quality The Python codebase contains well over 400 test files with extensive unit, integration, and regression coverage. Both Python and TypeScript codebases enforce strict typing — Python uses from __future__ import annotations throughout and relies on Protocol for interface contracts rather than abstract base classes. Ruff enforces formatting and linting on the Python side; ESLint and Prettier do the same for TypeScript. Error handling is deliberate: a MarimoRuntimeException wrapper strips internal marimo frames from tracebacks so users see errors starting at their own code. The CI pipeline runs type checking, linting, unit tests, and integration tests on every pull request.

What Makes It Unique marimo’s defining technical insight is deriving execution order from static AST analysis of variable definitions and references — not from cell position or manual tagging. This makes reproducibility a structural guarantee rather than a convention. The content-addressed mo.cache system computes input hashes to invalidate cached results only when inputs actually change, enabling persistent cross-session caching without user management. The MCP server (_mcp/) is one of the first native integrations that lets LLM agents read, edit, and execute notebook cells through a standardized protocol, making marimo a genuinely agentic development environment rather than a tool that just generates code snippets.

Self-Hosting

marimo is released under the Apache License 2.0, one of the most permissive open-source licenses available. You can use it commercially, modify the source code, distribute it, and sublicense it without restriction. There is no copyleft obligation — your proprietary notebooks and applications built on top of marimo do not need to be open-sourced. The only requirements are preserving copyright notices and the license file when distributing the software itself.

Self-hosting marimo is straightforward for a Python shop: it installs via pip or conda into any Python 3.10+ environment and runs as a local process with no external services required. Production deployments typically run marimo run behind a reverse proxy like nginx or Caddy. For multi-user environments, the ASGI app can be embedded in your own Starlette or FastAPI application using create_asgi_app(), giving you full control over authentication, routing, and session lifecycle. The operational burden is low for single-notebook deployments but increases for teams managing many notebooks, because marimo does not include built-in user management, scheduled execution, or centralized notebook storage — those concerns are left to surrounding infrastructure.

The marimo team offers molab (molab.marimo.io), a hosted cloud service for creating and sharing notebooks without local setup, which serves as the managed alternative. molab handles session persistence, sharing via URL, and browser-based WASM execution. Self-hosting gives you full data locality and network isolation (important for sensitive data), but you give up managed notebook galleries, built-in sharing URLs, and the collaborative cloud editing features that molab provides. Support is community-driven via Discord and GitHub Issues; there is no paid enterprise tier with SLAs or dedicated support as of the current release.