marimo-development

Create reactive Python notebooks with marimo's interactive programming environment.

Core Workflow

1. Start with fundamentals: Read references/core-concepts.md - contains marimo's cell structure, reactivity model, UI elements, and essential examples
2. Use recipes for common tasks: Check references/recipes.md for code snippets
3. Refer to API docs: Navigate references/api/ for specific function details
4. Troubleshoot issues: See references/faq.md and references/troubleshooting.md

Key Marimo Concepts

Cell Structure

Every marimo cell follows this structure:

@app.cell
def _():
    # Your code here
    return

When editing cells, only modify the code inside the function - marimo handles parameters and returns automatically.

Reactivity Rules

1. Automatic execution: When a variable changes, cells using it automatically re-run
2. No redeclaration: Variables cannot be redeclared across cells
3. DAG structure: Cells form a directed acyclic graph (no circular dependencies)
4. Last expression displays: The final expression in a cell is automatically shown
5. UI reactivity: UI element values accessed via .value trigger automatic updates
6. Local variables: Variables prefixed with _ (e.g., _temp) are local to the cell

Import Pattern

Always import marimo in the first cell:

@app.cell
def _():
    import marimo as mo
    # other imports
    return

Common Tasks

Creating Interactive UIs

# Create UI element in one cell
@app.cell
def _():
    slider = mo.ui.slider(0, 100, value=50, label="Value")
    slider
    return

# Use its value in another cell
@app.cell
def _():
    result = slider.value * 2
    mo.md(f"Double the value: {result}")
    return

Working with Data

# Load and display data
@app.cell
def _():
    import polars as pl
    df = pl.read_csv("data.csv")
    df  # Automatically displays as table
    return

# Interactive data exploration
@app.cell
def _():
    mo.ui.data_explorer(df)
    return

SQL with DuckDB

@app.cell
def _():
    # marimo has built-in DuckDB support
    result = mo.sql(f"""
        SELECT * FROM df WHERE column > 100
    """)
    return

Layouts

@app.cell
def _():
    # Horizontal stack
    mo.hstack([element1, element2, element3])

    # Vertical stack
    mo.vstack([top, middle, bottom])

    # Tabs
    mo.tabs({"Tab 1": content1, "Tab 2": content2})
    return

Visualization Best Practices

• matplotlib: Use plt.gca() as last expression (not plt.show())
• plotly: Return the figure object directly
• altair: Return the chart object; add tooltips; accepts polars dataframes directly

Reference Documentation

Use references/NAVIGATION.md to understand the complete documentation structure. Key references:

Essential Reading

• core-concepts.md - Start here for fundamentals and examples
• recipes.md - Code snippets for common tasks

Detailed Guides

• reactivity.md - Deep dive into reactive execution
• interactivity.md - Building interactive UIs
• best_practices.md - Coding standards for marimo

Working with Data

• working_with_data/sql.md - SQL and DuckDB integration
• working_with_data/dataframes.md - pandas, polars, etc.
• working_with_data/plotting.md - Visualization libraries

Deployment

• apps.md - Deploy as interactive web apps
• scripts.md - Run as Python scripts with CLI args

API Reference

• api/inputs/ - All UI elements (slider, dropdown, button, table, etc.)
• api/layouts/ - Layout components (tabs, accordion, sidebar, etc.)
• api/control_flow.md - Cell execution control
• api/state.md - State management
• api/caching.md - Performance optimization

Troubleshooting

• faq.md - Common questions and solutions
• troubleshooting.md - Error fixes
• debugging.md - Debugging techniques

Common Pitfalls

1. Circular dependencies: Reorganize code to remove cycles
2. UI value access: Can't access .value in the same cell where UI element is defined
3. Variable redeclaration: Each variable can only be defined once across all cells
4. Visualization not showing: Ensure visualization object is the last expression
5. Global keyword: Never use global - violates marimo's execution model

After Creating a Notebook

Run marimo check --fix to automatically catch and fix common formatting issues and detect pitfalls.

Quick Reference: Most Used UI Elements

mo.ui.slider(start, stop, value=None, label=None)
mo.ui.dropdown(options, value=None, label=None)
mo.ui.text(value='', label=None)
mo.ui.button(value=None, kind='primary')
mo.ui.checkbox(label='', value=False)
mo.ui.table(data, sortable=True, filterable=True)
mo.ui.data_explorer(df)  # Interactive dataframe explorer
mo.ui.dataframe(df)  # Editable dataframe
mo.ui.form(element, label='')  # Wrap elements in a form
mo.ui.array(elements)  # Array of UI elements

See references/api/inputs/index.md for the complete list.

Quick Reference: Layout Functions

mo.md(text)  # Display markdown
mo.hstack(elements)  # Horizontal layout
mo.vstack(elements)  # Vertical layout
mo.tabs(dict)  # Tabbed interface
mo.stop(predicate, output=None)  # Conditional execution
mo.output.append(value)  # Append to output
mo.output.replace(value)  # Replace output

See references/api/layouts/index.md for all layout options.