Prepare notebook results once, then read the same export from Python, TypeScript, agents, or custom applications.

Documentation · Getting started · Browser example · Reference

marimo-export runs selected states of a marimo notebook and writes their named results to a portable notebook export. Python, TypeScript, agents, and custom clients can read that export after the producer stops.

Build the quickstart

From a repository checkout, run the CLI directly from PyPI:

mkdir -p dist
uvx marimo-export build examples/quickstart/report.py \
  --spec examples/quickstart/report.export.yaml \
  --output dist/quickstart
uvx marimo-export verify dist/quickstart

dist/quickstart/index.json describes two exported states and one JSON output. Read the monthly state:

from marimo_export import open_export

export = open_export("dist/quickstart")
summary = export.state("monthly").output("summary").json()
print(dict(summary))

Expected output:

{'days': 30, 'label': 'Last 30 days'}

Install the Python package in another project with uv add marimo-export. The getting-started guide creates the same notebook and export from an empty directory.

Follow the product model

notebook + ExportSpec
  -> plan complete states and named outputs
  -> prepare missing results through marimo
  -> write index.json and declared assets
  -> open, resolve, and load from a consumer

An ExportSpec contains sparse state rows and named outputs. Planning completes each row from the captured input baseline. Every exported state has the same output-name set. A representation identifies how one output is stored and decoded.

What is marimo-export? introduces each object and operation in order. Why export notebook states? compares finite prepared results with live Python and browser Python execution.

Choose the next task

Goal	Start here
Select states and output representations	Choose states and outputs
Build from a file or capture a live session	Build or capture
Read from Python, a browser, or an agent	Consume an export
Build state transitions in a browser	Build a browser application
Publish and deploy immutable exports	Deploy an export
Look up an exact contract	Reference

Compatibility and trust

The Python package requires Python 3.10 or newer, is tested on Python 3.10 through 3.14, and installs the marimo release pinned by its package metadata. Browser applications install @marimo-team/marimo-export and any dependencies required by their selected output loaders. See Compatibility for the complete matrix.

Preparing an export executes notebook code with the producer environment's file, credential, network, and package access. Opening validates canonical index.json. Loading verifies the selected asset. Mounting an interactive representation grants its code the browser page's authority. See Integrity and trust before publishing executable output.

Contributor architecture, validation, and release mechanics live in the contributor guide. See Contributing for the pull request path and Security for private vulnerability reporting.

Licensed under Apache-2.0.