The next generation of Python notebooks

Marie-Hélène Burle

October 28, 2025

Notes

• I am making an opinionated decision to use uv (because it is great)
• Notebooks are great for prototyping but not at scale
• marimo is not available on the Alliance clusters at this point

A new notebook

What’s wrong with Jupyter?

Jupyter notebooks are very popular but they come with

• a nightmare for version control
• an awkward JSON file format
• reproducibility issues

DAC notebooks

marimo notebooks automatically generate an intermediate representation (IR) in the form of a directed acyclic graph (DAC) of

• definitions of global variables
• references of global variables

Each cell is parsed into an abstract syntax tree (AST)

Statically inferred (no runtime tracing)

Saved as Python file

Notebooks are saved as .py files
Each cell stored as a function
Pure functions can be reused as modules

➔

Easy version control
Directly executable as script or web app
Readable in any text editor

Interactive elements

marimo.ui creates interactive user interface (UI) elements with first-class support

Notebooks are automatically updated when values are changed via interactions

The constraints

Global variables must be unique

Even reusing i in loops is a problem

Variables local to a cell are created with _

So _i can be reused between cells:

for _i in range(10):
    ...

In-place transformations are not allowed

Computation cost

There is a cost to updating the DAG at each change

This can be controlled by disabling/enabling:

• autorun on startup
• specific cells
• autorun on cell change (lazy execution)

Getting started

Installation

Create a uv project:

uv init --bare

Install marimo in it as a development dependency:

uv add --dev marimo

(Optional) add tools marimo can make use of:

uv add --dev ruff basedpyright mcp

Configuration

Via GUI

• Notebook settings
• User settings

User settings saved in ~/.config/marimo/marimo.toml or similar
Logs found at ~/.cache/marimo/logs or similar

Package manager

User settings ➔ Package Management ➔ Manager: uv

AI pair programming

Code completion

Use GitHub Copilot without account

AI assistant

Use any of the classic LLMs with API key

MCP servers

• marimo docs
• Context7

Tutorials

uv run marimo tutorial intro

For more tutorials, replace intro with any of:

dataflow
ui
markdown
plots
sql
layout
fileformat
markdown-format
for-jupyter-users

Usage

ipynb notebooks conversion

marimo convert notebook.ipynb -o notebook.py

IPython magics are replaced by Python functions

Package installation

Using uv:

uv add <package>

Example:

uv add numpy

or via GUI (after it has been set properly)