Overview

Relevant source files

Purpose and Scope

This page provides a system-level overview of marimo, a reactive Python notebook system. It describes marimo's architecture, execution model, file format, and key subsystems. This overview targets developers who want to understand how marimo works internally or contribute to the project.

For detailed information about specific subsystems:

Core concepts and public API: see #1.1
Reactive execution model: see #1.2
Detailed architecture breakdown: see #1.3
Project structure and build system: see #1.4

What is marimo

marimo is a reactive Python notebook that stores notebooks as pure .py files instead of JSON. Unlike traditional notebooks such as Jupyter, marimo automatically tracks dependencies between cells and re-executes dependent cells when their inputs change, eliminating hidden state and ensuring reproducibility.

A marimo notebook can be:

Edited interactively with marimo edit — a development environment with reactive execution
Run as an app with marimo run — a read-only web interface with Python code hidden
Executed as a script with python notebook.py — standard Python script execution
Run in the browser — WASM-based execution via Pyodide with no server required

Sources: README.md38-53 docs/index.md16-23 docs/faq.md10-29

File Format

marimo notebooks are stored as pure Python files (.py), not JSON. Each notebook is a standard Python module that defines an App and registers cells using decorators:

This format enables:

Git-friendly version control (line-by-line diffs)
Direct script execution (python notebook.py)
Import of notebook functions/classes into other Python files
Standard Python tooling (linters, formatters, type checkers)

The marimo runtime parses these files to extract cell code and build the dependency graph based on variable references and definitions.

Sources: docs/faq.md27-29 docs/guides/coming_from/jupyter.md132-159 README.md40-41

System Architecture

Sources: marimo/__init__.py1-155 marimo/_pyodide/pyodide_session.py110-221

Core Components

Public API

The marimo module exposes the public API through marimo/__init__.py. Key exports include:

Component	Purpose
`App`	Defines a notebook application
`Cell`	Decorator for registering cells
`ui` namespace	Interactive UI elements (`mo.ui.slider`, `mo.ui.table`, etc.)
`md()`	Markdown rendering with interpolation
`sql()`	SQL cell execution
`state()`	Mutable reactive state
`stop()`	Conditional execution control

Sources: marimo/__init__.py17-91

Cell and App Model

Each CellImpl stores:

code: Compiled bytecode
defs: Global variables defined by the cell
refs: Global variables referenced by the cell
config: Cell-specific settings (disabled, hide_code, etc.)

The InternalApp maintains the cell registry and constructs the execution graph.

Sources: marimo/_ast/app.py marimo/_ast/cell.py

Reactive Runtime

The reactive execution engine is implemented in Kernel class:

Key classes:

Class	Location	Purpose
`Kernel`	`marimo/_runtime/runtime.py`	Orchestrates cell execution and manages state
`DirectedGraph`	`marimo/_ast/cell.py`	DAG of cell dependencies
`Runner`	`marimo/_runtime/runner/cell_runner.py`	Executes cells and captures output
`ScopedVisitor`	`marimo/_ast/visitor.py`	AST analysis for refs/defs extraction

Sources: docs/guides/reactivity.md31-55 README.md67-86

Session Modes

marimo supports two primary session modes defined in SessionMode enum:

EDIT mode (marimo edit):

Full code editor with syntax highlighting
Interactive cell execution
Variable explorer and debugger
AI assistance and copilot integration

RUN mode (marimo run):

Code cells are hidden (only outputs visible)
Read-only interface
UI elements remain interactive
Designed for end-user applications

Sources: marimo/_session/model.py docs/faq.md114-135

Execution Environments

Environment Selection Matrix

Isolation modes defined in marimo/_runtime/packages/package_managers.py:

Mode	Implementation	Use Case
`NONE`	Native Python interpreter	Local development
`SINGLE`	`uv run` wrapper process	Single notebook with PEP 723 metadata
`MULTI`	IPC kernel with per-notebook venvs	Home page with multiple notebooks
`DOCKER`	Container-based execution	Untrusted remote notebooks
`PYODIDE`	WASM in browser	No server required

Sources: marimo/_runtime/packages/package_managers.py docs/guides/package_management/inlining_dependencies.md

Pyodide (WASM) Architecture

PyodideSession provides a browser-compatible kernel implementation that:

Runs entirely in the browser via WebAssembly
Uses micropip for package installation
Implements the same Kernel interface as server-side execution
Communicates via async queues instead of WebSockets

Sources: marimo/_pyodide/pyodide_session.py110-221 tests/_pyodide/test_pyodide_session.py115-170

Frontend Architecture

The frontend is built with:

React for UI components
TypeScript for type safety
Jotai for reactive state management
CodeMirror 6 for code editing
Vite for building and development

State flows unidirectionally: WebSocket messages update atoms, atoms trigger component re-renders, user actions send commands back through WebSocket.

Sources: frontend/tsconfig.json1-40 docs/guides/index.md22

Data Flow Example

Sources: marimo/_runtime/runtime.py docs/guides/reactivity.md31-55

Key Subsystems

UI Plugin System

All interactive UI elements inherit from UIElement base class:

UI elements are reactive: when a user interacts with a UI element bound to a global variable, all cells referencing that variable automatically re-run.

Sources: marimo/__init__.py105 docs/guides/working_with_data/dataframes.md130-196

SQL Integration

marimo provides SQL cells via mo.sql():

Architecture:

Component	Purpose
`mo.sql()`	Entry point for SQL queries
DuckDB	Default SQL engine (in-memory)
Custom engines	SQLAlchemy, Ibis, SQLModel support
Connection UI	Visual database connection management

SQL cells are f-strings, allowing Python value interpolation. They support:

Local dataframe querying
Remote database connections (PostgreSQL, MySQL, SQLite, Snowflake, BigQuery)
File sources (CSV, Parquet, S3, HTTP endpoints)
Multiple output formats (native, pandas, polars, lazy)

Sources: docs/guides/working_with_data/sql.md1-415 marimo/_sql/sql.py

AI Integration

marimo includes AI features for code generation:

AI providers implement a common PydanticProvider interface supporting streaming responses and tool invocation.

Sources: marimo/_ai/ docs/guides/editor_features/ai_completion.md

Package Management

PEP 723 Support: marimo can inline package requirements in notebook files using PEP 723 script metadata:

When running with --sandbox, marimo automatically creates an isolated virtual environment and installs dependencies.

Sources: tests/_runtime/test_manage_script_metadata.py38-200 docs/guides/package_management/inlining_dependencies.md docs/guides/editor_features/package_management.md1-21

Technology Stack

Backend

Technology	Purpose
Python 3.8+	Core language
Starlette	ASGI web framework
Uvicorn	ASGI server
Click	CLI framework
msgspec	Fast JSON serialization
Ruff	Linting and formatting

Frontend

Technology	Purpose
React 18	UI framework
TypeScript	Type-safe JavaScript
Vite	Build tool and dev server
Jotai	State management
CodeMirror 6	Code editor
Tanstack Query	Data fetching
pnpm	Package manager
Turbo	Monorepo build orchestration

Sources: frontend/tsconfig.json1-40 README.md137-141

Summary

marimo is a comprehensive reactive notebook system with:

Pure Python storage format for Git-friendly version control
Reactive execution model via static dependency analysis
Multiple execution modes (edit, run, script, WASM)
Extensible plugin architecture for UI elements, SQL, and AI
Modern tech stack (React/TypeScript frontend, Python/Starlette backend)
Four execution environments (native, sandboxed venv, Docker, Pyodide)

The system prioritizes reproducibility, developer experience, and seamless transition between development and deployment contexts.