Marimo Pair

Executing Code

Every execute-code call runs inside the notebook's kernel. All cell variables are in scope — print(df.head()) just works. Nothing you define persists between calls (variables, imports, side-effects all reset), but you can freely introspect the notebook: inspect variables, test code snippets, check types and shapes. Use this to explore, prototype, and validate before committing anything to the notebook — then create cells to persist state and make results visible to the user.

To mutate the notebook's dataflow graph — create, edit, and delete cells, install packages, and run cells — use marimo._code_mode:

import marimo._code_mode as cm

async with cm.get_context() as ctx:
    cid = ctx.create_cell("x = 1")
    ctx.packages.add("pandas")
    ctx.run_cell(cid)

You must use async with — without it, operations silently do nothing. All ctx.* methods are synchronous — they queue operations and the context manager flushes them on exit. Do not await them.

The kernel supports top-level await, so use async with directly. Do not wrap calls in async def main(): ... + asyncio.run(main()) — it's unnecessary and easy to get wrong (compound statements like async with can't follow def name(): on the same line, so cramming it into a -c one-liner produces a SyntaxError).

Cells are not auto-executed. create_cell and edit_cell are structural changes only — use run_cell to queue execution.

code_mode is a tested, safe API for notebook mutations — prefer it for all structural changes. You also have access to marimo internals from the kernel, but treat that as a last resort and only with high confidence after exploration.

Edit cells through code_mode, never the file system. Direct file writes are silently lost. It is tempting to reach for Edit/Write for a small tweak since edit_cell requires the full new cell body. Don't — without --watch (off by default) the kernel never sees those edits and overwrites them on its next save, so the user sees nothing. (Read on the .py is okay, but content may lag the live kernel; prefer ctx.cells[target].code.)

UI state lives outside the reactive graph. Anywidget traitlets can be read or set directly (e.g., slider.value = 5). For mo.ui.* elements, use ctx.set_ui_value(element, new_value) inside code_mode.

First Step: Explore the API

The code_mode API can change between marimo versions. Explore it at the start of each session — dig deeper into anything you're unsure about.

import marimo._code_mode as cm
help(cm)

Guard Rails

Skip these and the UI breaks:

• Install packages via ctx.packages.add(), not uv add or pip. The code API handles kernel restarts and dependency resolution correctly. Only fall back to external CLIs if the API is unavailable or fails.
• Custom widget = anywidget. For bespoke visual components, use anywidget with HTML/CSS/JS. Composed mo.ui is fine for simple forms and controls. See rich-representations.md.
• NEVER Edit, Write, or NotebookEdit the notebook .py file while a session is running. Direct writes are silently destroyed and never reach the user. marimo only watches the file with --watch, which is off by default. Without it, the kernel doesn't pick up file edits — and on its next save, the kernel writes its own state and clobbers yours. The user sees no change, you think the work landed, and the bug is invisible. Always use ctx.edit_cell(target, code=...) with the full new cell body — even for a one-character change. (Read is allowed, but disk content may lag the live kernel; for the current truth prefer ctx.cells[target].code.)
• No temp-file deps in cells. pathlib.Path("/tmp/...") in cell code is a bug.
• Avoid empty cells. Prefer edit_cell into existing empty cells rather than creating new ones. Clean up any cells that end up empty after edits.
• Don't worry about cell names. Most cells don't need explicit names — see notebook-improvements.md.

Widgets and Reactivity

Anywidget state (traitlets) lives outside marimo's reactive graph. To hook a widget trait into the graph, pick one strategy per widget — never mix them:

• mo.state + .observe() — you pick specific traits to bridge. Default choice.
• mo.ui.anywidget() — wraps all synced traits into one reactive .value. Convenient but coarser.

Read rich-representations.md before wiring either.

Keep in Mind

• The user is editing too. The notebook can change between your calls — re-inspect notebook state if it's been a while since you last looked.
• Deletions are destructive. Deleting a cell removes its variables from kernel memory — restoring means recreating the cell and re-running it and its dependents. If intent seems ambiguous, ask first.
• Installing packages changes the project. ctx.packages.add() adds real dependencies — confirm when it's not obvious from context.

References

• finding-marimo.md — how to find and invoke the right marimo
• gotchas.md — cached module proxies and other traps
• rich-representations.md — custom widgets and visualizations
• notebook-improvements.md — improving existing notebooks