Python API

The Python package prepares selected marimo notebook states, writes verified notebook exports, and reads the same files that browser applications consume. The supported Python range and classifiers are declared in the package metadata. Continuous integration tests each supported version, and the package metadata pins its exact supported marimo release. See Compatibility for the complete boundary.

Install the base package to produce and read portable JSON, scalar, NumPy, rendered-output, complete-cell, and blob outputs:

uv add marimo-export

Install a producer extra when an ExportSpec uses its exporter:

Exporter	Install
Altair Vega-Lite, PNG, or SVG	uv add "marimo-export[charts]"
AnyWidget	uv add "marimo-export[anywidget]"
Parquet	uv add "marimo-export[parquet]"
Every built-in exporter	uv add "marimo-export[all]"

The media exporter needs the charts extra for Altair charts only. It renders matplotlib figures with the notebook's own matplotlib and other values with their display methods.

Choose a Python path

Job	Reference
Define states and outputs, plan work, prepare, or build	Produce an export
Open states and decode outputs	Read and verify exports
Inspect a notebook or capture a live session	Sessions and inspection
Configure retention or record observed inputs	Repository and observations
Commit an application directory or retain a Python prepared publication	Delivery and publications
Embed marimo-export behavior in a marimo host	Host integration
Discover the version-matched code-mode workflow	marimo_export.agent
Convert portable values or encode canonical JSON	Portable JSON
Construct indexes and descriptors or handle typed errors	Format records and errors
Interpret progress events and cache activity	Produce an export
Check lower-level capture record reachability	Narrow protocol records

The common workflow

from pathlib import Path

from marimo_export import ExportSpec, OutputSpec, build, open_export

spec = ExportSpec(
    default_state="baseline",
    states={
        "baseline": {},
        "weekly": {"interval": "1wk"},
    },
    outputs={"summary": OutputSpec.json("report.summary")},
)

Path("dist").mkdir(exist_ok=True)
result = build("report.py", spec=spec, output="dist/report")
summary = open_export(result.path).default_state.output("summary").json()

An ExportSpec declares named state rows and named outputs. Planning fills each sparse row from the notebook baseline and creates one complete input vector per state. Preparation stores reusable results in the export repository. Writing creates a notebook export whose index.json and assets can be verified without running notebook code.

The package root exposes the common workflow:

from marimo_export import (
    ExportPlan,
    ExportRepository,
    ExportResult,
    ExportSpec,
    NotebookExport,
    OutputSpec,
    PreparedExport,
    ProgressEvent,
    StateSpace,
    VerificationResult,
    build,
    capture,
    open_export,
    plan,
    prepare,
    verify_export,
)

Focused modules own application delivery, live sessions, observations, host integration, output values, and the low-level format records. Their reference pages identify the canonical import path for each API.