marimo Reactive Python Notebook

0.23.1 · active · verified Sat Apr 11

marimo is an open-source reactive Python notebook library that enhances traditional notebooks by guaranteeing consistency between code and outputs. It stores notebooks as pure Python files, making them Git-friendly, executable as standalone scripts, and deployable as interactive web applications. marimo also provides built-in UI elements and first-class SQL support. The current version is 0.23.1, and the project has an active development and release cadence.

Warnings

breaking marimo's reactive model does not track mutations to objects across cells. If you modify an object in one cell and expect another dependent cell to react to that mutation, it will not work as expected. Instead, create new objects or perform all mutations within a single cell to ensure reactivity.
Fix: Avoid in-place mutations of objects across cell boundaries. Instead, reassign variables to new objects, or ensure all operations on a specific object occur within the same cell that defines it.
breaking Each variable can be defined in only one cell to ensure a clear and reproducible execution order. Defining the same variable in multiple cells will result in an error.
Fix: Refactor your code to ensure each variable is assigned a value in only one cell. Use local variables or pass values between cells explicitly.
breaking marimo does not allow `import *` (importing all symbols from a library) to prevent ambiguity and maintain a well-defined dependency graph.
Fix: Use explicit imports (e.g., `import marimo as mo` or `from marimo.ui import slider`) instead of wildcard imports.
breaking Circular dependencies between cells are not allowed. If Cell A depends on Cell B, Cell B cannot simultaneously depend on Cell A. This prevents infinite loops and ensures a deterministic execution flow.
Fix: Analyze your cell dependencies and refactor your code to break any circular references. This typically involves rethinking data flow and variable assignments.
gotcha UI elements (e.g., `mo.ui.slider`) will reset to their initial `value` argument if the cell defining them reruns. This can happen if the cell itself depends on other changing variables.
Fix: Isolate UI element definitions in cells that do not have upstream dependencies that would cause them to re-execute unnecessarily. Use `mo.state` for persistent, mutable state across reruns if an element's value needs to survive cell re-execution without resetting.
gotcha marimo notebooks are pure Python files (`.py`), which means GitHub does not render their outputs directly like Jupyter's `.ipynb` files.
Fix: To share notebooks with rendered outputs on GitHub, configure marimo to automatically snapshot outputs to an `.ipynb` file or use services like molab for live previews.

Install

pip install marimo Base Installation
pip install "marimo[sql]" With SQL (e.g., DuckDB) and other extras

Imports

marimo
```
import marimo as mo
```
marimo explicitly disallows `import *` to maintain a clear dependency graph and avoid ambiguity.
ui elements
```
mo.ui.slider(...)
mo.ui.dropdown(...)
```
UI elements are accessed through the `mo.ui` submodule.

Quickstart

This quickstart demonstrates creating a simple reactive marimo notebook. Save this code as a `.py` file (e.g., `my_notebook.py`) and run `marimo edit my_notebook.py` in your terminal to open it in your browser. The second cell will automatically update as you interact with the slider in the first cell.

import marimo as mo

# Create an interactive slider
slider = mo.ui.slider(1, 100, value=50, label="Select a value")
slider

# A reactive cell that uses the slider's value
# This cell will automatically re-run when the slider moves.
mo.md(f"The current value is **{slider.value}**")

view raw JSON →