Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/marimo-team/marimo/llms.txt

Use this file to discover all available pages before exploring further.

marimo provides multiple execution modes depending on your use case: interactive editing, read-only apps, or standalone scripts.

​
Execution Modes

marimo has three primary modes:
ModeCommandUse Case
Editmarimo editInteractive development with live editing
Runmarimo runShare as read-only web app
Scriptpython notebook.pyExecute as standard Python script

​
Edit Mode

Edit mode is the interactive development environment for creating and modifying notebooks.

​
Basic Usage

marimo edit notebook.py

​
Configuration Options

# Custom port and host
marimo edit notebook.py --port 8080 --host 0.0.0.0

# Run behind a proxy
marimo edit notebook.py --proxy https://myapp.com

# Custom base URL
marimo edit notebook.py --base-url /notebooks
Auto-reload when the file changes externally:
marimo edit notebook.py --watch
Useful when editing the .py file in another editor while viewing in marimo.
Start the server without opening a browser:
marimo edit notebook.py --headless

​
Session Management

# Auto-close inactive sessions after 120 seconds
marimo edit notebook.py --session-ttl 120

# Global timeout: shutdown server after N minutes of inactivity
marimo edit notebook.py --timeout 30

​
Run Mode

Run mode serves notebooks as read-only web applications - perfect for sharing dashboards and reports.

​
Basic Usage

marimo run notebook.py

​
Configuration Options

# Include source code in the app
marimo run notebook.py --include-code

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

# Custom port and host
marimo run notebook.py --port 8080 --host 0.0.0.0

# Session timeout (default: 120 seconds)
marimo run notebook.py --session-ttl 300

​
Passing Arguments to Notebooks

Pass command-line arguments to your notebook: 
marimo run notebook.py -- --data-file input.csv --threshold 0.95
Access these in your notebook: 
@app.cell
def __():
    import marimo as mo
    args = mo.cli_args()
    data_file = args.get("data_file")  # "input.csv"
    threshold = float(args.get("threshold", 0.9))  # 0.95
    return args, data_file, threshold
Arguments are automatically parsed into a dictionary. Use --arg-name value format.
When running multiple notebooks or a directory, marimo creates a gallery view: 
# Run all notebooks in a folder
marimo run ./my-notebooks

# Run specific notebooks
marimo run analysis.py dashboard.py report.py
Users can browse and switch between notebooks in the web interface.

​
Script Mode

Run notebooks as standalone Python scripts - no web server required.

​
Running as a Script

python notebook.py
Or make it executable: 
chmod +x notebook.py
./notebook.py

​
Script Behavior

  • Executes all cells in dependency order
  • Outputs printed to terminal
  • No web interface
  • Exits when complete
notebook.py
import marimo

app = marimo.App()

@app.cell
def __():
    print("This runs as a script!")
    result = 42
    return (result,)

@app.cell
def __(result):
    print(f"Result: {result}")
    return

if __name__ == "__main__":
    app.run()

​
Sandbox Mode

Run notebooks in isolated virtual environments with automatic dependency management.

​
Single-File Sandbox

# Auto-creates venv from PEP 723 metadata
marimo edit notebook.py --sandbox

# Also works with run mode
marimo run notebook.py --sandbox
Requires uv to be installed. marimo will automatically create an isolated environment with the dependencies declared in the notebook’s script metadata.

​
Multi-File Sandbox

When running a directory with --sandbox, each notebook gets its own isolated environment: 
marimo edit ./notebooks --sandbox
Multi-file sandbox mode requires the pyzmq package. Install with:
pip install marimo[sandbox]

​
Authentication

​
Token-Based Authentication

# Auto-generate random token
marimo edit notebook.py --token

# Use specific token
marimo edit notebook.py --token-password my-secret-token

# Read token from file
marimo edit notebook.py --token-password-file ~/.marimo-token

# Disable token (not recommended for remote access)
marimo edit notebook.py --no-token
Always use authentication when exposing marimo to untrusted networks.

​
CORS and Origins

Allow specific origins for CORS: 
# Single origin
marimo edit notebook.py --allow-origins https://example.com

# Multiple origins
marimo edit notebook.py --allow-origins https://app1.com --allow-origins https://app2.com

# Allow all origins (use with caution)
marimo edit notebook.py --allow-origins "*"

​
Development Mode

Enable debug logging and auto-reload: 
marimo -d edit notebook.py

# Equivalent to:
marimo --development-mode edit notebook.py

​
Global Options

These options work with any marimo command: 
# Set log level
marimo --log-level DEBUG edit notebook.py

# Suppress output
marimo --quiet run notebook.py

# Auto-accept prompts
marimo --yes convert notebook.ipynb

​
Environment Variables

​
Skip Update Check

export MARIMO_SKIP_UPDATE_CHECK=1
marimo edit notebook.py

​
Custom Configuration

# Use custom config directory
export MARIMO_CONFIG_DIR=~/.config/marimo-custom
marimo edit notebook.py

​
Performance Tips

Use --skip-update-check to skip version checking:
marimo edit notebook.py --skip-update-check
Set shorter TTL for automatic session cleanup:
marimo run notebook.py --session-ttl 60
Install watchdog for more efficient file watching:
pip install watchdog
marimo edit notebook.py --watch

​
Checking Notebooks

Lint and format notebooks before running: 
# Check for issues
marimo check notebook.py

# Auto-fix issues
marimo check notebook.py --fix

# Check all notebooks
marimo check **/*.py

# Strict mode (warnings = errors)
marimo check notebook.py --strict

​
Next Steps

Sharing Notebooks

Export and deploy your notebooks

Package Management

Manage dependencies automatically

Build docs developers (and LLMs) love

Get started for freeTalk to us