Skip to main content

Import ObservableHQ notebooks

Notebook.from_observablehq reads a public notebook from the ObservableHQ document API at https://api.observablehq.com/document/<notebook> and returns a Notebook definition. Call view() to render it. The notebook keeps its cell languages and standard-library version. Notebook Kit's notebooks download command reads the same record.

Imported notebooks and remote modules run with the host page's browser privileges. Review the trust boundary in Browser execution.

import observablejs as obs

notebook = obs.Notebook.from_observablehq("@observablehq/plot-scatterplot/2")
full_view = notebook.view()
full_view

The specifier can be an ObservableHQ URL, a notebook slug, a notebook id, or a document API URL. Use timeout to bound the fetch.

obs.Notebook.from_observablehq("https://observablehq.com/@d3/bar-chart")
obs.Notebook.from_observablehq("@d3/bar-chart", timeout=10)

The constructor fetches notebook source on every call. To skip that request during a build or test, save the response once and pass it to Notebook.from_observablehq_document(...). Imports, uploaded files, libraries, and datasets may still load from the network when the view renders.

Keep imported notebooks pinned​

Append @version to a notebook URL or id to request an exact source revision. Dependencies with explicit revisions keep those revisions. For archived classic records, retain resolutions together with id and version to preserve the declared dependency pins. These records survive HTML export and reimport. Unpinned imports resolve when the view loads them.

For an archived node collection, pass {"nodes": nodes}. Native Notebook Kit models use {"cells": cells, "stdlib": "2"} and retain each cell's language. When a record's resolutions mark a cell unsupported_mode, the API has replaced that cell's language and the constructor raises ValueError. Load the notebook's Notebook Kit HTML with Notebook.from_html() instead. Notebook imports load through Python, so the kernel must remain connected.

Override variables​

Pass variables to override notebook-defined values from Python.

document = {
    "id": "1234567890abcdef",
    "version": 7,
    "title": "Report",
    "nodes": [
        {"id": 1, "mode": "js", "name": "answer", "value": "answer = 42"},
        {"id": 2, "mode": "js", "value": "md`Answer: ${answer}`"},
    ],
}
notebook = obs.Notebook.from_observablehq_document(
    document,
    variables={"answer": 100},
)

Remote uploaded files become URL-backed file records. Explicit files override fetched files with the same name.

Cell language and standard library​

Classic node documents use Observable JavaScript cells and default to the classic standard library, which includes require. Native notebook models preserve JavaScript, TypeScript, and Observable JavaScript cells and default to Notebook Kit's current library. An explicit stdlib value overrides that default. Cell language and standard-library choice survive to_notebook_html() round trips. See Browser execution and network access.

See Source constructors for the constructor contracts, error behavior, and source-revision import resolution.