Skip to content

WebAssembly Notebooks

marimo lets you execute notebooks entirely in the browser, without a backend executing Python. marimo notebooks that run entirely in the browser are called WebAssembly notebooks, or WASM notebooks for short.

Check for WebAssembly compatibility

Not all notebooks are compatible with WebAssembly. If you use coding agents like Claude Code, you can use our official skills to automatically check for WebAssembly compatibility of your notebooks.

Sharing interactive previews of GitHub notebooks

Read the molab docs to learn how to share WebAssembly previews of notebooks hosted on GitHub, and how to embed WebAssembly notebooks in other webpages such as documentation.

WASM notebooks have three benefits compared to notebooks hosted using a traditional client-server model. WASM notebooks:

  1. eliminate the need to install Python, making scientific computing accessible;
  2. eliminate the cost and complexity of deploying backend infrastructure, making it easy to share notebooks;
  3. eliminate network requests to a remote Python runner, making development feel snappy.

When should I use WASM notebooks?

WASM notebooks are excellent for sharing your work, quickly experimenting with code and models, doing lightweight data exploration, authoring blog posts, tutorials, and educational materials, and even building tools. For notebooks that do heavy computation, use marimo on your own machine/server or on molab.

Try it! Try editing the below notebook (your browser, not a backend server, is executing it!)

This feature is powered by Pyodide, a port of Python to WebAssembly that enables browsers to run Python code.

Creating WASM notebooks

marimo provides three ways to create and share WASM notebooks:

  1. molab. Our free cloud-hosted marimo notebook service. Append /wasm to GitHub previews to create interactive previews of notebooks hosted on GitHub. molab also allows embedding WebAssembly notebooks in other webpages (we do this throughout these docs).
  2. Export to WASM HTML, which you can host on GitHub Pages or self-host. You can also use a GitHub action.
  3. Try our ephemeral WebAssembly playground; unlike molab, notebooks created at the playground are not saved.

Packages

Use --sandbox for seamless package installation

If you're developing notebooks locally that you plan to share as WASM notebooks, create them with marimo edit --sandbox notebook.py. This inlines your package dependencies into the notebook file, ensuring they are seamlessly installed in our WebAssembly environment. See package management for more details.

Rendering performance

To make sure markdown and other elements render quickly: make sure to put import marimo as mo in its own cell, with no other lines of code.

WASM notebooks come with many packages pre-installed, including NumPy, SciPy, scikit-learn, pandas, and matplotlib; see Pyodide's documentation for a full list.

If you attempt to import a package that is not installed, marimo will attempt to automatically install it for you. To manually install packages, use micropip:

In one cell, import micropip:

import micropip

In the next cell, install packages:

await micropip.install("plotly")
import plotly

Supported packages

All packages with pure Python wheels on PyPI are supported, as well as additional packages like NumPy, SciPy, scikit-learn, duckdb, polars, and more. For a full list of supported packages, see Pyodide's documentation on supported packages.

If you want a package to be supported, consider filing an issue.

Including data

For notebooks exported to WASM HTML. To include data files in notebooks exported to WASM HTML, place them in a public/ folder in the same directory as your notebook. When you export to WASM HTML, the public folder will be copied to the export directory.

In order to access data both locally and when an exported notebook runs via WebAssembly (e.g., hosted on GitHub Pages), use mo.notebook_location() to construct the path to your data:

import polars as pl

path_to_csv = mo.notebook_location() / "public" / "data.csv"
df = pl.read_csv(str(path_to_csv))
df.head()

Fetching data files from the web. Instead of bundling data files with your notebook, you can host data files on the web and fetch them in your notebook. Depending on where your files are hosted, you may need to use a CORS Proxy; see the Pyodide documentation for more details.

molab notebooks. When opening a notebook from GitHub on molab, all the files in the GitHub repo are made available to your notebook.

Detecting WebAssembly

To check if your notebook is running in a WebAssembly environment, use:

import sys

if "pyodide" in sys.modules:
    # Running in WebAssembly
    ...
else:
    # Running locally
    ...

This is useful for branching logic, such as using micropip for package installation in WASM while using standard imports locally.

Limitations

While WASM notebooks let you share marimo notebooks seamlessly, they have some limitations.

Packages. Many but not all packages are supported. All packages with pure Python wheels on PyPI are supported, as well as additional packages like NumPy, SciPy, scikit-learn, duckdb, polars, and more. For a full list of supported packages, see Pyodide's documentation on supported packages.

If you want a package to be supported, consider filing an issue.

PDB. PDB is not currently supported.

Threading and multi-processing. WASM notebooks do not support multithreading and multiprocessing. This may be fixed in the future.

Memory. WASM notebooks have a memory limit of 2GB; this may be increased in the future. If memory consumption is an issue, try offloading memory-intensive computations to hosted APIs or precomputing expensive operations.

Browser support

WASM notebooks are supported in the latest versions of Chrome, Firefox, Edge, and Safari.

Chrome is the recommended browser for WASM notebooks as it seems to have the best performance and compatibility.