marimo Documentation

File: README.md Copy Chapter

marimo is a reactive Python notebook: run a cell or interact with a UI
element, and marimo automatically runs dependent cells (or marks them as stale), keeping code and outputs
consistent. marimo notebooks are stored as pure Python (with first-class SQL support), executable as scripts,
and deployable as apps.

Highlights.

• 🚀 batteries-included: replaces jupyter, streamlit, jupytext, ipywidgets, papermill, and more
• ⚡️ reactive: run a cell, and marimo reactively runs all dependent cells or marks them as stale
• 🖐️ interactive: bind sliders, tables, plots, and more to Python — no callbacks required
• 🐍 git-friendly: stored as .py files
• 🛢️ designed for data: query dataframes, databases, warehouses, or lakehouses with SQL, filter and search dataframes
• 🤖 AI-native: pair with AI agents like Claude Code, or use our editor's built-in AI features
• 🔬 reproducible: no hidden state, deterministic execution, built-in package management
• 🏃 executable: execute as a Python script, parameterized by CLI args
• 🛜 shareable: deploy as an interactive web app or slides, run in the browser via WASM
• 🧩 reusable: import functions and classes from one notebook to another
• 🧪 testable: run pytest on notebooks
• ⌨️ a modern editor: GitHub Copilot, AI assistants, vim keybindings, variable explorer, and more
• 🧑‍💻 use your favorite editor: run in VS Code/Cursor or PyCharm, or edit in neovim, Zed, or any other text editor

pip install marimo && marimo tutorial intro

Get started instantly with molab, our free online
notebook. Or jump to the
quickstart for a primer on our CLI.

A reactive programming environment Copy Chapter

marimo guarantees your notebook code, outputs, and program state are consistent. This solves many problems associated with traditional notebooks like Jupyter.

A reactive programming environment.
Run a cell and marimo reacts by automatically running the cells that
reference its variables, eliminating the error-prone task of manually
re-running cells. Delete a cell and marimo scrubs its variables from program
memory, eliminating hidden state.

Compatible with expensive notebooks. marimo lets you configure the runtime
to be
lazy,
marking affected cells as stale instead of automatically running them. This
gives you guarantees on program state while preventing accidental execution of
expensive cells.

Synchronized UI elements. Interact with UI
elements like sliders,
dropdowns, dataframe
transformers, and chat
interfaces, and the cells that
use them are automatically re-run with their latest values.

Interactive dataframes. Page through, search, filter, and
sort
millions of rows blazingly fast, no code required.

Generate cells with data-aware AI. Collaborate on marimo notebooks with
your favorite agent, such as Claude Code, Codex, or OpenCode, using marimo
pair. Or,
generate code in the marimo editor with an AI
assistant that
is highly specialized for working with data, with context about your variables
in memory. Customize the system prompt, bring your own API keys, or use local
models.

Query data with SQL. Build SQL queries
that depend on Python values and execute them against dataframes, databases, lakehouses,
CSVs, Google Sheets, or anything else using our built-in SQL engine, which
returns the result as a Python dataframe.

Your notebooks are still pure Python, even if they use SQL.

Dynamic markdown. Use markdown parametrized by Python variables to tell
dynamic stories that depend on Python data.

Built-in package management. marimo has built-in support for all major
package managers, letting you install packages on import. marimo can even
serialize package
requirements
in notebook files, and auto install them in
isolated venv sandboxes.

Deterministic execution order. Notebooks are executed in a deterministic
order, based on variable references instead of cells' positions on the page.
Organize your notebooks to best fit the stories you'd like to tell.

Performant runtime. marimo runs only those cells that need to be run by
statically analyzing your code.

Batteries-included. marimo comes with GitHub Copilot, AI assistants, Ruff
code formatting, HTML export, fast code completion, a VS Code
extension,
a PyCharm plugin,
an interactive dataframe viewer, and many more
quality-of-life features.

Quickstart Copy Chapter

The marimo concepts
playlist
on our YouTube channel gives an
overview of many features.

Installation. In a terminal, run

pip install marimo  # or conda install -c conda-forge marimo
marimo tutorial intro

To install with additional dependencies that unlock SQL cells, AI completion, and more,
run

pip install "marimo[recommended]"

Create notebooks.

Create or edit notebooks with

marimo edit

Run apps. Run your notebook as a web app, with Python
code hidden and uneditable:

marimo run your_notebook.py

Execute as scripts. Execute a notebook as a script at the
command line:

python your_notebook.py

Automatically convert Jupyter notebooks. Automatically convert Jupyter
notebooks to marimo notebooks with the CLI

marimo convert your_notebook.ipynb > your_notebook.py

or use our web interface.

Tutorials.
List all tutorials:

marimo tutorial --help

Share cloud-based notebooks. Use
molab, a cloud-based marimo notebook
service similar to Google Colab, to create and share notebook links.

Questions? Copy Chapter

See the FAQ at our docs.

Learn more Copy Chapter

marimo is easy to get started with, with lots of room for power users.
For example, here's an embedding visualizer made in marimo
(try the notebook live on molab!):

Check out our docs,
usage examples, and our gallery to learn more.

Contributing Copy Chapter

We appreciate all contributions! You don't need to be an expert to help out.
Please see CONTRIBUTING.md for more details on how to get
started.

Questions? Reach out to us on Discord.

Community Copy Chapter

We're building a community. Come hang out with us!

• 🌟 Star us on GitHub
• 💬 Chat with us on Discord
• 📧 Subscribe to our Newsletter
• ☁️ Join our Cloud Waitlist
• ✏️ Start a GitHub Discussion
• 🦋 Follow us on Bluesky
• 🐦 Follow us on Twitter
• 🎥 Subscribe on YouTube
• 🤖 Follow us on Reddit
• 🕴️ Follow us on LinkedIn

A NumFOCUS affiliated project. marimo is a core part of the broader Python
ecosystem and is a member of the NumFOCUS community, which includes projects
such as NumPy, SciPy, and Matplotlib.

Inspiration ✨ Copy Chapter

marimo is a reinvention of the Python notebook as a reproducible, interactive,
and shareable Python program, instead of an error-prone JSON scratchpad.

We believe that the tools we use shape the way we think — better tools, for
better minds. With marimo, we hope to provide the Python community with a
better programming environment to do research and communicate it; to experiment
with code and share it; to learn computational science and teach it.

Our inspiration comes from many places and projects, especially
Pluto.jl,
ObservableHQ, and
Bret Victor's essays. marimo is part of
a greater movement toward reactive dataflow programming. From
IPyflow, streamlit,
TensorFlow,
PyTorch,
JAX, and
React, the ideas of functional,
declarative, and reactive programming are transforming a broad range of tools
for the better.

Finally, we would like to acknowledge Bennet
Meyers and David
Chassin for believing in marimo from the very
beginning: this work was supported in part by U.S. DOE Office of Critical
Minerals and Energy Innovation (CMEI) Integrated Energy Systems Office (IESO),
Agreement 34368.

File: docs/index.md Copy Chapter

title: marimo - Documentation for the Reactive Python Notebook
hide:

• navigation

marimo: The Reactive Python Notebook

marimo is an open-source reactive
Python notebook: run a cell or interact with a UI element, and marimo
automatically runs dependent cells (or marks them as
stale), keeping code
and outputs consistent and preventing bugs before they happen. Every marimo
notebook is stored as pure Python (Git-friendly), executable as a script, and
deployable as an app; while stored as Python, marimo notebooks also have native
support for SQL.

/// admonition | Built from the ground up
type: tip

marimo was built from the ground up to solve well-known problems associated with traditional notebooks.
///

Get started instantly with molab, our free online
notebook. Or get started
locally by installing marimo with your favorite package manager:

/// tab | install with pip

pip install marimo && marimo tutorial intro

///

/// tab | install with uv

uv add marimo && uv run marimo tutorial intro

///

/// tab | install with conda

conda install -c conda-forge marimo && marimo tutorial intro

///

Developer experience is core to marimo, with an emphasis on
reproducibility, maintainability, composability, and shareability.

Highlights Copy Chapter

• 🚀 batteries-included: replaces jupyter, streamlit, jupytext, ipywidgets, papermill, and more
• ⚡️ reactive: run a cell, and marimo reactively runs all dependent cells or marks them as stale
• 🖐️ interactive: bind sliders, tables, plots, and more to Python — no callbacks required
• 🐍 git-friendly: stored as .py files
• 🛢️ designed for data: query dataframes, databases, warehouses, and lakehouses with SQL; filter and search dataframes
• 🤖 AI-native: pair with AI agents like Claude Code, or use our editor's built-in AI features
• 🔬 reproducible: no hidden state, deterministic execution, built-in package management
• 🏃 executable: execute as a Python script, parameterized by CLI args
• 🛜 shareable: deploy as an interactive web app or slides, run in the browser via WASM
• 🧩 reusable: import functions and classes from one notebook to another
• 🧪 testable: run pytest on notebooks
• ⌨️ a modern editor: GitHub Copilot, AI assistants, vim keybindings, variable explorer, and more
• 🧑‍💻 use your favorite editor: run in VS Code or Cursor, or edit in neovim, Zed, or any other text editor

A reactive programming environment Copy Chapter

marimo guarantees your notebook code, outputs, and program state are consistent. This solves many problems associated with traditional notebooks like Jupyter.

A reactive programming environment.
Run a cell and marimo reacts by automatically running the cells that
reference its variables, eliminating the error-prone task of manually
re-running cells. Delete a cell and marimo scrubs its variables from program
memory, eliminating hidden state.

Compatible with expensive notebooks. marimo lets you configure the runtime
to be
lazy,
marking affected cells as stale instead of automatically running them. This
gives you guarantees on program state while preventing accidental execution of
expensive cells.

Synchronized UI elements. Interact with UI
elements like sliders,
dropdowns, dataframe
transformers, and chat
interfaces, and the cells that
use them are automatically re-run with their latest values.

Interactive dataframes. Page through, search, filter, and
sort
millions of rows blazingly fast, no code required.

Generate cells with data-aware AI. Collaborate on marimo notebooks with
your favorite agent, such as Claude Code, Codex, or OpenCode, using marimo
pair. Or,
generate code in the marimo editor with an AI
assistant that
is highly specialized for working with data, with context about your variables
in memory. Customize the system prompt, bring your own API keys, or use local
models.

Query data with SQL. Build SQL queries
that depend on Python values and execute them against dataframes, databases, lakehouses,
CSVs, Google Sheets, or anything else using our built-in SQL engine, which
returns the result as a Python dataframe.

Your notebooks are still pure Python, even if they use SQL.

Dynamic markdown. Use markdown parametrized by Python variables to tell
dynamic stories that depend on Python data.

Built-in package management. marimo has built-in support for all major
package managers, letting you install packages on import. marimo can even
serialize package
requirements
in notebook files, and auto install them in
isolated venv sandboxes.

Deterministic execution order. Notebooks are executed in a deterministic
order, based on variable references instead of cells' positions on the page.
Organize your notebooks to best fit the stories you'd like to tell.

Performant runtime. marimo runs only those cells that need to be run by
statically analyzing your code.

Batteries-included. marimo comes with GitHub Copilot, AI assistants, Ruff
code formatting, HTML export, fast code completion, a VS Code
extension,
a PyCharm plugin,
an interactive dataframe viewer, and many more
quality-of-life features.

Quickstart Copy Chapter

The marimo concepts
playlist
on our YouTube channel gives an
overview of many features.

Installation. In a terminal, run

pip install marimo  # or conda install -c conda-forge marimo
marimo tutorial intro

To install with additional dependencies that unlock SQL cells, AI completion, and more,
run

pip install marimo[recommended]

Create notebooks.

Create or edit notebooks with

marimo edit

Run apps. Run your notebook as a web app. By default, the Python
source code is not sent to the browser, so it stays hidden and uneditable:

marimo run your_notebook.py

Execute as scripts. Execute a notebook as a script at the
command line:

python your_notebook.py

Automatically convert Jupyter notebooks. Automatically convert Jupyter
notebooks to marimo notebooks with the CLI

marimo convert your_notebook.ipynb > your_notebook.py

or use our web interface.

Tutorials.
List all tutorials:

marimo tutorial --help

Share cloud-based notebooks. Use
molab, a cloud-based marimo notebook
service similar to Google Colab, to create and share notebook links.

Questions? Copy Chapter

See our FAQ.

Learn more Copy Chapter

marimo is easy to get started with, with lots of room for power users.
For example, here's an embedding visualizer made in marimo
(try the notebook live on molab!):

Check out our guides, usage examples,
and our gallery to learn more.

Contributing Copy Chapter

We appreciate all contributions! You don't need to be an expert to help out.
Please see CONTRIBUTING.md for more details on how to get
started.

Questions? Reach out to us on Discord.

Community Copy Chapter

We're building a community. Come hang out with us!

• 🌟 Star us on GitHub
• 💬 Chat with us on Discord
• 📧 Subscribe to our Newsletter
• ☁️ Join our Cloud Waitlist
• ✏️ Start a GitHub Discussion
• 💬 Follow us on Bluesky
• 🐦 Follow us on Twitter
• 🎥 Subscribe on YouTube
• 💬 Follow us on Mastodon
• 🤖 Follow us on Reddit
• 🕴️ Follow us on LinkedIn

A NumFOCUS affiliated project. marimo is a core part of the broader Python
ecosystem and is a member of the NumFOCUS community, which includes projects
such as NumPy, SciPy, and Matplotlib.

Inspiration ✨ Copy Chapter

marimo is a reinvention of the Python notebook as a reproducible, interactive,
and shareable Python program, instead of an error-prone JSON scratchpad.

We believe that the tools we use shape the way we think — better tools, for
better minds. With marimo, we hope to provide the Python community with a
better programming environment to do research and communicate it; to experiment
with code and share it; to learn computational science and teach it.

Our inspiration comes from many places and projects, especially
Pluto.jl,
ObservableHQ, and
Bret Victor's essays. marimo is part of
a greater movement toward reactive dataflow programming. From
IPyflow, streamlit,
TensorFlow,
PyTorch,
JAX, and
React, the ideas of functional,
declarative, and reactive programming are transforming a broad range of tools
for the better.

Finally, we would like to acknowledge Bennet
Meyers and David
Chassin for believing in marimo from the very
beginning: this work was supported in part by U.S. DOE Office of Critical
Minerals and Energy Innovation (CMEI) Integrated Energy Systems Office (IESO),
Agreement 34368.