Notebooks in extensions

Extensions can include marimo notebooks as first-class content. An extension-shipped notebook appears in Analytics → Notebooks → From extension for every organization that installs the extension; adding it copies the notebook into the current workspace, where it behaves exactly like a user-created notebook (open, edit, governed scrydon SDK access).

Typical uses: a quickstart tour of the extension's data model, an analysis template over the extension's data sources, or a governed write-back walkthrough.

Extension layout

Each notebook is one subdirectory in the extension:

my-extension/
  manifest.json               # extension manifest — declares the notebook entries
  notebooks-quickstart/
    manifest.json             # notebook content manifest
    notebook.py               # the marimo notebook (≤ 1 MB)
  notebooks-writeback-demo/
    manifest.json
    notebook.py

Declare each notebook in the extension manifest's contents:

{
  "contents": [
    { "kind": "notebook", "path": "notebooks-quickstart", "required": true },
    { "kind": "notebook", "path": "notebooks-writeback-demo", "required": false }
  ]
}

The notebook kind is repeatable — ship as many notebooks as you like.

The notebook content manifest

notebooks-<slug>/manifest.json:

{
  "slug": "quickstart",
  "name": "Lakehouse quickstart",
  "description": "Read a managed table, run an analysis, and publish the result back."
}

notebook.py must be a valid marimo notebook file of at most 1 MB.

What happens at install

Installing the extension does not put notebooks into anyone's workspace. The install stores each notebook.py in organization-scoped storage and lists the notebook in the org's extension catalog. Users then pull the ones they want:

1. Analytics → Notebooks → From extension lists every notebook from the org's installed extensions.
2. Add copies the file into the current workspace environment and creates a workspace notebook entry.
3. From there it's a normal notebook — the extension is not consulted again, and later extension updates don't overwrite a user's copy.

Adding the same extension notebook twice is idempotent: the existing workspace copy is returned instead of a duplicate.

Writing extension notebooks that travel well

• Use the scrydon SDK for all data access (tables, knowledge, llm) — never hard-code URLs or credentials. See Marimo notebooks.
• Resolve tables by their logical names (the names your extension's data sources create) so the notebook works in any org that installed the extension.
• Guard optional extensions: llm.complete raises LlmNotConfiguredError when the org has no LLM extension — catch it and degrade gracefully.

Related

• Marimo notebooks — the notebook runtime and the scrydon SDK
• Extensions with extensions — the general extension archive format
• Extension versioning