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.	`True`
`--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`