Sharing Notebooks

Export, deploy, and share marimo notebooks in various formats

marimo makes it easy to share your work - export to static formats, deploy as web apps, or collaborate via version control.

Export Formats

marimo can export notebooks to multiple formats:

Format	Use Case	Command
HTML	Static web page with outputs	marimo export html
WASM HTML	Interactive, runs in browser	marimo export html-wasm
PDF	Printable reports	marimo export pdf
Script	Executable Python script	marimo export script
Markdown	Documentation	marimo export md
Jupyter	.ipynb format	marimo export ipynb

Exporting to HTML

Create standalone HTML files with embedded outputs.

Basic Export

marimo export html notebook.py -o notebook.html

The exported HTML includes:

• All cell outputs (plots, tables, text)
• Optional source code
• Styling and formatting

Options

Include code

marimo export html notebook.py -o output.html --include-code

Passing Arguments

Export with custom CLI arguments:

marimo export html dashboard.py -o dashboard.html -- --date 2024-03-15 --region west

WebAssembly (WASM) Export

Export fully interactive notebooks that run entirely in the browser using Pyodide.

Basic WASM Export

# Read-only mode (default)
marimo export html-wasm notebook.py -o output.html --mode run

# Editable mode
marimo export html-wasm notebook.py -o output.html --mode edit

Features

Complete Self-Contained

The exported HTML includes:

• Python runtime (via Pyodide)
• All notebook code
• Required assets
• No server needed!

Show/Hide Code

# Show code by default
marimo export html-wasm notebook.py -o app.html --show-code

# Hide code by default (users can toggle)
marimo export html-wasm notebook.py -o app.html --no-show-code

Cloudflare Workers

Generate Cloudflare Worker config for easy deployment:

marimo export html-wasm notebook.py -o dist/index.html --include-cloudflare

Creates index.js and wrangler.jsonc for deployment.

Serving WASM Files

WASM exports must be served via HTTP, not opened directly (file:// won’t work).

# Simple HTTP server
python -m http.server --directory output_dir

# Then open http://localhost:8000

Package Compatibility

Pyodide supports most pure-Python packages. Some packages with C extensions may not work. Check the Pyodide package list.

Exporting to PDF

Create printable PDF reports from your notebooks.

Basic PDF Export

marimo export pdf notebook.py -o report.pdf

Options

Include outputs and code

marimo export pdf notebook.py -o report.pdf --include-outputs --include-inputs

Advanced Configuration

Rasterization Options

For better rendering of interactive widgets:

# Custom scale for screenshots
marimo export pdf notebook.py -o report.pdf --raster-scale 2.0

# Use live server for rasterization (better for slides)
marimo export pdf notebook.py -o slides.pdf --as=slides --raster-server=live

Export Method

# Use WebPDF (Chromium-based, default)
marimo export pdf notebook.py -o report.pdf --webpdf

# Try standard PDF first, fallback to WebPDF
marimo export pdf notebook.py -o report.pdf --no-webpdf

PDF export requires nbformat and nbconvert packages:

pip install nbformat nbconvert[webpdf]

Export to Script

Convert to a flat Python script in topological order.

marimo export script notebook.py -o script.py

The exported script:

• Executes cells in dependency order
• Removes marimo-specific decorators
• Can be run as a standard Python script

python script.py

Export to Markdown

Export as markdown with code fences:

marimo export md notebook.py -o documentation.md

Generated markdown:

# My Analysis

```python
import pandas as pd
df = pd.read_csv("data.csv")

result = df.groupby("category").mean()
print(result)

## Export to Jupyter

Convert marimo notebooks to `.ipynb` format:

```bash
# Without outputs
marimo export ipynb notebook.py -o notebook.ipynb

# With outputs (runs the notebook)
marimo export ipynb notebook.py -o notebook.ipynb --include-outputs

# Custom cell order
marimo export ipynb notebook.py -o notebook.ipynb --sort top-down

Requires nbformat:

pip install nbformat

Deploying as Web Apps

Running on a Server

Deploy marimo notebooks as web applications:

# Bind to all interfaces
marimo run notebook.py --host 0.0.0.0 --port 8080

# With authentication
marimo run notebook.py --host 0.0.0.0 --token-password secret123

# Behind a reverse proxy
marimo run notebook.py --host 127.0.0.1 --proxy https://myapp.com

Docker Deployment

Example Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY notebook.py .

EXPOSE 8080

CMD ["marimo", "run", "notebook.py", "--host", "0.0.0.0", "--port", "8080", "--headless"]

Build and run:

docker build -t my-marimo-app .
docker run -p 8080:8080 my-marimo-app

Cloud Platforms

Deploy to Cloudflare

Use WASM export with --include-cloudflare flag, then:

cd output_dir
wrangler deploy

Deploy to Heroku

Create Procfile:

web: marimo run notebook.py --host 0.0.0.0 --port $PORT --headless

Version Control

marimo notebooks are pure Python files, making them ideal for Git.

Best Practices

1. Track .py files

   Commit your notebook .py files directly:

   git add notebook.py
   git commit -m "Add data analysis notebook"
   
2. Readable diffs

   Since notebooks are Python code, diffs are human-readable:

   @app.cell
   def __(df):
   -   result = df.mean()
   +   result = df.median()
       return (result,)
   
3. Ignore outputs

   No need to track outputs - they’re generated at runtime:

   .gitignore

   # No .ipynb_checkpoints needed!
   __pycache__/
   .marimo.cache/
   

Collaboration

Workflow for teams:

1. Create a branch for your analysis
2. Edit the notebook with marimo edit
3. Commit changes to the .py file
4. Create pull request with readable diffs
5. Review code like any Python file
6. Merge when approved

marimo’s reactive execution ensures notebooks always run top-to-bottom, eliminating hidden state issues common in Jupyter.

Sharing on GitHub

README Examples

Reference notebooks in your README:

README.md

# My Project

Explore the analysis:

```bash
marimo edit analysis.ipynb

Or run as a dashboard:

marimo run dashboard.py

### GitHub Actions

Automate notebook exports:

```yaml .github/workflows/export.yml
name: Export Notebooks

on: [push]

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: pip install marimo nbformat nbconvert
      - run: marimo export html notebook.py -o output.html
      - uses: actions/upload-artifact@v3
        with:
          name: exported-html
          path: output.html

Next Steps

Converting from Jupyter

Migrate existing .ipynb notebooks

Package Management

Manage dependencies with PEP 723