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