Run as a script

You can run marimo notebooks as scripts at the command line, just like any other Python script. For example,

python my_marimo_notebook.py

Running a notebook as a script is useful when your notebook has side-effects, like writing to disk. Print statements and other console outputs will show up in your terminal.

Check before running

Before running a notebook as a script, you can use marimo's linter to check for issues that might prevent execution:

marimo check my_marimo_notebook.py

See the Lint Rules guide for more information about marimo's linting system.

Saving notebook outputs

To run as a script while also saving HTML of the notebook outputs, use

marimo export html notebook.py -o notebook.html

You can also pass command-line arguments to your notebook during export. Separate these args from the command with two dashes:

marimo export html notebook.py -o notebook.html -- -arg value

Exporting to other formats, such as ipynb, is also possible:

marimo export ipynb notebook.py -o notebook.ipynb -- -arg value

Command-line arguments

When run as a script, you can access your notebook's command-line arguments through sys.argv, just like any other Python program. This also means you can declare your notebook's command-line arguments using Python libraries like argparse and simple-parsing.

These examples shows how to conditionally assign values to variables based on command-line arguments when running as a script, and use default values when running as a notebook.

argparse

Source code for examples/running_as_a_script/sharing_arguments.py

Tip: paste this code into an empty cell, and the marimo editor will create cells for you

import marimo

__generated_with = "0.17.2"
app = marimo.App(width="medium")


@app.cell
def _():
    import marimo as mo
    return (mo,)


@app.cell
def _():
    import argparse
    return (argparse,)


@app.cell(hide_code=True)
def _(mo):
    mo.md("""
    This notebook shows how to parametrize a notebook with optional command-line arguments.

    Run the notebook with

    ```bash
    marimo edit sharing_arguments.py
    ```

    or

    ```bash
    marimo edit sharing_arguments.py -- -learning_rate=1e-3
    ```

    (Note the `--` separating the filename from the arguments.)

    or

    ```bash
    python sharing_arguments.py -learning_rate=1e-3
    ```

    See help for the notebook's arguments with

    ```python
    python sharing_arguments.py --help
    ```
    """)
    return


@app.cell
def _(mo):
    default = mo.ui.number(1000, step=100)
    default
    return (default,)


@app.cell
def _(argparse, default):
    parser = argparse.ArgumentParser()

    parser.add_argument("-iterations", default=default.value)
    args = parser.parse_args()
    print(args.iterations)
    return


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

simple-parsing

Source code for examples/running_as_a_script/with_simple_parsing.py

Tip: paste this code into an empty cell, and the marimo editor will create cells for you

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "marimo",
#     "simple-parsing==0.1.7",
# ]
# ///

import marimo

__generated_with = "0.15.5"
app = marimo.App(width="medium")


@app.cell
def _():
    import marimo as mo
    return (mo,)


@app.cell
def _():
    import simple_parsing
    return


@app.cell
def _():
    from dataclasses import dataclass
    from simple_parsing import ArgumentParser

    parser = ArgumentParser()
    parser.add_argument("--foo", type=int, default=123, help="foo help")


    @dataclass
    class Options:
        """Help string for this group of command-line arguments."""

        log_dir: str  # Help string for a required str argument
        learning_rate: float = 1e-4  # Help string for a float argument

    parser.add_arguments(Options, dest="options")
    return Options, parser


@app.cell
def _(Options, mo, parser):
    from dataclasses import fields

    def parse_args():
        if mo.running_in_notebook():
            # set default values for the command-line arguments when running as a notebook
            return "foo default", Options("logs/", 1e-4)
        else:
            args = parser.parse_args()
            return args.foo, args.options
    return (parse_args,)


@app.cell
def _(parse_args):
    foo, options = parse_args()
    print(foo, options)
    return


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