marimo

Welcome to marimo! Getting started:

• marimo tutorial intro

Example usage:

• marimo edit: create or edit notebooks
• marimo edit notebook.py: create or edit a notebook called notebook.py
• marimo run notebook.py: run a notebook as a read-only app
• marimo tutorial --help: list tutorials

Usage:

marimo [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
--version	boolean	Show the version and exit.	False
-l, --log-level	choice (DEBUG | INFO | WARN | ERROR | CRITICAL)	Choose logging level.	WARN
-q, --quiet	boolean	Suppress standard out.	False
-y, --yes	boolean	Automatic yes to prompts, running non-interactively.	False
-d, --development-mode	boolean	Run in development mode; enables debug logs and server autoreload.	False
--help	boolean	Show this message and exit.	False

marimo config

Various commands for the marimo config.

Usage:

marimo config [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

marimo config describe

Describe the marimo config.

Usage:

marimo config describe [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

marimo config show

Show the marimo config.

Usage:

marimo config show [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

marimo convert

Convert a Jupyter notebook or Markdown file to a marimo notebook.

The argument may be either a path to a local .ipynb/.md file, or an .ipynb/.md file hosted on GitHub.

Example usage:

marimo convert your_nb.ipynb -o your_nb.py

or

marimo convert your_nb.md -o your_nb.py

Jupyter notebook conversion will strip out all outputs. Markdown cell conversion with occur on the presence of {python} code fences. After conversion, you can open the notebook in the editor:

marimo edit your_nb.py

Since marimo is different from traditional notebooks, once in the editor, you may need to fix errors like multiple definition errors or cycle errors.

Usage:

marimo convert [OPTIONS] FILENAME

Options:

Name	Type	Description	Default
-o, --output	path	Output file to save the converted notebook to. If not provided, the converted notebook will be printed to stdout.	None
--help	boolean	Show this message and exit.	False

marimo edit

Create or edit notebooks.

• marimo edit: Start the marimo notebook server
• marimo edit notebook.py: Create or edit notebook.py

Usage:

marimo edit [OPTIONS] [NAME] [ARGS]...

Options:

Name	Type	Description	Default
-p, --port	integer	Port to attach to.	None
--host	text	Host to attach to.	127.0.0.1
--proxy	text	Address of reverse proxy.	None
--headless	boolean	Don't launch a browser.	False
--token / --no-token	boolean	Use a token for authentication. This enables session-based authentication. A random token will be generated if --token-password is not set. If --no-token is set, session-based authentication will not be used.	True
--token-password	text	Use a specific token for authentication. This enables session-based authentication. A random token will be generated if not set.	None
--base-url	text	Base URL for the server. Should start with a /.	``
--allow-origins	text	Allowed origins for CORS. Can be repeated. Use * for all origins.	None
--skip-update-check	boolean	Don't check if a new version of marimo is available for download.	False
--sandbox	boolean	Run the command in an isolated virtual environment using uv run --isolated. Requires uv.	False
--help	boolean	Show this message and exit.	False

marimo env

Print out environment information for debugging purposes.

Usage:

marimo env [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

marimo export

Export a notebook to various formats.

Usage:

marimo export [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

marimo export html

Run a notebook and export it as an HTML file.

Example:

marimo export html notebook.py -o notebook.html

Optionally pass CLI args to the notebook:

marimo export html notebook.py -o notebook.html -- -arg1 foo -arg2 bar

Usage:

marimo export html [OPTIONS] NAME [ARGS]...

Options:

Name	Type	Description	Default
--include-code / --no-include-code	boolean	Include notebook code in the exported HTML file.	True
--watch / --no-watch	boolean	Watch notebook for changes and regenerate the output on modification. If watchdog is installed, it will be used to watch the file. Otherwise, file watcher will poll the file every 1s.	False
-o, --output	path	Output file to save the HTML to. If not provided, the HTML will be printed to stdout.	None
--sandbox	boolean	Run the command in an isolated virtual environment using uv run --isolated. Requires uv.	False
--help	boolean	Show this message and exit.	False

marimo export html-wasm

Export a notebook as a WASM-powered standalone HTML file.

Example:

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

The exported HTML file will run the notebook using WebAssembly, making it completely self-contained and executable in the browser. This lets you share interactive notebooks on the web without setting up infrastructure to run Python code.

The exported notebook runs using Pyodide, which supports most but not all Python packages. To learn more, see the Pyodide documentation.

In order for this file to be able to run, it must be served over HTTP, and cannot be opened directly from the file system (e.g. file://).

Usage:

marimo export html-wasm [OPTIONS] NAME

Options:

Name	Type	Description	Default
-o, --output	path	Output directory to save the HTML to.	_required
--mode	choice (edit | run)	Whether the notebook code should be editable or readonly.	run
--show-code / --no-show-code	boolean	Whether to show code by default in the exported HTML file; only relevant for run mode.	False
--help	boolean	Show this message and exit.	False

marimo export ipynb

Export a marimo notebook as a Jupyter notebook in topological order.

Example:

marimo export ipynb notebook.py -o notebook.ipynb

Watch for changes and regenerate the script on modification:

marimo export ipynb notebook.py -o notebook.ipynb --watch

Requires nbformat to be installed.

Usage:

marimo export ipynb [OPTIONS] NAME

Options:

Name	Type	Description	Default
--sort	choice (top-down | topological)	Sort cells top-down or in topological order.	topological
--watch / --no-watch	boolean	Watch notebook for changes and regenerate the output on modification. If watchdog is installed, it will be used to watch the file. Otherwise, file watcher will poll the file every 1s.	False
-o, --output	path	Output file to save the ipynb file to. If not provided, the ipynb contents will be printed to stdout.	None
--include-outputs / --no-include-outputs	boolean	Run the notebook and include outputs in the exported ipynb file.	False
--sandbox	boolean	Run the command in an isolated virtual environment using uv run --isolated. Requires uv.	False
--help	boolean	Show this message and exit.	False

marimo export md

Export a marimo notebook as a code fenced Markdown file.

Example:

marimo export md notebook.py -o notebook.md

Watch for changes and regenerate the script on modification:

marimo export md notebook.py -o notebook.md --watch

Usage:

marimo export md [OPTIONS] NAME

Options:

Name	Type	Description	Default
--watch / --no-watch	boolean	Watch notebook for changes and regenerate the output on modification. If watchdog is installed, it will be used to watch the file. Otherwise, file watcher will poll the file every 1s.	False
-o, --output	path	Output file to save the markdown to. If not provided, markdown will be printed to stdout.	None
--help	boolean	Show this message and exit.	False

marimo export script

Export a marimo notebook as a flat script, in topological order.

Example:

marimo export script notebook.py -o notebook.script.py

Watch for changes and regenerate the script on modification:

marimo export script notebook.py -o notebook.script.py --watch

Usage:

marimo export script [OPTIONS] NAME

Options:

Name	Type	Description	Default
--watch / --no-watch	boolean	Watch notebook for changes and regenerate the output on modification. If watchdog is installed, it will be used to watch the file. Otherwise, file watcher will poll the file every 1s.	False
-o, --output	path	Output file to save the script to. If not provided, the script will be printed to stdout.	None
--help	boolean	Show this message and exit.	False

marimo new

Create a new notebook.

Usage:

marimo new [OPTIONS]

Options:

Name	Type	Description	Default
-p, --port	integer	Port to attach to.	None
--host	text	Host to attach to.	127.0.0.1
--proxy	text	Address of reverse proxy.	None
--headless	boolean	Don't launch a browser.	False
--token / --no-token	boolean	Use a token for authentication. This enables session-based authentication. A random token will be generated if --token-password is not set. If --no-token is set, session-based authentication will not be used.	True
--token-password	text	Use a specific token for authentication. This enables session-based authentication. A random token will be generated if not set.	None
--base-url	text	Base URL for the server. Should start with a /.	``
--sandbox	boolean	Run the command in an isolated virtual environment using uv run --isolated. Requires uv.	False
--help	boolean	Show this message and exit.	False

marimo recover

Recover a marimo notebook from JSON.

Usage:

marimo recover [OPTIONS] NAME

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

marimo run

Run a notebook as an app in read-only mode.

If NAME is a url, the notebook will be downloaded to a temporary file.

Example:

marimo run notebook.py

Usage:

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

Options:

Name	Type	Description	Default
-p, --port	integer	Port to attach to.	None
--host	text	Host to attach to.	127.0.0.1
--proxy	text	Address of reverse proxy.	None
--headless	boolean	Don't launch a browser.	False
--token / --no-token	boolean	Use a token for authentication. This enables session-based authentication. A random token will be generated if --token-password is not set. If --no-token is set, session-based authentication will not be used.	False
--token-password	text	Use a specific token for authentication. This enables session-based authentication. A random token will be generated if not set.	None
--include-code	boolean	Include notebook code in the app.	False
--watch	boolean	Watch the file for changes and reload the app. If watchdog is installed, it will be used to watch the file. Otherwise, file watcher will poll the file every 1s.	False
--base-url	text	Base URL for the server. Should start with a /.	``
--allow-origins	text	Allowed origins for CORS. Can be repeated.	None
--redirect-console-to-browser	boolean	Redirect console logs to the browser console.	False
--sandbox	boolean	Run the command in an isolated virtual environment using uv run --isolated. Requires uv.	False
--help	boolean	Show this message and exit.	False

marimo shell-completion

Install shell completions for marimo. Supports bash, zsh, fish, and elvish.

Usage:

marimo shell-completion [OPTIONS]

Options:

Name	Type	Description	Default
--help	boolean	Show this message and exit.	False

marimo tutorial

Open a tutorial.

marimo is a powerful library for making reactive notebooks and apps. To get the most out of marimo, get started with a few tutorials, starting with the intro:

marimo tutorial intro

Recommended sequence:

- intro
- dataflow
- ui
- markdown
- plots
- sql
- layout
- fileformat
- markdown-format
- for-jupyter-users

Usage:

marimo tutorial [OPTIONS] {intro|dataflow|ui|markdown|plots|sql|layout|filefor
                mat|markdown-format|for-jupyter-users}

Options:

Name	Type	Description	Default
-p, --port	integer	Port to attach to.	None
--host	text	Host to attach to.	127.0.0.1
--proxy	text	Address of reverse proxy.	None
--headless	boolean	Don't launch a browser.	False
--token / --no-token	boolean	Use a token for authentication. This enables session-based authentication. A random token will be generated if --token-password is not set. If --no-token is set, session-based authentication will not be used.	True
--token-password	text	Use a specific token for authentication. This enables session-based authentication. A random token will be generated if not set.	None
--help	boolean	Show this message and exit.	False