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.

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/with_argparse.py

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

import marimo

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


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


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


@app.cell
def _(argparse):
    parser = argparse.ArgumentParser(
        description="This notebook shows how to use argparse with marimo",
    )

    parser.add_argument("filename")
    parser.add_argument("-c", "--count", type=int)
    parser.add_argument("-v", "--verbose", action="store_true")
    return (parser,)


@app.cell
def _(mo, parser):
    def parse_args():
        if mo.running_in_notebook():
            # set default values for the command-line arguments when running as a notebook
            filename = "your default value"
            count = 42
            verbose = True
        else:
            args = parser.parse_args()
            filename = args.filename
            count = args.count
            verbose = args.verbose
        return filename, count, verbose
    return (parse_args,)


@app.cell
def _(parse_args):
    print(parse_args())
    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.11.31"
app = marimo.App(width="medium")


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


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


@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 ArgumentParser, Options, dataclass, 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 fields, parse_args


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


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