Run notebooks as scripts - marimo (original) (raw)

Run as a script¶

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

[](#%5F%5Fcodelineno-0-1)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:

[](#%5F%5Fcodelineno-1-1)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

[](#%5F%5Fcodelineno-2-1)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:

[](#%5F%5Fcodelineno-3-1)marimo export html notebook.py -o notebook.html -- -arg value

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

[](#%5F%5Fcodelineno-4-1)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 argparseand 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

__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() `