Marimo Notebooks

What is Marimo?[edit]

marimo is a modern, reactive Python notebook environment designed for building reproducible, interactive, and production-ready analyses and applications.

Unlike traditional notebooks, marimo treats notebooks as executable Python programs. Each notebook is stored as a standard .py file, making it easy to version, review, and deploy.

Marimo Notebooks vs Jupyter Notebooks[edit]

File Format[edit]

• marimo notebooks are plain Python files (.py)
• Jupyter notebooks use JSON-based .ipynb files

This makes marimo notebooks:

• Easier to read in code reviews
• Better suited for Git and diff tools
• Compatible with standard Python tooling

Execution Model[edit]

• marimo uses a reactive execution model
• Jupyter uses a cell-by-cell, imperative execution model

In marimo:

• Cells automatically re-run when their dependencies change
• Execution order is deterministic
• Hidden state and out-of-order execution are avoided

Reproducibility[edit]

marimo notebooks are designed to be:

• Fully reproducible
• Free of implicit state
• Safe to re-run from top to bottom at any time

Jupyter notebooks can accumulate hidden state if cells are run out of order, which may lead to inconsistent results.

Interactivity and Apps[edit]

With marimo:

• Notebooks can behave like interactive applications
• UI elements (sliders, dropdowns, buttons) are first-class citizens
• The same notebook can be used for exploration, dashboards, or lightweight apps

Jupyter typically requires additional frameworks (e.g. widgets or web frameworks) to achieve similar behavior.

Environment Management[edit]

When combined with uv:

• marimo runs inside a well-defined project environment
• Dependencies are explicit and version-pinned
• Notebooks are portable and reproducible across machines

Installing Marimo in a uv Project[edit]

To install marimo with recommended dependencies inside the current uv project:

uv add "marimo[recommended]"

Creating and Editing a marimo Notebook[edit]

To create and edit a new marimo notebook using the project environment:

uv run marimo edit myscript.py

This will:

• Create the file if it does not exist
• Launch the marimo editor
• Use the uv-managed Python environment

Using Marimo with a Sandbox Environment[edit]

If you want a notebook with its own isolated environment, independent of the current project, use the sandbox mode:

uvx marimo edit --sandbox myapp.py

Sandbox mode is useful for:

• Quick experiments
• Prototyping
• Isolated demos without affecting project dependencies