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.

marimo ntoebooks can also [double as importable modules, providing libraries of functions and classes that you can reuse in other programs:

from my_notebook import my_function

Read our guide on reusable functions for details.

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.19.7"
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.19.7"
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()

Example: scheduled execution¶

marimo notebooks are Python files, so any scheduler that runs Python scripts can run marimo notebooks. This includes cron, Airflow, Prefect, and other tools. You can pass variables from the command line and reuse functions from notebooks in other jobs as well.

GitHub Action¶

Run notebooks on a schedule with GitHub Actions. This example assumes inline dependencies:

name: Run marimo notebook daily

on:
  schedule:
    - cron: '0 9 * * *'

jobs:
  run-marimo:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
      with:
        python-version: '3.12'
    - uses: astral-sh/setup-uv@v7
    - run: uv run path/to/notebook.py