Skip to content

Self-host WebAssembly notebooks

As an alternative to GitHub Pages, it is possible to self-host exported WebAssembly notebooks:

  • Export to WASM HTML.
  • Serve the exported file over HTTP.
  • Serve the assets in the assets directory, next to the HTML file.
  • Possibly configure your web server to support serving application/wasm/ files with the correct headers.

Exporting for offline use

Use --offline to download the Python runtime and notebook packages alongside the exported HTML.

Offline export requires Playwright for Python and its Chromium browser. Use the Python environment where marimo is installed for all three commands:

python -m pip install playwright
python -m playwright install chromium
python -m marimo export html-wasm notebook.py -o dist --offline

The export requires internet access. Playwright runs Pyodide to resolve browser-compatible dependencies without executing notebook cells. The result can be served from a local HTTP server or copied to a static host:

dist/
├── index.html
├── assets/
├── pyodide/
├── lockfile/
└── packages/

The HTML uses relative URLs for the bundled runtime, lockfile, and package index, so the directory can be moved to another host or URL prefix. The packages directory includes transitive dependencies, packages inferred from imports that are available in Pyodide, and dependencies declared in inline script metadata. Declare PyPI dependencies in that metadata, including packages installed dynamically by the notebook.

--offline bundles Python dependencies. Data files, remote API calls, and JavaScript assets fetched by notebook code or widgets still need local alternatives. Serve the export over HTTP even when using it offline.

Without --offline, the browser uses the default hosted Python runtime and package sources.