Run notebooks as scripts¶

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

python my_marimo_notebook.py

The python command uses your current environment, which must contain marimo and the notebook's dependencies. Activate it first if you manage it yourself.

uv and Pixi can prepare the environment and run the script using its declared dependencies.

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.

You can also import functions and classes from notebooks into other Python programs.

Running with declared dependencies¶

Use your package manager to run a notebook with its declared requirements.

Running with inline dependencies¶

A sandboxed notebook declares its requirements as inline script metadata (PEP 723). uv and Pixi can read that metadata, prepare an environment, and run the notebook without opening the editor:

uvPixi

uv run notebook.py

pixi run --script notebook.py

Use Pixi for notebooks that require Conda dependencies declared under tool.pixi. Running a notebook with python directly does not install its inline requirements.

Running in a project¶

For a notebook that uses project dependencies, run it from the project directory:

uvPixiPoetry

uv run notebook.py

If the notebook contains inline script metadata, uv uses that metadata instead of the project's dependencies.

pixi run python notebook.py

pixi run python uses the workspace environment. Use pixi run --script notebook.py instead to prepare an environment from the notebook's inline requirements.

poetry run python notebook.py

See package management for choosing between project dependencies and a notebook sandbox.

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