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.

fix: delete local variables after cell execution (#9933)

Akshay Agrawal52ac299955a9
diff --git a/docs/guides/expensive_notebooks.md b/docs/guides/expensive_notebooks.md
index 39425d25fd..8988a7302e 100644
--- a/docs/guides/expensive_notebooks.md
+++ b/docs/guides/expensive_notebooks.md
@@ -132,6 +132,15 @@ attempting to manually run the second cell will raise a `NameError`, and you'll
need to re-run the defining cell in order to get your notebook back to a
consistent state.
+### Local variables
+
+[Local or temporary
+variables](../guides/reactivity.md#creating-temporary-variables) (i.e.,
+variables prefixed with an underscore) are automatically removed from the
+kernel globals after cell-run. If another Python object retains a reference to
+the variable, it will remain in memory; otherwise, Python's garbage collector
+will automatically reclaim its allocated memory.
+
## Automatically snapshot outputs as HTML or IPYNB
To keep a record of your cell outputs while working on your
diff --git a/marimo/_ast/app.py b/marimo/_ast/app.py
index 9c03ce1b28..5dacdfdb6e 100644
--- a/marimo/_ast/app.py
+++ b/marimo/_ast/app.py
@@ -326,6 +326,7 @@ class App:
refs=cell_impl.refs,
sql_refs=cell_impl.sql_refs,
temporaries=cell_impl.temporaries,
+ closed_over_temporaries=cell_impl.closed_over_temporaries,
variable_data=cell_impl.variable_data,
deleted_refs=cell_impl.deleted_refs,
body=cell_impl.body,
diff --git a/marimo/_ast/cell.py b/marimo/_ast/cell.py
index 0c3fbd8488..d7888ffc7e 100644
--- a/marimo/_ast/cell.py
+++ b/marimo/_ast/cell.py
@@ -174,6 +174,11 @@ class CellImpl:
# unique id
cell_id: CellId_t
+ # Subset of `temporaries` that are closed over (transitively) by a
+ # function, lambda, or class defined in this cell, and so must be retained
+ # in the kernel globals for those closures to be callable.
+ closed_over_temporaries: set[Name] = dataclasses.field(default_factory=set)
+
# Markdown content of the cell if it exists
markdown: str | None = None
diff --git a/marimo/_ast/compiler.py b/marimo/_ast/compiler.py
index ef4028be4c..de2b836b5d 100644
--- a/marimo/_ast/compiler.py
+++ b/marimo/_ast/compiler.py
@@ -28,7 +28,12 @@ from marimo._ast.names import SETUP_CELL_NAME, TOPLEVEL_CELL_PREFIX
from marimo._ast.pytest import has_fixture_decorator
from marimo._ast.transformers import ContainedExtractWithBlock
from marimo._ast.variables import is_local
-from marimo._ast.visitor import ImportData, Name, ScopedVisitor
+from marimo._ast.visitor import (
+ ImportData,
+ Name,
+ ScopedVisitor,
+ get_closure_refs,
+)
from marimo._schemas.serialization import CellDef, ClassCell, FunctionCell
from marimo._types.ids import CellId_t
from marimo._utils.tmpdir import get_tmpdir
@@ -363,6 +368,11 @@ def compile_cell(
for name in nonlocals
if name in v.variable_data
}
+ # Temporaries that closures depend on (transitively) must be retained even
+ # though they would otherwise be deleted after the cell runs. We use the
+ # unfiltered `v.variable_data` here so that references reachable only
+ # through private (temporary) closures are still found.
+ closed_over_temporaries = get_closure_refs(v.variable_data) & temporaries
# If this cell is an import cell, we carry over any imports in
# `carried_imports` that are also in this cell to the import workspace's
@@ -389,6 +399,7 @@ def compile_cell(
refs=v.refs,
sql_refs=v.sql_refs,
temporaries=temporaries,
+ closed_over_temporaries=closed_over_temporaries,
variable_data=variable_data,
import_workspace=ImportWorkspace(
is_import_block=is_import_block,
diff --git a/marimo/_ast/visitor.py b/marimo/_ast/visitor.py
index 6b23ec78af..a98b8f37e0 100644
--- a/marimo/_ast/visitor.py
+++ b/marimo/_ast/visitor.py
@@ -108,6 +108,55 @@ class VariableData:
)
+def _defers_ref_resolution(datum: VariableData) -> bool:
+ """Whether a definition resolves its references lazily, at call time.
+
+ Functions, lambdas, and classes (via their methods) read the names they
+ reference from the enclosing scope when they are *called*, not when they
+ are defined — i.e. they bind those names late. This is true regardless of
+ whether the definition actually captures anything: a function that
+ references nothing simply has empty `required_refs`. Contrast with eager
+ definitions like `y = _x + 1`, which read `_x` at definition time.
+ """
+ return datum.kind in ("function", "class") or (
+ "_lambda" in datum.required_refs
+ )
+
+
+def get_closure_refs(
+ variable_data: dict[Name, list[VariableData]],
+) -> set[Name]:
+ """Return the names that functions, lambdas, and classes close over.
+
+ Because closures resolve their references at call time, the names they
+ depend on must stay in scope even when they would otherwise be considered
+ temporary. References are followed transitively through closures: if a
+ closure references a private helper that is itself a closure, that helper's
+ references are included too.
+ """
+ refs: set[Name] = set()
+ # Seed the search with every reference made by a late-binding definition;
+ # these are the names that must survive so the definitions stay callable.
+ frontier: set[Name] = {
+ ref
+ for data in variable_data.values()
+ for datum in data
+ if _defers_ref_resolution(datum)
+ for ref in datum.required_refs
+ }
+ while frontier:
+ ref = frontier.pop()
+ if ref in refs:
+ continue
+ refs.add(ref)
+ # Only late-binding definitions defer resolution to call time, so only
+ # their references need to be retained transitively.
+ for datum in variable_data.get(ref, []):
+ if _defers_ref_resolution(datum):
+ frontier |= datum.required_refs - refs
+ return refs
+
+
@dataclass
class Block:
"""A scope in which names are declared."""
diff --git a/marimo/_runtime/runner/hooks_post_execution.py b/marimo/_runtime/runner/hooks_post_execution.py
index 7cfafb9fc9..b3be4ceed0 100644
--- a/marimo/_runtime/runner/hooks_post_execution.py
+++ b/marimo/_runtime/runner/hooks_post_execution.py
@@ -507,6 +507,25 @@ def _reset_matplotlib_context(
exec("__marimo__._output.mpl.close_figures()", ctx.glbls)
+@kernel_tracer.start_as_current_span("delete_local_variables")
+def _delete_local_variables(
+ cell: CellImpl,
+ ctx: PostExecutionHookContext,
+ run_result: cell_runner.RunResult,
+) -> None:
+ # Remove temporary (local) variables from the kernel globals to relieve
+ # memory pressure once the cell has finished running.
+ #
+ # To prevent breaking existing notebooks, we make an exception for
+ # temporaries that are closed over by a function, lambda, or class defined
+ # in this cell: deleting those would cause a NameError when the closure is
+ # later invoked, since closures do late-binding. These are precomputed at
+ # compile time as `closed_over_temporaries`.
+ del run_result
+ for name in cell.temporaries - cell.closed_over_temporaries:
+ ctx.glbls.pop(name, None)
+
+
@kernel_tracer.start_as_current_span("flush_console")
def _flush_console(
cell: CellImpl,
@@ -540,6 +559,7 @@ POST_EXECUTION_HOOKS: list[PostExecutionHook] = [
_broadcast_duckdb_datasource,
_broadcast_outputs,
_reset_matplotlib_context,
+ _delete_local_variables,
# Flush buffered console output so that stderr/stdout arrives at the
# frontend before the cell transitions to idle.
_flush_console,
diff --git a/tests/_ast/test_visitor.py b/tests/_ast/test_visitor.py
index 860863c7be..63a5c8c78d 100644
--- a/tests/_ast/test_visitor.py
+++ b/tests/_ast/test_visitor.py
@@ -1975,3 +1975,38 @@ def test_class_with_backward_reference_to_method() -> None:
assert v.refs == {"method"}
# B should have method in unbounded refs (backward reference is invalid)
assert v.variable_data["B"][0].unbounded_refs == {"method"}
+
+
+def _closure_refs(code: str) -> set[str]:
+ v = visitor.ScopedVisitor("cell_c")
+ v.visit(ast.parse(dedent(code)))
+ return visitor.get_closure_refs(v.variable_data)
+
+
+def test_get_closure_refs_function() -> None:
+ assert "_cell_c_x" in _closure_refs("_x = 1\ndef foo():\n return _x")
+
+
+def test_get_closure_refs_lambda() -> None:
+ assert "_cell_c_x" in _closure_refs("_x = 1\nlam = lambda: _x")
+
+
+def test_get_closure_refs_class() -> None:
+ code = "_x = 1\nclass C:\n def m(self):\n return _x"
+ assert "_cell_c_x" in _closure_refs(code)
+
+
+def test_get_closure_refs_ignores_plain_data_dependency() -> None:
+ # `_x` is only a data dependency of `y`, not closed over, so it is excluded.
+ assert _closure_refs("_x = 1\ny = _x + 1") == set()
+
+
+def test_get_closure_refs_transitive_through_private_helper() -> None:
+ # `foo` closes over `_helper`, which itself closes over `_data`; both must
+ # be reported.
+ code = (
+ "_data = 1\n"
+ "def _helper():\n return _data\n"
+ "def foo():\n return _helper()"
+ )
+ assert {"_cell_c_helper", "_cell_c_data"} <= _closure_refs(code)
diff --git a/tests/_runtime/test_runtime.py b/tests/_runtime/test_runtime.py
index f3479a27ab..e01f56d0df 100644
--- a/tests/_runtime/test_runtime.py
+++ b/tests/_runtime/test_runtime.py
@@ -12,6 +12,7 @@ from unittest.mock import MagicMock, Mock, patch
import pytest
+from marimo._ast.variables import is_mangled_local
from marimo._config.config import DEFAULT_CONFIG
from marimo._dependencies.dependencies import DependencyManager
from marimo._messaging.cell_output import CellChannel
@@ -330,26 +331,6 @@ class TestExecution:
# Make sure the array and its child are updated
assert k.globals["state"] == 5
- async def test_set_local_var_ui_element_value(
- self, any_kernel: Kernel
- ) -> None:
- k = any_kernel
- await k.run([ExecuteCellCommand("0", "import marimo as mo")])
- await k.run(
- [ExecuteCellCommand("1", "_s = mo.ui.slider(0, 10, value=1); _s")]
- )
- # _s's name is mangled to _cell_1_s because it is local
- assert k.globals["_cell_1_s"].value == 1
-
- element_id = k.globals["_cell_1_s"]._id
- # This shouldn't crash the kernel, and s's value should still be
- # updated
- await k.set_ui_element_value(
- UpdateUIElementCommand.from_ids_and_values([(element_id, 5)]),
- notify_frontend=False,
- )
- assert k.globals["_cell_1_s"].value == 5
-
async def test_creation_with_ui_element_value(
self, any_kernel: Kernel
) -> None:
@@ -1759,9 +1740,71 @@ except NameError:
self, k: Kernel, exec_req: ExecReqProvider
) -> None:
await k.run([er := exec_req.get("_x = 1")])
- assert k.globals[f"_cell_{er.cell_id}_x"] == 1
- await k.run([ExecuteCellCommand(er.cell_id, "None")])
- assert f"_cell_{er.cell_id}_x" not in k.globals
+ assert not any(is_mangled_local(name) for name in k.globals)
+
+ async def test_temporary_closed_over_by_function_not_deleted(
+ self, k: Kernel, exec_req: ExecReqProvider
+ ) -> None:
+ await k.run([exec_req.get("_x = 1\ndef fn():\n return _x")])
+ assert k.globals["fn"]() == 1
+
+ async def test_temporary_closed_over_by_lambda_not_deleted(
+ self, k: Kernel, exec_req: ExecReqProvider
+ ) -> None:
+ await k.run([exec_req.get("_x = 1\nlam = lambda: _x")])
+ assert k.globals["lam"]() == 1
+
+ async def test_temporary_closed_over_by_class_not_deleted(
+ self, k: Kernel, exec_req: ExecReqProvider
+ ) -> None:
+ await k.run(
+ [
+ exec_req.get(
+ "_x = 1\nclass C:\n def m(self):\n return _x"
+ )
+ ]
+ )
+ assert k.globals["C"]().m() == 1
+
+ async def test_transitive_temporary_closed_over_not_deleted(
+ self, k: Kernel, exec_req: ExecReqProvider
+ ) -> None:
+ # `foo` closes over the private helper `_helper`, which in turn closes
+ # over `_data`; both temporaries must survive for `foo` to be callable.
+ await k.run(
+ [
+ exec_req.get(
+ "_data = 1\n"
+ "def _helper():\n return _data\n"
+ "def foo():\n return _helper()"
+ )
+ ]
+ )
+ assert k.globals["foo"]() == 1
+
+ async def test_temporary_last_expression_retained_as_output(
+ self, k: Kernel
+ ) -> None:
+ # A cell whose last expression is a temporary UI element: the temporary
+ # is deleted from globals, but the kernel should hang on to a reference.
+ # This is needed for RPCs in particular.
+ await k.run(
+ [ExecuteCellCommand(cell_id="0", code="import marimo as mo")]
+ )
+ await k.run(
+ [
+ ExecuteCellCommand(
+ cell_id="1",
+ code="_s = mo.ui.slider(0, 10, value=1); _s",
+ )
+ ]
+ )
+ # The temporary is gone from globals ...
+ assert not any(is_mangled_local(name) for name in k.globals)
+ # ... but the kernel retains it as the cell's output.
+ output = k.graph.cells["1"].output
+ assert isinstance(output, UIElement)
+ assert output.value == 1
async def test_private_recursive_function(
self, any_kernel: Kernel, exec_req: ExecReqProvider