Skip to main content
marimo notebooks are reactive Python programs stored as .py files. This makes them easy to version control, diff, and integrate into your development workflow.

​
Creating a New Notebook

1

Start the editor

Create a new notebook with the marimo edit command:
marimo edit
If the file doesn’t exist, marimo will create an empty notebook. If it exists, marimo will open it for editing.
2

Open in browser

marimo will automatically launch your browser and open the notebook editor at http://localhost:2718.Use the --headless flag to prevent the browser from opening:
marimo edit notebook.py --headless
3

Add cells

Click the + button or press Ctrl/Cmd + K to add a new cell. Each cell can contain Python code that will execute reactively.

​
Notebook File Structure

marimo notebooks are pure Python files with a specific structure:
notebook.py
import marimo

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


@app.cell
def __():
    import marimo as mo
    import pandas as pd
    return mo, pd


@app.cell
def __(mo):
    mo.md("# Hello, marimo!")
    return


@app.cell
def __(pd):
    data = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
    return (data,)


if __name__ == "__main__":
    app.run()
Each cell is a Python function decorated with @app.cell. Variables are automatically tracked and cells re-execute when their dependencies change.

​
Understanding Cells

​
Cell Functions

Each cell is defined as a function: 
@app.cell
def __():
    x = 1
    y = 2
    return x, y
The function parameters (like __(mo, pd)) indicate which variables from other cells this cell depends on.

​
Variable Returns

Variables must be explicitly returned to be used by other cells: 
@app.cell
def __():
    data = [1, 2, 3]
    result = sum(data)
    return data, result  # Both available to other cells
Variables not included in the return statement are local to the cell and won’t be accessible elsewhere.

​
Anonymous Cells

Cells use __() as the function name by default. You can also name cells for better debugging: 
@app.cell
def load_data():
    import pandas as pd
    df = pd.read_csv("data.csv")
    return df, pd

​
Organizing Code

​
Markdown Cells

Use mo.md() to create formatted markdown content: 
@app.cell
def __(mo):
    mo.md(
        r"""
        # Data Analysis

        This notebook analyzes **sales data** from Q4 2024.

        Key metrics:
        - Revenue
        - Customer acquisition
        - Retention rates
        """
    )
    return

​
Code Organization

Follow these best practices:
  1. Import cells first: Place imports at the top
  2. One responsibility per cell: Keep cells focused on a single task
  3. Return only what’s needed: Don’t expose internal variables
  4. Use descriptive names: Name important cells for clarity
@app.cell
def __():
    import pandas as pd
    import numpy as np
    return pd, np

@app.cell
def __(pd):
    df = pd.read_csv("data.csv")
    return (df,)

@app.cell
def __(df):
    summary = df.describe()
    return (summary,)

​
Cell Configuration

​
Hide Code

Hide cell code while showing output: 
@app.cell(hide_code=True)
def __(mo):
    mo.md("# Welcome to My Analysis")
    return

​
Disable Automatic Execution

Prevent a cell from running automatically: 
@app.cell(disabled=True)
def __():
    # Expensive computation - run manually
    result = expensive_operation()
    return (result,)

​
Advanced: Script Metadata (PEP 723)

marimo notebooks can include dependency information using PEP 723 inline script metadata: 
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "marimo",
#     "pandas>=2.0.0",
#     "plotly",
# ]
# ///

import marimo

app = marimo.App()
# ...
When you use --sandbox mode, marimo automatically manages these dependencies. See Package Management for details.

​
Creating from Templates

​
AI-Generated Notebooks

Generate a notebook from a text prompt: 
marimo new "Create an interactive dashboard with sliders to filter a pandas DataFrame"

​
Tutorial Notebooks

Open built-in tutorials: 
marimo tutorial intro
marimo tutorial dataflow
marimo tutorial plots

​
Next Steps

Running Notebooks

Learn about different execution modes

Package Management

Manage dependencies in your notebooks

Build docs developers (and LLMs) love

Get started for freeTalk to us