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
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
import subprocess
import sys
from typing import TYPE_CHECKING
import pytest
from marimo._dependencies.dependencies import DependencyManager
from marimo._save.manifest import CacheManifest, is_manifest_name
if TYPE_CHECKING:
from collections.abc import Callable
from pathlib import Path
NOTEBOOK_SOURCE = """# /// script
# [tool.marimo.runtime]
# cache_cells = true
# ///
import marimo
app = marimo.App()
@app.cell
def _():
value = sum(range(1000))
print(f"computed value={value}")
return (value,)
@app.cell
def _(value):
doubled = value * 2
print(f"downstream doubled={doubled}")
return (doubled,)
if __name__ == "__main__":
app.run()
"""
def test_script_run_populates_and_restores_cell_cache(tmp_path: Path) -> None:
"""`python notebook.py` warms the `cache_cells` cell cache.
The first run executes cell bodies and saves them to
`__marimo__/cache`. The second run restores from cache, so the cell
bodies (and their prints) do not run.
"""
nb_path = tmp_path / "notebook.py"
nb_path.write_text(NOTEBOOK_SOURCE, encoding="utf-8")
first = subprocess.run(
[sys.executable, str(nb_path)],
capture_output=True,
text=True,
cwd=tmp_path,
timeout=120,
)
assert first.returncode == 0, first.stderr
assert "computed value=499500" in first.stdout
assert "downstream doubled=999000" in first.stdout
cache_dir = tmp_path / "__marimo__" / "cache"
assert cache_dir.is_dir(), "script run must create the cell cache"
assert any(cache_dir.rglob("*")), "script run must write cache entries"
second = subprocess.run(
[sys.executable, str(nb_path)],
capture_output=True,
text=True,
cwd=tmp_path,
timeout=120,
)
assert second.returncode == 0, second.stderr
assert "computed value" not in second.stdout, (
"cached cell body ran again instead of restoring"
)
def test_script_run_records_its_cache_entries_in_a_manifest(
tmp_path: Path,
) -> None:
"""A script run writes the manifest that `marimo cache` commands read."""
nb_path = tmp_path / "notebook.py"
nb_path.write_text(NOTEBOOK_SOURCE, encoding="utf-8")
result = subprocess.run(
[sys.executable, str(nb_path)],
capture_output=True,
text=True,
cwd=tmp_path,
timeout=120,
)
assert result.returncode == 0, result.stderr
cache_dir = tmp_path / "__marimo__" / "cache"
(manifest_path,) = [
path for path in cache_dir.iterdir() if is_manifest_name(path.name)
]
manifest = CacheManifest.from_bytes(manifest_path.read_bytes())
entries = manifest.entries()
assert len(entries) == 2, "one entry per cell"
assert {block for block, _ in entries} == {"cell_cache"}
def test_script_run_without_cache_cells_stays_cold(tmp_path: Path) -> None:
"""Without `cache_cells`, script runs execute every cell, every time."""
source = NOTEBOOK_SOURCE.replace("# cache_cells = true\n", "")
nb_path = tmp_path / "notebook.py"
nb_path.write_text(source, encoding="utf-8")
for _ in range(2):
result = subprocess.run(
[sys.executable, str(nb_path)],
capture_output=True,
text=True,
cwd=tmp_path,
timeout=120,
)
assert result.returncode == 0, result.stderr
assert "computed value=499500" in result.stdout
assert not (tmp_path / "__marimo__" / "cache").exists()
# `x` is not a primitive, so the consumer's cache key hashes the code of
# the cell that defines `x` rather than its value.
OVERRIDE_NOTEBOOK_SOURCE = """# /// script
# [tool.marimo.runtime]
# cache_cells = true
# ///
import marimo
app = marimo.App()
with app.setup:
from types import SimpleNamespace
@app.cell
def _():
x = SimpleNamespace(value=1)
return (x,)
@app.cell
def _(x):
y = x.value
print(f"computed y={y}")
return (y,)
"""
OVERRIDE_DRIVER_SOURCE = """import sys
from types import SimpleNamespace
from notebook import app
overrides = {"x": SimpleNamespace(value=2)} if sys.argv[1:] else None
_, defs = app.run(defs=overrides)
print(f"returned y={defs['y']}")
"""
def test_app_run_with_overrides_bypasses_cell_cache(tmp_path: Path) -> None:
"""`App.run(defs=...)` neither restores nor saves cached cells."""
(tmp_path / "notebook.py").write_text(
OVERRIDE_NOTEBOOK_SOURCE, encoding="utf-8"
)
driver = tmp_path / "driver.py"
driver.write_text(OVERRIDE_DRIVER_SOURCE, encoding="utf-8")
def run(*args: str) -> str:
result = subprocess.run(
[sys.executable, str(driver), *args],
capture_output=True,
text=True,
cwd=tmp_path,
timeout=120,
)
assert result.returncode == 0, result.stderr
return result.stdout
assert "returned y=1" in run()
assert "returned y=2" in run("--override")
warm = run()
assert "returned y=1" in warm
assert "computed y" not in warm, "the first run's entry should restore"
ARRAY_NOTEBOOK_SOURCE = """import marimo
app = marimo.App()
@app.cell
def _():
import numpy as np
return (np,)
@app.cell
def _(np):
x = np.array([1, 2])
return (x,)
@app.cell
def _(x):
y = int(x.sum())
return (y,)
"""
# Both notebooks run inside this notebook's cell, so they reuse its runtime
# context, including the `cache_cells` setting.
HOST_NOTEBOOK_SOURCE = """# /// script
# [tool.marimo.runtime]
# cache_cells = true
# ///
import marimo
app = marimo.App()
@app.cell
def _():
import ones
import tens
_, ones_defs = ones.app.run()
_, tens_defs = tens.app.run()
print(f"returned y={ones_defs['y']},{tens_defs['y']}")
return
if __name__ == "__main__":
app.run()
"""
@pytest.mark.skipif(
not DependencyManager.numpy.has(), reason="numpy not installed"
)
def test_app_runs_in_one_context_hash_their_own_values(tmp_path: Path) -> None:
"""Each `App.run()` hashes its own values, even in a shared context.
Content hashes are memoized by variable name. A second run that read
the first run's memo would hash its `x` as `[1, 2]` and restore the
first run's `y`.
"""
(tmp_path / "ones.py").write_text(ARRAY_NOTEBOOK_SOURCE, encoding="utf-8")
(tmp_path / "tens.py").write_text(
ARRAY_NOTEBOOK_SOURCE.replace("[1, 2]", "[10, 20]"), encoding="utf-8"
)
host = tmp_path / "host.py"
host.write_text(HOST_NOTEBOOK_SOURCE, encoding="utf-8")
result = subprocess.run(
[sys.executable, str(host)],
capture_output=True,
text=True,
cwd=tmp_path,
timeout=120,
)
assert result.returncode == 0, result.stderr
assert "returned y=3,30" in result.stdout
UNPICKLABLE_NOTEBOOK_SOURCE = """# /// script
# [tool.marimo.runtime]
# cache_cells = true
# ///
import marimo
app = marimo.App()
@app.cell
def _():
increment = lambda value: value + 1
print("defined increment")
return (increment,)
"""
UNPICKLABLE_DRIVER_SOURCE = """from notebook import app
_, defs = app.run()
print(f"returned {defs['increment'](1)}")
"""
def test_app_run_reruns_cells_whose_definitions_did_not_pickle(
tmp_path: Path,
) -> None:
"""`App.run()` never hands back a cache placeholder.
A lambda cannot be pickled, so its cache entry holds a placeholder. In
a notebook the first cell to read the placeholder reruns its producer;
the caller of `App.run()` reads the definitions only after the run, so
the script runner reruns the producer itself.
"""
(tmp_path / "notebook.py").write_text(
UNPICKLABLE_NOTEBOOK_SOURCE, encoding="utf-8"
)
driver = tmp_path / "driver.py"
driver.write_text(UNPICKLABLE_DRIVER_SOURCE, encoding="utf-8")
for attempt in ("cold", "warm"):
result = subprocess.run(
[sys.executable, str(driver)],
capture_output=True,
text=True,
cwd=tmp_path,
timeout=120,
)
assert result.returncode == 0, (attempt, result.stderr)
assert "returned 2" in result.stdout, attempt
assert "defined increment" in result.stdout, (
f"the {attempt} run must execute the cell"
)
# `n` changes on every run and `f` cannot be pickled.
STUB_DESCENDANT_NOTEBOOK_SOURCE = """# /// script
# [tool.marimo.runtime]
# cache_cells = true
# ///
import marimo
app = marimo.App()
@app.cell
def _():
import time
n = time.time()
f = lambda: 1
return f, n
@app.cell
def _(n):
y = 2 * n
return (y,)
"""
# Reads only `f`, so its cache key hashes the code of the defining cell.
STUB_READER_CELL_SOURCE = """
@app.cell
def _(f):
h = f()
print("computed h")
return (h,)
"""
STUB_DESCENDANT_DRIVER_SOURCE = """from notebook import app
_, defs = app.run()
print(f"consistent={defs['y'] == 2 * defs['n']}")
"""
def _run_driver(tmp_path: Path, notebook: str) -> Callable[[], str]:
(tmp_path / "notebook.py").write_text(notebook, encoding="utf-8")
driver = tmp_path / "driver.py"
driver.write_text(STUB_DESCENDANT_DRIVER_SOURCE, encoding="utf-8")
def run() -> str:
result = subprocess.run(
[sys.executable, str(driver)],
capture_output=True,
text=True,
cwd=tmp_path,
timeout=120,
)
assert result.returncode == 0, result.stderr
return result.stdout
return run
def test_app_run_reruns_descendants_of_rerun_producers(
tmp_path: Path,
) -> None:
"""A producer rerun after the run reruns the cells that read it.
On a warm run the first cell restores a stale `n` next to a placeholder
for `f`, and the second cell restores the `y` that matched the stale
`n`. Rerunning the first cell alone would hand back `y != 2 * n`.
"""
run = _run_driver(tmp_path, STUB_DESCENDANT_NOTEBOOK_SOURCE)
assert "consistent=True" in run()
assert "consistent=True" in run(), (
"the derived value must come from the rerun producer"
)
def test_app_run_reruns_descendants_when_a_reader_reschedules(
tmp_path: Path,
) -> None:
"""A producer rerun mid-run reruns the cells that read it.
The third cell reads the placeholder for `f` and reschedules the first
cell before the run ends. The second cell must follow the rerun, while
the third cell's key did not change, so it still restores.
"""
run = _run_driver(
tmp_path, STUB_DESCENDANT_NOTEBOOK_SOURCE + STUB_READER_CELL_SOURCE
)
cold = run()
assert "consistent=True" in cold
assert "computed h" in cold
warm = run()
assert "consistent=True" in warm, (
"the derived value must come from the rerun producer"
)
assert "computed h" not in warm, (
"a descendant whose inputs did not change should still restore"
)
OUTPUT_STUB_NOTEBOOK_SOURCE = """# /// script
# [tool.marimo.runtime]
# cache_cells = true
# ///
import marimo
app = marimo.App()
@app.cell
def _():
lambda value: value + 1
return
"""
OUTPUT_STUB_DRIVER_SOURCE = """from notebook import app
outputs, _ = app.run()
output = outputs[0]
print(f"output kind={type(output).__name__}")
print(f"called {output(1)}")
"""
def test_app_run_never_returns_a_placeholder_output(tmp_path: Path) -> None:
"""A def-less cell whose last expression did not pickle runs live.
The cell defines nothing, so no definition reveals the placeholder. The
restored output itself must be recognized and the cell rerun.
"""
(tmp_path / "notebook.py").write_text(
OUTPUT_STUB_NOTEBOOK_SOURCE, encoding="utf-8"
)
driver = tmp_path / "driver.py"
driver.write_text(OUTPUT_STUB_DRIVER_SOURCE, encoding="utf-8")
for attempt in ("cold", "warm"):
result = subprocess.run(
[sys.executable, str(driver)],
capture_output=True,
text=True,
cwd=tmp_path,
timeout=120,
)
assert "output kind=function" in result.stdout, (
attempt,
result.stdout,
)
assert result.returncode == 0, (attempt, result.stderr)
assert "called 2" in result.stdout, attempt