armandli/marimo-notebook

Notes for marimo Notebooks

Running Marimo Notebooks

# Run as script (non-interactive, for testing)
uv run <notebook.py>

# Run interactively in browser
uv run marimo run <notebook.py>

# Edit interactively
uv run marimo edit <notebook.py>

Required: Setup Cell

Every marimo notebook MUST have a with app.setup: block immediately after app = marimo.App(...). Always import marimo as mo and typer in the setup cell:

app = marimo.App(width="medium")

with app.setup:
    import marimo as mo
    import typer

Add any other shared imports (numpy, polars, torch, etc.) to the setup cell as well.

Script Mode Detection

Use mo.app_meta().mode == "script" in a dedicated cell:

@app.cell
def _(mo):
    is_script_mode = mo.app_meta().mode == "script"
    return (is_script_mode,)

Key Principle: Show UI Always

Always create and show widgets. Only change the data source in script mode.

• Sliders, buttons, widgets should always be created and displayed
• In script mode, use synthetic/default data instead of waiting for user input
• Don't wrap everything in if not is_script_mode conditionals

Good Pattern

# Always show the widget
@app.cell
def _(mo):
    scatter_widget = mo.ui.anywidget(ScatterWidget())
    scatter_widget
    return (scatter_widget,)

# Only change data source based on mode
@app.cell
def _(is_script_mode, scatter_widget):
    if is_script_mode:
        X, y = make_moons(n_samples=200, noise=0.2)
    else:
        X, y = scatter_widget.widget.data_as_X_y
    return X, y

# Always show sliders - use .value in both modes
@app.cell
def _(mo):
    lr_slider = mo.ui.slider(start=0.001, stop=0.1, value=0.01)
    lr_slider
    return (lr_slider,)

Don't Guard Cells with if Statements

Marimo's reactivity means cells only run when their dependencies are ready:

# BAD - the if statement prevents the chart from showing
@app.cell
def _(plt, training_results):
    if training_results:  # WRONG
        fig, ax = plt.subplots()
        ax.plot(training_results['losses'])
        fig
    return

# GOOD - let marimo handle the dependency
@app.cell
def _(plt, training_results):
    fig, ax = plt.subplots()
    ax.plot(training_results['losses'])
    fig
    return

Don't Use try/except for Control Flow

# BAD - hiding errors behind try/except
@app.cell
def _(scatter_widget):
    try:
        X, y = scatter_widget.widget.data_as_X_y
    except Exception as e:
        return None, None

# GOOD - let it fail if something is wrong
@app.cell
def _(scatter_widget):
    X, y = scatter_widget.widget.data_as_X_y
    return X, y

Only use try/except for specific, expected exceptions with meaningful recovery.

Cell Output Rendering

Marimo only renders the final expression of a cell:

# BAD - indented expression won't render
@app.cell
def _(mo, condition):
    if condition:
        mo.md("This won't show!")  # WRONG - indented
    return

# GOOD - final expression renders
@app.cell
def _(mo, condition):
    result = mo.md("Shown!") if condition else mo.md("Also shown!")
    result
    return

Marimo Variable Naming

Use underscore prefix for loop variables to make them cell-private:

for _name, _model in items:
    ...

PEP 723 Dependencies

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "marimo",
#     "typer",
#     "torch>=2.0.0",
# ]
# ///

Always add typer when using CLI arguments.

Prefer pathlib over os.path

# GOOD
from pathlib import Path
data_dir = Path(tempfile.mkdtemp())
parquet_file = data_dir / "data.parquet"

# BAD
import os
parquet_file = os.path.join(temp_dir, "data.parquet")

marimo check

Run before delivering any notebook:

uvx marimo check <notebook.py>

API Docs (Local)

uv --with marimo run python -c "import marimo as mo; help(mo.ui.form)"

Typer CLI Arguments

Notebooks can accept --flags when run as uv run notebook.py using Typer. Use a module-level _cli_args dict to pass values from the CLI into cells. See references/TYPER.md for the full integration pattern and template.

Testing with pytest

Cells whose function names start with test_ are discovered as pytest tests. Cell arguments inject other cells' return values as test inputs:

pytest notebook.py        # run all tests
pytest notebook.py -v     # verbose

See references/PYTEST.md for fixtures, parametrize, and class-based test patterns.

Working with Polars

Import polars as pl in the setup cell. Marimo renders DataFrames natively — drop a DataFrame as the final cell expression, or use:

• mo.ui.table(df) — interactive table with row selection
• mo.ui.dataframe(df) — no-code filter/groupby GUI
• mo.ui.data_explorer(df) — column statistics and chart builder

See references/POLARS.md for the full API.

Charting with Altair

Import altair as alt in the setup cell. Wrap charts with mo.ui.altair_chart(chart) for reactivity — .value returns selected data as a DataFrame. See references/ALTAIR.md for chart types and composition.

NumPy Arrays

Import numpy as np in the setup cell. Use for numerical computation, array math, and linear algebra. See references/NUMPY.md for the full API.

SciPy Scientific Computing

Import from scipy submodules in the setup cell (e.g., from scipy import stats, optimize). Use for statistics, optimization, signal processing, and integration. See references/SCIPY.md for the full API.

PyTorch Neural Networks

Import torch and torch.nn in the setup cell. Define models with nn.Module, train with autograd. See references/PYTORCH.md for the full API.

Additional Resources

• SQL.md — SQL in marimo with DuckDB, SQLAlchemy, DuckDB connections
• UI.md — marimo UI component reference
• TOP-LEVEL-IMPORTS.md — exposing functions/classes as top-level imports
• TYPER.md — Typer CLI argument integration
• PYTEST.md — pytest testing in marimo notebooks
• POLARS.md — Polars DataFrame guide
• ALTAIR.md — Altair charting guide
• NUMPY.md — NumPy array computing reference
• SCIPY.md — SciPy scientific computing reference
• PYTORCH.md — PyTorch neural network reference

---

Final Step — Record Usage

After the skill's primary task completes, run:

python3 ${PWD}/.claude/skills/skill-stat/scripts/record-stat.py "marimo-notebook"