Consume a notebook export

A notebook export gives every consumer the same default state, authored state aliases, complete input vectors, and named outputs. The examples on this page use dist/report, created by Build your first notebook export.

Job	Interface
Read and verify local files	open_export() and verify_export()
Load immutable results in a browser	openExport()
Drive a changing prepared publication	Browser prepared subpath
Ground an agent answer	Python reader, CLI verification, or export format
Implement another reader	Export format

Open from Python

Select the monthly state and decode its JSON output:

from marimo_export import open_export

notebook_export = open_export("dist/report")
monthly = notebook_export.state("monthly")
summary = monthly.output("summary").json()
print(dict(summary))

Expected output:

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

Opening validates canonical index.json and leaves output assets lazy. The quickstart keeps summary inline, so json() decodes it directly from the index. When an output references an asset, its reader verifies that asset before decoding it. The reader also exposes:

• identity, the SHA-256 of the exact index.json bytes
• spec_sha256, the identity of the authored ExportSpec
• default_state, the resolved default ExportState
• notebook and producer facts
• input names, control bindings, output names, aliases, and states

Select an exported state

Readers support these selection forms:

• state(alias) selects an authored state alias such as monthly.
• Python state_by_fingerprint(fingerprint) selects an exact state identity.
• resolve(inputs) selects one complete exported input vector.
• state.resolve(patch) replaces each supplied root input in the current exported state, then selects the resulting complete vector. It does not deep-merge nested objects.

Resolution returns a state already present in the notebook export. Preparing a new input vector requires another producer operation or a Python service.

Read an asset-backed output from Python

After building the market dashboard, an output backed by a BlobAsset exposes verified bytes and media metadata:

from marimo_export import open_export

market_export = open_export("examples/vite-vanilla/public/export")
chart = market_export.default_state.output("performance_chart").blob_asset()
print(chart.media_type, chart.filename, len(chart.data))

Use scalar() for a native scalar and json() for portable JSON. Use blob_asset() for text, HTML, images, Parquet, Vega-Lite, AnyWidget, and custom media types stored through the BlobAsset envelope. NumPy, Arrow, rendered-output, and complete-cell accessors return verified raw bytes for a compatible decoder.

The Python reader validates framing but does not interpret NumPy, Arrow, or marimo snapshot semantics.

Open from a browser

A browser reads the export over HTTP. Configure the static server so dist/report is available at /exports/report/, then open the same monthly state:

import { openExport } from "@marimo-team/marimo-export";
import { jsonLoader } from "@marimo-team/marimo-export/loader/json";

const notebookExport = await openExport("/exports/report/");
const monthly = notebookExport.state("monthly");
const summary = await monthly.output("summary").load(jsonLoader());

console.log(summary); // { days: 30, label: "Last 30 days" }

The JSON loader has no peer runtime. Specialized loaders can require one. Output representations maps stored representations to browser loaders and their peer dependencies.

Follow a prepared publication

Applications can open a marimo-export.prepared.v1 manifest with the browser prepared subpath:

import {
  fetchPreparedExportManifest,
  openPreparedPublication,
} from "@marimo-team/marimo-export/prepared";

const manifestUrl = new URL("/runtime/prepared.json", location.href);
const manifest = await fetchPreparedExportManifest(manifestUrl);
const publication = await openPreparedPublication(manifest, manifestUrl);

The manifest binds one immutable export identity, export URL, complete input vector, and state fingerprint. PreparedStateController owns semantic state updates and cancellation. PreparedPublicationRefresh swaps to a newer verified manifest while preserving a compatible current selection.

Verify the complete export

Python:

from marimo_export import verify_export

result = verify_export("dist/report")

CLI:

uv run marimo-export verify dist/report

Browser:

const result = await notebookExport.verify({
  maxBytes: 512 * 1024 * 1024,
  maxTotalBytes: 2 * 1024 * 1024 * 1024,
});

Verification reads every declared asset. API and JSON results return exported state, state-output-pair, unique-asset, and verified-byte counts. Human CLI output omits the state-output-pair count. index.json is the integrity root.

Retain evidence for an agent

Bind data-driven claims to the selected state and output. Retain notebook, producer, spec, state fingerprint, codec, media type, asset SHA-256, and verification facts when the answer needs an auditable source.

Use notebook exports with agents develops this workflow. Build a browser application covers complete state transitions and mount disposal.