marimo run

Run marimo notebooks as read-only web applications

marimo run

Run one or more marimo notebooks as read-only web applications. Perfect for sharing interactive dashboards and apps.

Usage

marimo run NAME [NAME...] [OPTIONS] [-- ARGS...]

Arguments

NAME - Path to notebook file(s) or directory(ies) to run (required)

• Can specify multiple files or directories
• If a directory is provided, all marimo notebooks in it will be available
• Supports URLs for remote notebooks
• When multiple paths are provided, creates a gallery view

ARGS - Arguments to pass to the notebook (after --)

• All arguments after -- are passed to the notebook’s sys.argv

Options

Server Configuration

-p, —port PORT - Port to attach to

• Type: Integer
• Default: Auto-assigned

—host HOST - Host to attach to

• Type: String
• Default: 127.0.0.1

—proxy PROXY - Address of reverse proxy

• Type: String

—base-url URL - Base URL for the server (should start with /)

• Type: String
• Default: ""

Browser & UI

—headless - Don’t launch a browser

• Type: Flag
• Default: False

—include-code - Include notebook code in the app

• Type: Flag
• Default: False
• When enabled, users can view the source code

Authentication

—token / —no-token - Use token for authentication

• Type: Flag
• Default: False

—token-password PASSWORD - Use a specific token for authentication

• Type: String

—token-password-file FILE - Path to file containing token password, or - for stdin

• Type: String

Security & CORS

—allow-origins ORIGIN - Allowed origins for CORS

• Type: String (can be repeated)

—trusted / —untrusted - Run notebooks hosted remotely

• If --untrusted, runs marimo in a Docker container

Development Features

—watch - Watch files for changes and reload the app

• Type: Flag
• Default: False
• Uses watchdog if installed, otherwise polls every 1 second

—skew-protection / —no-skew-protection - Enable skew protection middleware

• Type: Flag
• Default: True

Console & Debugging

—redirect-console-to-browser - Redirect console logs to browser console

• Type: Flag
• Default: False

Validation

—check / —no-check - Perform static check of notebook before running

• Type: Flag
• Default: True
• Validates notebook for errors before starting

Sandbox & Isolation

—sandbox / —no-sandbox - Run in an isolated virtual environment

• Type: Flag
• For multiple files/directories, uses IPC kernels with per-notebook sandboxed environments
• Requires uv and pyzmq

Session Management

—session-ttl SECONDS - Seconds to wait before closing a session on websocket disconnect

• Type: Integer
• Default: 120

Examples

Basic Usage

# Run a single notebook
marimo run notebook.py

# Run multiple notebooks (creates a gallery)
marimo run app1.py app2.py app3.py

# Run all notebooks in a directory
marimo run notebooks/

# Run notebooks from multiple directories
marimo run folder1 folder2

Custom Server Configuration

# Run on a specific port
marimo run app.py --port 8080

# Run on all network interfaces
marimo run app.py --host 0.0.0.0 --port 8080

# Run headless (no browser)
marimo run app.py --headless

Including Code

# Show notebook code to users
marimo run app.py --include-code

Authentication

# Enable token authentication
marimo run app.py --token

# Use a specific token
marimo run app.py --token-password mysecrettoken

Development Workflow

# Watch for changes and auto-reload
marimo run app.py --watch

# Watch with code visible
marimo run app.py --watch --include-code

# Disable pre-run checks for faster iteration
marimo run app.py --no-check

Remote Notebooks

# Run a remote notebook
marimo run https://raw.githubusercontent.com/user/repo/main/app.py

# Trust remote notebooks automatically
marimo run https://example.com/app.py --trusted

Passing Arguments to Notebook

# Pass arguments to the notebook
marimo run app.py -- --config config.json --verbose

# With multiple notebooks (arguments apply to all)
marimo run app1.py app2.py -- --shared-arg value

Access arguments in your notebook:

import sys
import marimo as mo

# sys.argv contains the arguments after --
config_file = sys.argv[sys.argv.index('--config') + 1]

Gallery Mode

# Create a gallery of notebooks
marimo run dashboards/ analytics/

# Watch a directory for new notebooks
marimo run dashboards/ --watch

Sandbox Mode

# Run in isolated environment (single notebook)
marimo run app.py --sandbox

# Run gallery with per-notebook sandboxes
marimo run notebooks/ --sandbox

Production Deployment

# Run headless with authentication on a specific port
marimo run app.py \
  --host 0.0.0.0 \
  --port 8080 \
  --headless \
  --token-password-file /secrets/token \
  --no-check

# Behind a reverse proxy
marimo run app.py \
  --host 127.0.0.1 \
  --port 8080 \
  --headless \
  --base-url /apps/myapp \
  --proxy https://example.com

CORS Configuration

# Allow specific origins
marimo run app.py --allow-origins https://example.com

# Allow multiple origins
marimo run app.py \
  --allow-origins https://example.com \
  --allow-origins https://other.com

Console Output

# Redirect Python print() to browser console
marimo run app.py --redirect-console-to-browser

Tips

• Use --watch during development to see changes immediately
• Enable --include-code for educational or open-source apps
• Use --sandbox for untrusted notebooks or to isolate dependencies
• For production, combine --headless, --host 0.0.0.0, and --token
• Gallery mode is great for creating dashboards or app collections

Related Commands

• marimo edit - Edit notebooks interactively
• marimo export - Export notebooks to static formats