Skip to content

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.

feat: expand `app.run` to allow programmatic overrides (#6359)

Dylan Madisetti2da0c83d0f93
diff --git a/docs/api/app.md b/docs/api/app.md
index 1f26340261..778962e4c0 100644
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -4,6 +4,7 @@
options:
members:
- embed
+ - run
## AppMeta
diff --git a/docs/guides/coming_from/papermill.md b/docs/guides/coming_from/papermill.md
index 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**:
```python
import subprocess
diff --git a/marimo/_ast/app.py b/marimo/_ast/app.py
index 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/debugging
if os.environ.get("MARIMO_SCRIPT_EDIT"):
+ # unset the env var to avoid recursion
+ os.environ.pop("MARIMO_SCRIPT_EDIT")
from marimo._cli.cli import edit
if 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.py
index 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 mo
return (mo,)
@app.cell
- def __():
+ def _():
x = 0
y = 1
return (x, y)
diff --git a/marimo/_ast/errors.py b/marimo/_ast/errors.py
index 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):
+ pass
diff --git a/marimo/_output/superjson.py b/marimo/_output/superjson.py
index 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 serializes
from typing import Any
diff --git a/marimo/_runtime/app/script_runner.py b/marimo/_runtime/app/script_runner.py
index bf91905041..013e910f70 100644
--- a/marimo/_runtime/app/script_runner.py
+++ b/marimo/_runtime/app/script_runner.py
@@ -4,6 +4,7 @@ from __future__ import annotations
import asyncio
from typing import TYPE_CHECKING, Any, Callable, Optional
+from marimo._ast.errors import IncompleteRefsError
from marimo._ast.names import SETUP_CELL_NAME
from marimo._dependencies.dependencies import DependencyManager
from marimo._messaging.types import NoopStream
@@ -46,11 +47,39 @@ class AppScriptRunner:
self.filename = filename
self.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 = [
cid
for cid in self.app.execution_order
if app.cell_manager.cell_data_at(cid).cell is not None
and 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.py
index 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 _AppConfig
from 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
+
@staticmethod
def test_setup() -> None:
app = App()