A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
feat: expand `app.run` to allow programmatic overrides (#6359)
Dylan Madisetti2da0c83d0f93
diff --git a/docs/api/app.md b/docs/api/app.mdindex 1f26340261..778962e4c0 100644--- a/docs/api/app.md+++ b/docs/api/app.md@@ -4,6 +4,7 @@options:members:- embed+ - run## AppMetadiff --git a/docs/guides/coming_from/papermill.md b/docs/guides/coming_from/papermill.mdindex 5e204e5ec9..7649e8239b 100644--- a/docs/guides/coming_from/papermill.md+++ b/docs/guides/coming_from/papermill.md@@ -88,7 +88,46 @@ programmatically.This API also allows for parametrizing the inputs to the cell; to learn more,make sure to checkout [the example][marimo.Cell.run] in our API reference.-2. **Using subprocess**:+2. **Programmatic execution with definition overrides**:++ You can run a marimo app programmatically and override cell definitions:++ ```python+ import marimo+ from my_notebook import app++ # Run the app with overridden definitions+ # This completely replaces the definitions in cells that define these variables+ outputs, defs = app.run(defs={"batch_size": 64, "learning_rate": 0.001, "model_type": "transformer"})+ ```++ **Important limitations:**+ - When you provide definitions to `app.run()`, you are **completely overriding**+ the definitions of cells that define those variables+ - The cells that originally defined those variables will not execute their logic+ - You must provide **all** the definitions that a cell would normally produce,+ not just individual parameters+ - This is different from CLI arguments which are parsed within the cell's execution++ For example, if you have a cell that defines:+ ```python+ @app.cell+ def config():+ batch_size = 32+ learning_rate = 0.01+ return batch_size, learning_rate+ ```++ To override this cell, you must provide both variables:+ ```python+ # Correct: Override the entire cell's definitions+ outputs, defs = app.run(defs={"batch_size": 64, "learning_rate": 0.001})++ # Incorrect: This would leave learning_rate undefined+ # outputs, defs = app.run(defs={"batch_size": 64})+ ```++3. **Using subprocess**:```pythonimport subprocessdiff --git a/marimo/_ast/app.py b/marimo/_ast/app.pyindex d3f46eb678..5338baff36 100644--- a/marimo/_ast/app.py+++ b/marimo/_ast/app.py@@ -594,10 +594,96 @@ class App:def run(self,+ defs: dict[str, Any] | None = None,+ **kwargs: Any,) -> tuple[Sequence[Any], Mapping[str, Any]]:+ """+ Run the marimo app and return its outputs and definitions.++ Use this method to run marimo apps programmatically and retrieve their+ outputs and definitions. This lets you execute notebooks from other+ Python scripts. By providing definitions to `app.run()`, you can+ override specific cells in the notebook with your own values.+++ Examples:+ Consider a notebook `my_notebook.py`:++ ```python+ import marimo++ app = marimo.App()++ with app.setup:+ import pandas as pd+++ @app.cell+ def config():+ batch_size = 32+ learning_rate = 0.01+ return batch_size, learning_rate+++ @app.cell+ def process_data(pd, batch_size, learning_rate):+ data = pd.DataFrame({"x": [1, 2, 3]})+ result = data * batch_size * learning_rate+ return (result,)+++ if __name__ == "__main__":+ app.run()+ ```++ To run this app programmatically:++ ```python+ from my_notebook import app++ # Run with default values+ outputs, defs = app.run()+ # defs["batch_size"] == 32, defs["learning_rate"] == 0.01++ # Override the specific cell definitions in `config`+ outputs, defs = app.run(+ defs={batch_size: 64, learning_rate: 0.001}+ )+ # defs["batch_size"] == 64, defs["learning_rate"] == 0.001+ ```++ Definition Override Behavior:+ When you provide definitions to `app.run()`, you are **completely+ overriding** the definitions of cells that define those variables:++ - The cells that originally defined those variables will not execute+ - You must provide **all** the definitions that a cell would normally produce+ - Cells that depend on the overridden variables will use your provided values++ Args:+ defs (dict[str, Any]):+ You may pass values for any variable definitions as keyword+ arguments. marimo will use these values instead of executing+ the cells that would normally define them. Cells that depend+ on these variables will use your provided values.+ **kwargs (Any):+ For forward-compatibility with future arguments.++ Returns:+ A tuple containing:+ - Sequence of cell outputs (visual outputs from each cell)+ - Mapping of variable names to their values (definitions)++ Environment Variables:+ MARIMO_SCRIPT_EDIT: If set, opens the notebook in edit mode instead+ of running it. Requires the app to have a filename.+ """+ del kwargs# Enabled specifically for debugging purposes.# see docs.marimo.io/guides/debuggingif os.environ.get("MARIMO_SCRIPT_EDIT"):+ # unset the env var to avoid recursion+ os.environ.pop("MARIMO_SCRIPT_EDIT")from marimo._cli.cli import editif self._filename is None:@@ -611,7 +697,15 @@ class App:self._maybe_initialize()glbls: dict[str, Any] = {}if self._setup is not None:- glbls = self._setup._glbls+ glbls = {**self._setup._glbls}++ if set(glbls) & set(defs or {}):+ # Type Error is convention for bad args.+ raise TypeError("`defs` cannot override setup cell definitions.")++ if defs is not None:+ glbls.update(defs)+outputs, glbls = AppScriptRunner(InternalApp(self),filename=self._filename,diff --git a/marimo/_ast/cell.py b/marimo/_ast/cell.pyindex 92c68bb32c..d5bd0b25ae 100644--- a/marimo/_ast/cell.py+++ b/marimo/_ast/cell.py@@ -539,14 +539,14 @@ class Cell:@app.cell- def __():+ def _():import marimo as moreturn (mo,)@app.cell- def __():+ def _():x = 0y = 1return (x, y)diff --git a/marimo/_ast/errors.py b/marimo/_ast/errors.pyindex 1eca5c240e..5283249d54 100644--- a/marimo/_ast/errors.py+++ b/marimo/_ast/errors.py@@ -17,3 +17,7 @@ class MultipleDefinitionError(Exception):class UnparsableError(Exception):pass+++class IncompleteRefsError(Exception):+ passdiff --git a/marimo/_output/superjson.py b/marimo/_output/superjson.pyindex e35a65aec1..4caa930aa0 100644--- a/marimo/_output/superjson.py+++ b/marimo/_output/superjson.py@@ -1,3 +1,4 @@+# Copyright 2025 Marimo. All rights reserved.# This data serializesfrom typing import Anydiff --git a/marimo/_runtime/app/script_runner.py b/marimo/_runtime/app/script_runner.pyindex bf91905041..013e910f70 100644--- a/marimo/_runtime/app/script_runner.py+++ b/marimo/_runtime/app/script_runner.py@@ -4,6 +4,7 @@ from __future__ import annotationsimport asynciofrom typing import TYPE_CHECKING, Any, Callable, Optional+from marimo._ast.errors import IncompleteRefsErrorfrom marimo._ast.names import SETUP_CELL_NAMEfrom marimo._dependencies.dependencies import DependencyManagerfrom marimo._messaging.types import NoopStream@@ -46,11 +47,39 @@ class AppScriptRunner:self.filename = filenameself.cells_cancelled: set[CellId_t] = set()self._glbls = glbls if glbls else {}++ # Prune cells that define provided refs+ cells_to_prune: set[CellId_t] = set()+ if self._glbls:+ refs = set(self._glbls.keys())+ for ref_name in refs:+ if ref_name in self.app.graph.definitions:+ defining_cells = self.app.graph.get_defining_cells(+ ref_name+ )+ cells_to_prune.update(defining_cells)++ # Validate that all definitions from pruned cells are provided+ missing_defs: set[str] = set()+ for cell_id in cells_to_prune:+ cell = self.app.graph.cells[cell_id]+ # Check all definitions this cell would have provided+ for missing in cell.defs - refs:+ missing_defs.add(missing)++ if missing_defs:+ raise IncompleteRefsError(+ f"When providing refs that override cell definitions, you must "+ f"provide all definitions from those cells. Missing: {sorted(missing_defs)}. "+ f"Provided refs: {sorted(refs)}."+ )+self.cells_to_run = [cidfor cid in self.app.execution_orderif app.cell_manager.cell_data_at(cid).cell is not Noneand not self.app.graph.is_disabled(cid)+ and cid not in cells_to_prune]self._executor = get_executor(ExecutionConfig())@@ -77,6 +106,7 @@ class AppScriptRunner:) as module:glbls = module.__dict__glbls.update(self._glbls)+outputs: dict[CellId_t, Any] = {}while self.cells_to_run:cid = self.cells_to_run.pop(0)@@ -118,6 +148,7 @@ class AppScriptRunner:) as module:glbls = module.__dict__glbls.update(self._glbls)+outputs: dict[CellId_t, Any] = {}while self.cells_to_run:diff --git a/tests/_ast/test_app.py b/tests/_ast/test_app.pyindex b1068bc638..f77903a605 100644--- a/tests/_ast/test_app.py+++ b/tests/_ast/test_app.py@@ -21,6 +21,7 @@ from marimo._ast.app import (from marimo._ast.app_config import _AppConfigfrom marimo._ast.errors import (CycleError,+ IncompleteRefsError,MultipleDefinitionError,SetupRootError,UnparsableError,@@ -89,6 +90,111 @@ class TestApp:assert (defs["y"], defs["z"]) == (1, 2)assert defs["a"] == 2+ @staticmethod+ def test_run_with_refs() -> None:+ """Test that app.run() can override variables with provided defs."""+ app = App()++ @app.cell+ def config() -> tuple[int, float]:+ batch_size = 32+ learning_rate = 0.01+ return batch_size, learning_rate++ @app.cell+ def process_data(batch_size: int, learning_rate: float) -> tuple[float]:+ result = batch_size * learning_rate+ return (result,)++ @app.cell+ def other_cell() -> tuple[str]:+ message = "independent"+ return (message,)++ # Test 1: Run with default values+ outputs, defs = app.run()+ assert defs["batch_size"] == 32+ assert defs["learning_rate"] == 0.01+ assert defs["result"] == 32 * 0.01+ assert defs["message"] == "independent"++ # Test 2: Run with overridden values+ outputs, defs = app.run(defs={"batch_size": 64, "learning_rate": 0.001})+ assert defs["batch_size"] == 64+ assert defs["learning_rate"] == 0.001+ assert defs["result"] == 64 * 0.001+ assert defs["message"] == "independent" # unaffected cell still runs++ # Test 3: Partial override - this should fail with IncompleteRefsError+ # because we're only providing batch_size but the config cell defines both+ # batch_size and learning_rate+ with pytest.raises(IncompleteRefsError) as exc_info:+ app.run(defs={"batch_size": 128})+ assert "learning_rate" in str(exc_info.value)+ assert "Missing: ['learning_rate']" in str(exc_info.value)+ assert "Provided refs: ['batch_size']" in str(exc_info.value)++ @staticmethod+ def test_run_with_refs_multiple_cells() -> None:+ """Test defs override with multiple cells that define different variables."""+ app = App()++ @app.cell+ def cell_a() -> tuple[int]:+ x = 10+ return (x,)++ @app.cell+ def cell_b() -> tuple[int]:+ y = 20+ return (y,)++ @app.cell+ def cell_c(x: int, y: int) -> tuple[int]:+ z = x + y+ return (z,)++ # Test: Override both x and y - cells a and b should be pruned+ outputs, defs = app.run(defs={"x": 100, "y": 200})+ assert defs["x"] == 100+ assert defs["y"] == 200+ assert defs["z"] == 300++ # Test: Override only x - cell a is pruned, cell b still runs+ outputs, defs = app.run(defs={"x": 50})+ assert defs["x"] == 50+ assert defs["y"] == 20 # cell_b still ran+ assert defs["z"] == 70++ @staticmethod+ def test_run_with_refs_setup_cell_protection() -> None:+ """Test that overriding setup cell definitions raises IncompleteRefsError."""+ app = App()++ with app.setup:+ import os+ setup_var = "from_setup"++ @app.cell+ def use_setup(setup_var: str) -> tuple[str]:+ result = f"Used {setup_var}"+ return (result,)++ # Test: Can still override non-setup variables+ @app.cell+ def normal_cell() -> tuple[int]:+ normal_var = 42+ return (normal_var,)++ # Test: Trying to override setup cell variables should fail+ with pytest.raises(TypeError) as exc_info:+ app.run(defs={"setup_var": "overridden"})+ assert "override" in str(exc_info.value)++ outputs, defs = app.run(defs={"normal_var": 100})+ assert defs["normal_var"] == 100+ assert "setup_var" in defs # setup still ran+@staticmethoddef test_setup() -> None:app = App()