Understanding dataflow

Unlike traditional notebooks, marimo understands the relationships between cells and uses this information to keep your code and outputs consistent. These relationships are represented as a dataflow graph, which encodes how variables flow from one cell to another.

The dataflow graph, which is inferred statically from variable definitions and references, is used to automatically run (or mark stale) cells in the correct sequence; it's also why cells can be arranged "out of order" on the page, or across columns.

marimo provides several tools to help you visualize and understand the relationships it identifies between cells.

Variables explorer

The variables explorer panel collects marimo's understanding of the variables in your notebook into a single searchable list.

To open the panel, click the variables icon in the left sidebar panel. The variable explorer shows each variable's name, type, value, where it's defined, and where it's used.

Dependency explorer

The dependency explorer panel provides a bird's-eye view of your notebook's dataflow, showing all cells as an interactive graph. It helps you understand high-level patterns, overall connectedness, and the broader structure of your notebook.

To open the dependency explorer, click the graph icon in the left sidebar panel. You can choose between vertical or horizontal layouts.

Minimap

The minimap provides a focused slice of your notebook's dataflow, helping you understand the reactive context of a given cell and navigate related cells. You can toggle the minimap a hotkey (Cmd/Ctrl-Shift-i), or select the map icon from the footer toolbar.

Click a cell in the minimap to jump to it:

Connections are read left to right:

• Connections to the left are direct inputs — cells the current cell reads from
• Connections to the right are direct outputs — cells that read from the current cell
• Cells positioned left or right but not directly connected are transitive dependencies — cells that influence or are influenced by the current cell, but only through one or more intermediate cells

The minimap can take some getting used to, but it's an effective representation for understanding how data flows around the current cell. It's meant to show just enough local context to help you debug, trace relationships, and navigate complex notebooks. For a high level overview, use the dependency explorer.

Cell symbols

The minimap uses visual indicators to show the status and connectivity of each cell:

Symbol	Meaning
	Cell uses variables from other cells
	Cell defines variables used by other cells
	Cell uses variables and defines variables used by others
	Cell defines variables but isn't connected to anything (safe to delete)
	Cell doesn't define or use variables from other cells (often markdown)
	Cell has an error

Reading cell connections

When you select a cell, the minimap draws lines showing how data flows between cells. Since marimo cells can define multiple variables, downstream connections show all cells that reference any variable from your selected cell.

Path	Interpretation
	First cell defines variables used by the second cell. Second cell will re-run when the first runs
	First cell uses variables from the second cell. First cell will re-run when the second runs
	Gray cell has no connection to the blue cells above
	Gray cell indirectly uses variables from the first cell. Whiskers indicate transitive dependencies
	Gray cell's variables are indirectly used by the second cell. Whiskers indicate transitive dependencies
	Cells have circular dependencies - each uses variables from the other (error)

Implementation notes

The minimap was heavily inspired by Observable's minimap, a thoughtfully designed dataflow visualization for their reactive JavaScript notebooks.

We adapted Observable's visual design to marimo's execution model. A key difference: Observable cells are named (declaring one variable), while marimo cells can define multiple variables. This leads to asymmetric dataflow tracing. When tracing upstream, we can identify exactly which variables from a cell depends on. When tracing downstream, all variables in a dependent cell are considered affected. Our minimap also accounts for marimo's support for multi-column layouts.

Reactive reference highlighting

marimo's reactive reference highlighting provides an in-editor indicator when variables defined by other cells are used in the current cell. These "reactive references" are emphasized with an underline and lightly bolded text:

Hover over any underlined variable and Cmd/Ctrl-Click to jump to its definition.

This feature is currently opt-in and must be enabled via Settings > User Settings > Display > Reference highlighting or toggled via the command palette (Cmd/Ctrl-K > Reference highlighting).