Deploy with WebAssembly

Deploy marimo notebooks that run entirely in the browser using WebAssembly (WASM). No Python backend required—notebooks execute directly in the user’s browser via Pyodide, a port of CPython to WebAssembly.

Why WASM Deployment?

WASM notebooks offer unique advantages:

Zero Infrastructure

No backend servers to maintain, configure, or pay for. Host static files anywhere.

Instant Access

Users don’t need Python installed. Works on any device with a modern browser.

Low Latency

No network requests to remote servers. All computation happens locally.

Easy Sharing

Share via link, embed in documentation, or publish to GitHub Pages.

WASM notebooks are ideal for: interactive documentation, educational materials, blog posts, lightweight data exploration, quick prototyping, and shareable tools. For heavy computation or large datasets, use a traditional backend.

Deployment Methods

marimo offers three ways to deploy WASM notebooks:

1. Export to WASM HTML

Generate a standalone HTML file with embedded WebAssembly:

marimo export html-wasm notebook.py -o notebook.html

The generated file:

✅ Runs completely offline
✅ Contains your entire notebook
✅ Includes all marimo dependencies
✅ Can be hosted anywhere (GitHub Pages, S3, Netlify, etc.)

Export notebook

marimo export html-wasm my_app.py -o index.html

Host the HTML file

Upload to any static hosting service:

# GitHub Pages
git add index.html
git commit -m "Add WASM app"
git push

# Or use the gh-pages branch
npx gh-pages -d . -f index.html

Share the URL

Your notebook is now live and executable in any browser!

2. Online Playground

Use marimo.new for instant WASM notebooks:

No installation required: Create and run notebooks in your browser
Share via link: Get a shareable URL instantly
No login needed: Start coding immediately
Great for demos: Embed in documentation or presentations

Simply visit https://marimo.new and start coding!

Load from GitHub: In the playground, use File → Open from URL to load any notebook from a GitHub URL. Perfect for trying out examples!

3. Community Cloud

Deploy to marimo.io for managed WASM hosting:

Workspace management: Organize notebooks in collections
Public or private: Control access with email-based authorization
Nice URLs: Get shareable links like https://marimo.app/@username/notebook
Free tier: Host notebooks at no cost

Working with Packages

Pre-installed Packages

WASM notebooks come with many packages pre-installed:

Scientific: NumPy, SciPy, scikit-learn, pandas
Visualization: matplotlib, altair, plotly
Data: polars, DuckDB, pyarrow
ML: scikit-learn, xgboost (selected packages)

See Pyodide’s package list for the full catalog.

Installing Additional Packages

Use micropip to install packages at runtime:

import micropip

Package compatibility: Only pure Python packages or packages with pre-built WebAssembly wheels work in WASM. Packages with native C extensions not compiled for Pyodide won’t work.

Auto-install on Import

marimo automatically attempts to install missing packages:

import marimo as mo

# marimo will try to auto-install if not present
import altair as alt
import vega_datasets

data = vega_datasets.data.cars()
mo.ui.altair_chart(alt.Chart(data).mark_point())

Performance tip: Put import marimo as mo in its own cell with no other code. This ensures marimo loads quickly and the UI renders immediately.

Using Script Metadata

Declare dependencies using PEP 723 inline metadata:

# /// script
# dependencies = [
#   "altair",
#   "pandas",
#   "vega_datasets",
# ]
# ///

import marimo as mo
import altair as alt
import pandas as pd

marimo reads this metadata and pre-installs dependencies when the WASM notebook loads.

Capabilities and Limitations

What Works

✅ Full marimo reactivity: UI elements, reactive execution, dataflow ✅ Most Python: Standard library, pure Python packages ✅ Data manipulation: pandas, polars, NumPy, DuckDB ✅ Visualization: matplotlib, altair, plotly, seaborn ✅ File operations: Read/write using browser’s virtual filesystem ✅ API requests: Fetch data from APIs (with CORS support) ✅ Machine learning: scikit-learn, lightweight models

Limitations

❌ Heavy computation: Limited by browser performance ❌ Large datasets: Browser memory constraints (~2GB typically) ❌ Native extensions: C/C++ packages without WASM builds ❌ System calls: No real filesystem, subprocess, etc. ❌ Long-running jobs: Browser tabs can timeout ❌ Networking: Subject to CORS restrictions

For these use cases, deploy with a traditional Python backend using marimo run or programmatic deployment.

File Operations

Reading Files

WASM notebooks use a virtual filesystem:

import marimo as mo

# Upload file via UI
file_upload = mo.ui.file()
file_upload

Access uploaded files:

import pandas as pd
import io

if file_upload.value:
    # file_upload.value is bytes
    df = pd.read_csv(io.BytesIO(file_upload.value[0].contents))
    mo.ui.table(df)

Writing Files

Write to virtual filesystem and download:

import marimo as mo
import pandas as pd

# Create some data
df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})

# Write to virtual filesystem
df.to_csv("/tmp/output.csv", index=False)

# Create download button
with open("/tmp/output.csv", "rb") as f:
    data = f.read()

mo.download(
    data=data,
    filename="output.csv",
    label="Download CSV"
)

Embedding WASM Notebooks

Embed interactive notebooks in any webpage:

iframe Embed

<!-- Embed playground notebook -->
<iframe 
  src="https://marimo.app/l/c4hgb5?embed=true" 
  width="100%" 
  height="500" 
  frameborder="0"
></iframe>

Self-hosted Embed

Host your exported HTML and embed:

<iframe 
  src="https://your-site.com/notebook.html" 
  width="100%" 
  height="600"
  frameborder="0"
></iframe>

Use embed=true query parameter on playground links to hide the header and provide a cleaner embed experience.

GitHub Pages Deployment

Automate deployment to GitHub Pages with GitHub Actions:

Manual Deployment

# Export notebook
marimo export html-wasm app.py -o index.html

# Deploy to gh-pages branch
git add index.html
git commit -m "Deploy WASM app"
git push origin gh-pages

Automated with Actions

Create .github/workflows/deploy-wasm.yml:

name: Deploy WASM Notebook

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v3
      
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install marimo
        run: pip install marimo
      
      - name: Export to WASM
        run: marimo export html-wasm app.py -o index.html
      
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: .
          publish_branch: gh-pages

See the GitHub Pages guide for detailed instructions.

Advanced Configuration

Custom Loading Screen

Customize the loading experience in exported HTML:

# In your notebook
import marimo as mo

mo.app(
    app_title="My WASM App",
    layout_file="custom_layout.py"  # Custom UI layout
)

Performance Optimization

Minimize dependencies

Only import what you need. Fewer packages = faster load time.

Use lazy imports

Import heavy packages only in cells that use them.

Optimize data size

Keep datasets small. Consider loading data from URLs instead of embedding.

Cache computations

Use @functools.cache for expensive operations.

Loading External Data

Fetch data from APIs instead of embedding:

import marimo as mo
import pandas as pd

# Load from URL (subject to CORS)
url = "https://raw.githubusercontent.com/user/repo/main/data.csv"
df = pd.read_csv(url)

mo.ui.table(df)

CORS restrictions: External data sources must have CORS headers that allow browser access. Many APIs don’t support this. Consider hosting data on CORS-enabled services or using a proxy.

Use Cases

Interactive Documentation

import marimo as mo
import numpy as np
import matplotlib.pyplot as plt

mo.md("""
# Fourier Transform Demo

Adjust the parameters to see how they affect the signal:
""")

frequency = mo.ui.slider(1, 10, value=5, label="Frequency")
frequency

Educational Materials

Teach concepts with interactive examples:

import marimo as mo

mo.md("""# Linear Regression

Drag the slider to change the slope:
""")

slope = mo.ui.slider(-5, 5, step=0.1, value=1, label="Slope")
slope

Data Exploration Tools

Build shareable data apps:

import marimo as mo
import altair as alt

column = mo.ui.dropdown(
    options=df.columns.tolist(),
    value=df.columns[0],
    label="Select column"
)

chart = alt.Chart(df).mark_bar().encode(x=column.value, y='count()')
mo.ui.altair_chart(chart)

Security Considerations

WASM notebooks run in the user’s browser:

Code visibility: All code is visible to users (view source)
No secrets: Don’t embed API keys or passwords
Client-side only: No access to server resources
Sandboxed: Browser security model provides isolation
CORS applies: Can only fetch from CORS-enabled sources

For applications requiring secrets or server-side logic, use traditional deployment with marimo run.

Troubleshooting

Package Not Found

# Try manual installation
import micropip
await micropip.install("package-name")

Slow Loading

Reduce number of dependencies
Use lighter-weight alternatives (e.g., polars instead of pandas)
Split into multiple smaller notebooks

Memory Issues

Reduce dataset size
Process data in chunks
Use more efficient data structures

CORS Errors

When loading external data:

Use CORS-enabled APIs
Host data on CORS-friendly services (GitHub raw, jsDelivr)
Consider embedding small datasets directly

Examples

Explore WASM notebooks:

marimo Gallery - Community-created notebooks
marimo Playground - Try creating your own
Documentation Examples - Embedded interactive examples

Best Practices

For successful WASM deployment:

Keep it lightweight: Fewer dependencies, smaller data
Test in browser first: Use playground or local export
Provide loading feedback: Users expect some initial load time
Handle errors gracefully: Check for package availability
Document requirements: Let users know what browser/features needed
Use progressive enhancement: Start with core functionality
Optimize for mobile: Many users browse on phones

Next Steps

Export to WASM

Learn more about exporting options

Playground

Create WASM notebooks instantly

GitHub Pages

Automate deployment to GitHub Pages

Community Cloud

Deploy to managed WASM hosting

Get Started

Core Features

Working with Notebooks

Deployment

Data & Visualization

Editor Features

Advanced Topics

​Deploy with WebAssembly

​Why WASM Deployment?

Zero Infrastructure

Instant Access

Low Latency

Easy Sharing

​Deployment Methods

​1. Export to WASM HTML

​2. Online Playground

​3. Community Cloud

​Working with Packages

​Pre-installed Packages

​Installing Additional Packages

​Auto-install on Import

​Using Script Metadata

​Capabilities and Limitations

​What Works

​Limitations

​File Operations

​Reading Files

​Writing Files

​Embedding WASM Notebooks

​iframe Embed

​Self-hosted Embed

​GitHub Pages Deployment

​Manual Deployment

​Automated with Actions

​Advanced Configuration

​Custom Loading Screen

​Performance Optimization

​Loading External Data

​Use Cases

​Interactive Documentation

​Educational Materials

​Data Exploration Tools

​Security Considerations

​Troubleshooting

​Package Not Found

​Slow Loading

​Memory Issues

​CORS Errors

​Examples

​Best Practices

​Next Steps

Export to WASM

Playground

GitHub Pages

Community Cloud

Build docs developers (and LLMs) love

Deploy with WebAssembly

Why WASM Deployment?

Deployment Methods

1. Export to WASM HTML

2. Online Playground

3. Community Cloud

Working with Packages

Pre-installed Packages

Installing Additional Packages

Auto-install on Import

Using Script Metadata

Capabilities and Limitations

What Works

Limitations

File Operations

Reading Files

Writing Files

Embedding WASM Notebooks

iframe Embed

Self-hosted Embed

GitHub Pages Deployment

Manual Deployment

Automated with Actions

Advanced Configuration

Custom Loading Screen

Performance Optimization

Loading External Data

Use Cases

Interactive Documentation

Educational Materials

Data Exploration Tools

Security Considerations

Troubleshooting

Package Not Found

Slow Loading

Memory Issues

CORS Errors

Examples

Best Practices

Next Steps