marimo-team/marimo-export

Select the states and outputs to publish from a marimo notebook. marimo-export writes a portable, verified notebook export that browser applications and agents read without a Python runtime or a copy of the notebook source.

Build the quickstart

From a repository checkout, run the CLI in the workspace environment:

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

dist/quickstart/index.json describes two exported states and two named outputs. Two report assets sit under dist/quickstart/assets. Read the monthly JSON state:

uv run python - <<'PY'
from marimo_export import open_export

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

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.

How notebook exports work

flowchart LR
    source[Notebook and ExportSpec]
    plan[Plan states and outputs]
    prepare[Prepare missing states]
    write[Write index and assets]
    consume[Open, resolve, and load]

    source --> plan --> prepare --> write --> consume

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

Overview follows the quickstart from notebook states to the files consumers read. When to use marimo-export compares notebook exports with live Python services and browser Python execution.

Documentation

Compatibility and trust

The Python package supports 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.