Quickstart

Get started with marimo in minutes - from installation to your first interactive notebook

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

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:

Slider

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:

Horizontal stack

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

• Browse the examples gallery for inspiration
• Join the Discord community for support
• Check the FAQ for common questions
• Watch YouTube tutorials for video guides