Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/marimo-team/marimo/llms.txt

Use this file to discover all available pages before exploring further.

​
Quickstart

Get up and running with marimo in minutes. This guide walks you through installation, creating your first notebook, and exploring marimo’s core features.

​
Installation

Install marimo using pip or conda: 
pip install marimo
The recommended extras include SQL support, AI completion, formatting tools, and more features that enhance your experience.

​
Your first notebook

1

Run the interactive tutorial

The fastest way to learn marimo is through the built-in tutorial:
marimo tutorial intro
This launches an interactive notebook that teaches you marimo’s core concepts.
2

Create a new notebook

Start a new notebook with the edit command:
marimo edit
This opens marimo in your browser with an empty notebook.
3

Add your first cell

Click the ”+ Code” button to add a cell, then write some Python:
import marimo as mo

slider = mo.ui.slider(1, 100, value=50)
slider
When you run this cell (Ctrl+Enter or Cmd+Enter), you’ll see an interactive slider.
4

Create a reactive cell

Add another cell that uses the slider value:
import numpy as np
import matplotlib.pyplot as plt

x = np.linspace(0, 2 * np.pi, slider.value)
y = np.sin(x)

plt.plot(x, y)
plt.title(f"Sine wave with {slider.value} points")
plt.gcf()
Move the slider and watch the plot update automatically - that’s reactivity!
5

Save your notebook

Save your notebook with Ctrl+S (or Cmd+S). You’ll be prompted for a filename. marimo saves it as a .py file:
# Your notebook is now saved as a Python file
marimo edit my_notebook.py

​
Core workflows

​
Creating notebooks

Create or edit notebooks with the edit command: 
# Start a new notebook
marimo edit

# Edit an existing notebook
marimo edit notebook.py

# Edit with a specific port
marimo edit notebook.py --port 3000

​
Running as apps

Deploy your notebook as a web app where code is hidden and non-editable: 
marimo run notebook.py
This is perfect for:
  • Sharing interactive dashboards with colleagues
  • Creating internal tools
  • Publishing data stories
  • Building demos and prototypes
In app mode, users can interact with UI elements but cannot edit the code. The notebook remains fully reactive.

​
Executing as scripts

Run notebooks as command-line scripts: 
python notebook.py
You can pass arguments: 
import marimo as mo

# Access CLI arguments in your notebook
args = mo.cli_args()
print(args)

python notebook.py --arg1 value1 --arg2 value2

​
Exploring tutorials

marimo includes several built-in tutorials: 
# List all available tutorials
marimo tutorial --help

# Run specific tutorials
marimo tutorial intro      # Introduction to marimo
marimo tutorial dataflow   # How reactivity works
marimo tutorial ui         # Interactive UI elements
marimo tutorial plots      # Data visualization
marimo tutorial sql        # SQL cells
marimo tutorial markdown   # Dynamic markdown

​
Essential features

​
Interactive UI elements

marimo provides 40+ UI components that automatically trigger cell re-execution: 
import marimo as mo

slider = mo.ui.slider(1, 100, value=50, label="Sample size")
slider
Access values with .value: 
mo.md(f"Selected {slider.value} samples using {dropdown.value} model")

​
Dynamic markdown

Create markdown that updates with your data: 
import marimo as mo

name = "marimo"
count = 42

mo.md(f"""
# Welcome to {name}!

You have processed **{count}** records.

{"🎉" * min(count, 10)}
""")

​
SQL cells

Query data with native SQL support: 
import marimo as mo
import pandas as pd

df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})

SELECT * FROM df WHERE x > 1
The SQL cell creates a dataframe you can use in Python cells.

​
Layouts

Organize outputs with flexible layouts: 
import marimo as mo

mo.hstack([plot1, plot2, plot3])

​
Converting from Jupyter

Convert existing Jupyter notebooks to marimo: 
# Convert to marimo format
marimo convert notebook.ipynb > notebook.py

# Edit the converted notebook
marimo edit notebook.py
Automatic conversion works well for simple notebooks, but you may need to refactor cells that have hidden state or out-of-order execution dependencies.

​
Next steps

Key concepts

Learn about reactivity, cells, and the marimo execution model

Installation

Explore advanced installation options and optional dependencies

​
Getting help

Build docs developers (and LLMs) love

Get started for freeTalk to us