/marimo

name: marimo
description: >-
  Reactive Python notebook system. Cell reactivity, UI elements (sliders, dropdowns, tables), SQL cells, plotting, app deployment. Use when assembling Stage 9 notebooks, building data apps, or converting Jupyter to marimo .py format.
metadata:
  audience: research-coders
  domain: python-library
  library-version: "0.19.x"
  skill-last-updated: "2026-03-28"

marimo

marimo reactive Python notebook system for reproducible and interactive data work. Covers cell reactivity model, UI elements (sliders, dropdowns, tables, forms), SQL cells, DataFrame display, plotting integration, validation patterns for data pipelines, and deployment as apps, scripts, or WASM. Use when assembling Stage 9 research notebooks, developing reactive marimo notebooks, building interactive data apps, or converting Jupyter notebooks to marimo's Git-friendly .py format.

Comprehensive skill for building reactive Python notebooks with marimo. Use decision trees below to find the right guidance, then load detailed references.

What is Marimo?

marimo is an open-source **reactive Python notebook** that automatically keeps code and outputs consistent:

• **Reactive**: Run a cell, and dependent cells automatically re-run
• **No hidden state**: Delete a cell, its variables are scrubbed from memory
• **Pure Python**: Notebooks stored as `.py` files (Git-friendly)
• **Interactive**: UI elements sync with Python without callbacks
• **Deployable**: Run as scripts, deploy as web apps, export to WASM

How to Use This Skill

Reference File Structure

Each topic in `./references/` contains focused documentation:

| File | Purpose | When to Read | |------|---------|--------------| | `quickstart.md` | Installation, CLI, first notebook | Starting a new project | | `reactivity.md` | Cell execution model, dataflow | Understanding marimo's reactive model | | `validation-patterns.md` | Transform-validate patterns, checkpoints | **REQUIRED for data analysis workflows** | | `ui-elements.md` | Interactive elements (mo.ui.*) | Adding interactivity | | `sql-data.md` | SQL cells, dataframes, plotting | Working with data | | `outputs-layouts.md` | Markdown, layouts, formatting | Styling outputs | | `apps-deployment.md` | Apps, scripts, export, deploy | Sharing/deploying notebooks | | `gotchas.md` | Common errors, best practices | Debugging issues |

Reading Order

1. **New to marimo?** Start with `quickstart.md` then `reactivity.md` 2. **Data analysis workflows?** Read `validation-patterns.md` (REQUIRED for rigorous analysis) 3. **Building features?** Read the relevant topic file 4. **Having issues?** Check `gotchas.md` first

Related Skills

Load these skills together with marimo for comprehensive workflow support:

**Always Load Together:**

• `data-scientist` - Provides validation methodology and EDA principles that inform notebook structure
• `polars` - DataFrame operations for data transformations within notebooks

**Load for Specific Features:**

• `plotnine` - Static publication-quality plots (ggplot2 style)
• `plotly` - Interactive visualizations with hover/zoom

**Prerequisite Knowledge:** If new to marimo, first understand: 1. Python basics 2. DataFrame operations (polars or pandas) 3. Basic plotting concepts

---

CRITICAL: Stage 9 is Script COMPILATION, Not Dashboard Building

**For data research workflows**, the Stage 9 marimo notebook has ONE job: **LITERALLY COPY script file contents into cells.**

What Stage 9 IS

• **A script viewer** — Copy-paste scripts into marimo cells
• **An audit tool** — Display execution logs to prove what ran
• **A file compiler** — Read files, copy contents, format as notebook

What Stage 9 is NOT

• ❌ NOT a dashboard builder
• ❌ NOT an interactive analysis tool
• ❌ NOT a place for new aggregations or filters
• ❌ NOT a place for UI widgets (dropdowns, sliders, search)

Stage 9 Notebook Assembly

Stage 9 is handled by the **notebook-assembler agent** (see `.claude/agents/notebook-assembler.md`), which: 1. READS script files from `scripts/stage{5,6,7,8}_*/` 2. COPIES script code VERBATIM into code cells 3. COPIES execution logs VERBATIM into accordion cells 4. ADDS ONLY simple `pl.read_parquet() + mo.ui.table()` cells

ABSOLUTE PROHIBITIONS for Stage 9

The following are **NEVER ALLOWED** in Stage 9 notebooks:

| Prohibited Element | Why | |-------------------|-----| | `mo.ui.dropdown()` | No dropdowns — not a dashboard | | `mo.ui.slider()` | No sliders — not a dashboard | | `mo.ui.multiselect()` | No multiselects — not a dashboard | | `mo.ui.text()` for search | No search boxes — not a dashboard | | `.group_by()` (new) | No new aggregations — copy script code only | | `.agg()` (new) | No new aggregations — copy script code only | | `.pivot()` (new) | No pivot tables — copy script code only | | `.filter()` in data cells | No filtering — just load and display | | `.with_columns()` in data cells | No transforms — just load and display | | "Interactive Filters" section | Not a dashboard | | "Data Explorer" section | Not a dashboard | | "Institution Lookup" feature | Not a dashboard |

The ONLY New Code Allowed

Data inspection cells may contain ONLY these two lines:

df = pl.read_parquet("path/to/file.parquet")
mo.ui.table(df.head(100))

No `.filter()`. No `.with_columns()`. No `.select()`. No aggregations. Just load and display.

Anti-Patterns (What BAD Output Looks Like)

# ❌ WRONG — This is new analysis code
tier_summary = risk_data.group_by("tier").agg(pl.len())

# ❌ WRONG — This is a dashboard widget
sector_dropdown = mo.ui.dropdown(options=["Public", "Private"])

# ❌ WRONG — This is a transformation when loading
df = pl.read_parquet("data.parquet").with_columns(pl.col("x") * 2)

# ❌ WRONG — This is filtering
filtered = df.filter(pl.col("state") == "VA")

# ✅ CORRECT — Verbatim script code in code cell
# SOURCE: scripts/stage5_fetch/01_fetch.py
import polars as pl
def _():
    # ... exac