How to Get Started with Marimo Notebook

Marimo is a reactive Python notebook where changing any cell automatically re-runs everything that depends on it. The result is a notebook that always stays in a consistent state, with no stale outputs. Marimo notebooks are stored as pure Python .py files, which means they work naturally with Git, can be run as standalone scripts, and can be deployed as web apps. This guide walks through installation, your first notebook, and the key features that make marimo worth using.

Why Marimo Is Different from Jupyter

Standard Jupyter notebooks are stateful by design. You can run cells in any order, which creates a persistent problem: cells earlier in the notebook may rely on state set by cells you ran later. This leads to bugs that are hard to reproduce and notebooks that only work correctly if you re-run them top to bottom.

Marimo eliminates this by modeling the notebook as a dataflow graph. Each cell can only reference variables defined in other cells. If cell B depends on a variable defined in cell A, marimo re-runs cell B whenever cell A changes. The dependency graph is computed automatically from your code, not enforced by running order.

As of April 2026, marimo has passed 20,000 GitHub stars and 3,600 members in its Discord community, driven largely by growing frustration with Jupyter's reproducibility limitations among analysts and researchers.

Installation

Install marimo with pip or uv:

pip install marimo

For full features including SQL cells, AI completion, and server-side dataframe profiling, install the recommended extras:

pip install 'marimo[recommended]'

You can also install via conda:

conda install -c conda-forge marimo

Verify the install with:

marimo --version

Creating Your First Notebook

Start the marimo editor from your terminal:

marimo edit

This opens a browser-based notebook editor at http://localhost:2718. To create a named notebook:

marimo edit my_analysis.py

The notebook is saved as a standard Python file, not a JSON blob. You can open it in any text editor, commit it to Git without merge conflicts, and import functions from it in other Python scripts. To get a feel for the reactive model, run the built-in intro tutorial:

marimo tutorial intro

How Reactivity Works

In marimo, each cell defines one or more variables and can reference variables from other cells. The notebook tracks which cells define which variables and which cells depend on which variables. This dependency graph is built from your code before any execution.

Concretely: if cell A sets sales_data = pd.read_csv("sales.csv") and cell B computes total = sales_data['revenue'].sum(), then editing cell A will immediately re-run cell B. You do not need to manually trigger this.

This also means you cannot have two cells that define the same variable. If two cells both define x, marimo shows an error. This constraint prevents the ambiguity that causes stale state in Jupyter.

Working with Dataframes

Marimo has first-class support for both pandas and polars dataframes. When you reference a dataframe in a cell, marimo renders it as a sortable, filterable table automatically.

import pandas as pd
import marimo as mo

df = pd.read_csv("sales.csv")
df  # renders as an interactive table

The mo.ui.dataframe() component adds filter controls directly above the table:

table = mo.ui.dataframe(df)
table

Any downstream cell that references table.value will receive the currently filtered dataframe and will re-run whenever the filter changes. This makes interactive exploratory analysis reproducible by construction.

SQL Cells

Marimo includes built-in SQL cells powered by DuckDB. To add a SQL cell, click the SQL button at the bottom of any cell. The result is returned as a Python variable, specifically a Polars dataframe if polars is installed, otherwise a pandas dataframe.

SQL cells are stored as pure Python under the hood using mo.sql(), so the notebook remains a valid .py file. They support f-string interpolation, which means you can build reactive SQL queries that depend on UI elements or Python values:

selected_region = mo.ui.dropdown(["North", "South", "East", "West"])
selected_region

Then in a SQL cell:

SELECT * FROM df WHERE region = '{selected_region.value}'

Changing the dropdown automatically re-runs the query. This pattern replaces the manual cell-re-running loop that most analysts use in Jupyter.

You can also connect to external databases. Marimo supports PostgreSQL, MySQL, SQLite, DuckDB, Snowflake, and BigQuery through a connection dialog built into the editor. No connection string boilerplate required.

UI Elements

Marimo ships with a set of UI components that integrate directly with the reactive system. Sliders, dropdowns, date pickers, file upload widgets, and text inputs are all available as mo.ui.* components:

threshold = mo.ui.slider(0, 100, value=50)
threshold

Any cell that references threshold.value will re-run when the slider moves. This makes it straightforward to build interactive data explorations where the notebook records the state of every UI element and re-runs correctly from top to bottom on a fresh open.

Running as a Script or App

Because marimo notebooks are stored as .py files, you can run them as standard Python scripts:

python my_analysis.py

You can also run them as interactive web apps without any server setup:

marimo run my_analysis.py

This launches a read-only app view where users interact with UI elements but cannot edit cells. It is a practical way to share a working analysis with non-technical stakeholders, without exporting to a static PDF or setting up a dashboard tool.

VS Code and Cursor Integration

Marimo has an official VS Code extension. Install it by searching "marimo" in the extensions marketplace, or add it directly to Cursor. The extension lets you edit and run marimo notebooks from your existing editor with the same reactivity and SQL features available in the browser-based editor. For teams already in VS Code, this removes the friction of switching to a separate tool.

What marimo Does Not Replace

Marimo is a strong fit for exploratory analysis, reproducible research, and lightweight interactive apps. It is not a replacement for a full BI tool when you need multi-user dashboards, role-based access, or a managed query layer. It also does not replace orchestration tools like Dagster or Prefect for scheduled production pipelines.

For analysts who want to go from a raw file to cleaned charts and statistical output in a single session without any setup, VSLZ AI handles that workflow from a file upload with no configuration needed.

Summary

Marimo is a practical upgrade to the standard notebook workflow. Install it with pip, open a notebook with marimo edit, and the reactive model handles dependency tracking automatically. The SQL cells, UI components, and .py storage format make it a better fit than Jupyter for analysis that needs to be shared, repeated, or extended by other people.