marimo-notebook

Notes for marimo Notebooks

marimo uses Python to create notebooks, unlike Jupyter which uses JSON. Here's an example notebook:

# /// script
# dependencies = [
#     "marimo",
#     "numpy==2.4.3",
# ]
# requires-python = ">=3.14"
# ///
 
import

Notice how the notebook is structured with functions can represent cell contents. Each cell is defined with the @app.cell decorator and the inputs/outputs of the function are the inputs/outputs of the cell. marimo usually takes care of the dependencies between cells automatically.

Running Marimo Notebooks

Script Mode Detection

Use mo.app_meta().mode == "script" to detect CLI vs interactive:

Key Principle: Keep It Simple

Show all UI elements always. Only change the data source in script mode.

• Sliders, buttons, widgets should always be created and displayed
• In script mode, just use synthetic/default data instead of waiting for user input
• Don't wrap everything in if not is_script_mode conditionals
• Don't use try/except for normal control flow

Good Pattern

State and Reactivity

Variables between cells define the reactivity of the notebook for 99% of the use-cases out there. No special state management needed. Don't mutate objects across cells (e.g., my_list.append()); create new objects instead. Avoid mo.state() unless you need bidirectional UI sync or accumulated callback state. See STATE.md for details.

Don't Guard Cells with if Statements

Marimo's reactivity means cells only run when their dependencies are ready. Don't add unnecessary guards:

The cell won't run until training_results has a value anyway.

Don't Use try/except for Control Flow

Don't wrap code in try/except blocks unless you're handling a specific, expected exception. Let errors surface naturally.

Only use try/except when:

• You're handling a specific, known exception type
• The exception is expected in normal operation (e.g., file not found)
• You have a meaningful recovery action

Cell Output Rendering

Marimo only renders the final expression of a cell. Indented or conditional expressions won't render:

PEP 723 Dependencies

Notebooks created via marimo edit --sandbox have these dependencies added to the top of the file automatically but it is a good practice to make sure these exist when creating a notebook too:

marimo check

When working on a notebook it is important to check if the notebook can run. That's why marimo provides a check command that acts as a linter to find common mistakes.

Make sure these are checked before handing a notebook back to the user.

Important: you have a tendency to over-do variables with an underscore prefix. You should only apply this to one or two variables at most. Consider creating a new variable instead of prefixing entire cells in marimo.

api docs

If the user specifically wants you to use a marimo function, you can locally check the docs via:

tests

By default, marimo discovers and executes tests inside your notebook. When the optional pytest dependency is present, marimo runs pytest on cells that consist exclusively of test code - i.e. functions whose names start with test_. If the user asks you to add tests, make sure to add the pytest dependency is added and that there is a cell that contains only test code.

For more information on testing with pytest see PYTEST.md

Once tests are added, you can run pytest from the commandline on the notebook to run pytest.

Additional resources

• For marimo notebooks that run in width=columns SQL.md
• For SQL use in marimo see SQL.md
• For UI elements in marimo UI.md
• For exposing functions/classes as top level imports TOP-LEVEL-IMPORTS.md
• For exporting notebooks (PDF, HTML, markdown, etc.) EXPORTS.md
• For state management and reactivity STATE.md
• For deployment of marimo notebooks DEPLOYMENT.md
• For custom interactive widgets with anywidget ANYWIDGET.md
• For external editing and --watch mode WATCHING.md
• For expensive notebooks (caching, lazy eval, mo.stop) EXPENSIVE.md
• For configuration (pyproject.toml, marimo.toml) CONFIGURATION.md
• For reactivity model (DAG, variable scoping, mutations) REACTIVITY.md