marimo-development

name

marimo-development

description

Expert guidance for creating and working with marimo notebooks - reactive Python notebooks that can be executed as scripts and deployed as apps. Use when the user asks to create marimo notebooks, convert Jupyter notebooks to marimo, build interactive dashboards or data apps with marimo, work with marimo's reactive programming model, debug marimo notebooks, or needs help with marimo-specific features (cells, UI elements, reactivity, SQL integration, deploying apps, etc.).

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.