Intro

1. Reactive execution¶

A marimo notebook is made up of small blocks of Python code called cells.

marimo reads your cells and models the dependencies among them: whenever a cell that defines a global variable is run, marimo automatically runs all cells that reference that variable.

Reactivity keeps your program state and outputs in sync with your code, making for a dynamic programming environment that prevents bugs before they happen.

Global names must be unique. To enable reactivity, marimo imposes a constraint on how names appear in cells: no two cells may define the same variable.

2. UI elements¶

Cells can output interactive UI elements. Interacting with a UI element automatically triggers notebook execution: when you interact with a UI element, its value is sent back to Python, and every cell that references that element is re-run.

marimo provides a library of UI elements to choose from under marimo.ui.

🌊 Some UI elements. Try interacting with the below elements.

3. marimo is just Python¶

marimo cells parse Python (and only Python), and marimo notebooks are stored as pure Python files — outputs are not included. There’s no magical syntax.

The Python files generated by marimo are:

• easily versioned with git, yielding minimal diffs

• legible for both humans and machines

• formattable using your tool of choice,

• usable as Python scripts, with UI elements taking their default values, and

• importable by other modules (more on that in the future).

4. Running notebooks as apps¶

marimo notebooks can double as apps. Click the app window icon in the bottom-right to see this notebook in “app view.”

Serve a notebook as an app with marimo run at the command-line. Of course, you can use marimo just to level-up your notebooking, without ever making apps.

5. The marimo command-line tool¶

Creating and editing notebooks. Use

marimo edit

in a terminal to start the marimo notebook server. From here you can create a new notebook or edit existing ones.

Running as apps. Use

marimo run notebook.py

to start a webserver that serves your notebook as an app in read-only mode, with code cells hidden.

Convert a Jupyter notebook. Convert a Jupyter notebook to a marimo notebook using marimo convert:

marimo convert your_notebook.ipynb > your_app.py

Tutorials. marimo comes packaged with tutorials:

• dataflow: more on marimo’s automatic execution

• ui: how to use UI elements

• markdown: how to write markdown, with interpolated values and LaTeX

• plots: how plotting works in marimo

• sql: how to use SQL

• layout: layout elements in marimo

• fileformat: how marimo’s file format works

• markdown-format: for using .md files in marimo

• for-jupyter-users: if you are coming from Jupyter

Start a tutorial with marimo tutorial; for example,

marimo tutorial dataflow

In addition to tutorials, we have examples in our our GitHub repo.

6. The marimo editor¶

Here are some tips to help you get started with the marimo editor.

Finally, a fun fact¶

The name “marimo” is a reference to a type of algae that, under the right conditions, clumps together to form a small sphere called a “marimo moss ball”. Made of just strands of algae, these beloved assemblages are greater than the sum of their parts.