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: handle private imports (#9704)

Dylan Madisettif08787ac0149
diff --git a/docs/guides/reactivity.md b/docs/guides/reactivity.md
index 4cea874e47..49c23775b9 100644
--- a/docs/guides/reactivity.md
+++ b/docs/guides/reactivity.md
@@ -168,6 +168,13 @@ Variables prefixed with an underscore (_e.g._, `_x`) are "local" to a
cell: they can't be read by other cells. Multiple cells can reuse the same
local variables names.
+!!! note "Underscore-prefixed imports"
+ Imported names are also variables, so an import bound to an
+ underscore-prefixed name (`import numpy as _np`, or `from ibis import _`)
+ is local to the cell that imports it. When the imported symbol itself
+ starts with an underscore and you want to use it across cells, alias it
+ to a name without a leading underscore: `from ibis import _ as d`.
+
#### Encapsulating code in functions
If you want most or all the variables in a cell to be temporary, prefixing each
diff --git a/marimo/_ast/visitor.py b/marimo/_ast/visitor.py
index a98b8f37e0..bd5efa01f9 100644
--- a/marimo/_ast/visitor.py
+++ b/marimo/_ast/visitor.py
@@ -1021,16 +1021,21 @@ class ScopedVisitor(ast.NodeVisitor):
)
for block in reversed(self.block_stack):
if block == self.block_stack[0]:
- # At top-level scope: mangle only if the mangled name is
- # already defined. When called from a nested scope
- # (len > 1), also mangle even if the top-level block
- # doesn't define it yet — this handles recursive calls to
- # underscore-prefixed functions, where the function name
- # isn't registered in the top-level block until after its
- # body is visited.
- if (
- block.is_defined(mangled_name)
- or len(self.block_stack) > 1
+ # A local (underscore-prefixed) reference resolves
+ # against the top-level block. Leave it raw only when
+ # the raw name is a top-level definition, which happens
+ # solely for no-alias underscore imports (`from pkg
+ # import _c` — the user has no control over the
+ # package's symbol name, so it is deliberately not
+ # mangled). Everything else is mangled: names whose
+ # mangled def exists, forward references (e.g. the body
+ # of a recursive underscore-prefixed function, visited
+ # before its name is registered), and references to
+ # names this cell never defines — the latter guarantees
+ # one cell's raw import can never leak into another
+ # cell through the shared globals.
+ if block.is_defined(mangled_name) or not block.is_defined(
+ node.id
):
node.id = mangled_name
elif block.is_defined(node.id):
diff --git a/marimo/_runtime/executor/executor.py b/marimo/_runtime/executor/executor.py
index a75285feee..de47a2fbe9 100644
--- a/marimo/_runtime/executor/executor.py
+++ b/marimo/_runtime/executor/executor.py
@@ -7,6 +7,7 @@ import asyncio
from typing import TYPE_CHECKING, Any, Protocol
from marimo._ast.cell import _is_coroutine
+from marimo._ast.variables import demangle_locals_in_text
from marimo._runtime.exceptions import MarimoRuntimeException
from marimo._types.globals import MutableGlobals
@@ -14,6 +15,21 @@ if TYPE_CHECKING:
from marimo._ast.cell import CellImpl
+def _demangle_name_error(e: BaseException) -> None:
+ """Rewrite a NameError's message to use the name the user wrote.
+
+ Cell-local (underscore-prefixed) references are compiled to mangled
+ names (`_cell_<id>_x`); when one is undefined, CPython's message
+ exposes the mangled form. The `name` attribute is left untouched for
+ downstream consumers that resolve it structurally.
+ """
+ if isinstance(e, NameError) and e.args:
+ e.args = tuple(
+ demangle_locals_in_text(arg) if isinstance(arg, str) else arg
+ for arg in e.args
+ )
+
+
def _strip_frame(e: BaseException, count: int = 1) -> None:
"""Drop the top `count` frames from `e.__traceback__`.
@@ -61,6 +77,7 @@ class DefaultExecutor:
except BaseException as e:
# Strip our own frame so user-facing tracebacks start at user code.
_strip_frame(e)
+ _demangle_name_error(e)
raise MarimoRuntimeException from e
async def execute_cell_async(
@@ -81,4 +98,5 @@ class DefaultExecutor:
raise
except BaseException as e:
_strip_frame(e)
+ _demangle_name_error(e)
raise MarimoRuntimeException from e
diff --git a/marimo/_runtime/runner/cell_runner.py b/marimo/_runtime/runner/cell_runner.py
index 66c33daaf7..45295ae860 100644
--- a/marimo/_runtime/runner/cell_runner.py
+++ b/marimo/_runtime/runner/cell_runner.py
@@ -1,6 +1,7 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+import ast
import asyncio
import io
import traceback
@@ -8,7 +9,11 @@ from pathlib import Path
from types import TracebackType
from typing import TYPE_CHECKING, Any
-from marimo._ast.variables import unmangle_local
+from marimo._ast.variables import (
+ if_local_then_mangle,
+ is_local,
+ unmangle_local,
+)
from marimo._config.config import ExecutionType, MarimoConfig, OnCellChangeType
from marimo._dependencies.dependencies import DependencyManager
from marimo._dependencies.errors import ManyModulesNotFoundError
@@ -61,6 +66,31 @@ if TYPE_CHECKING:
from marimo._runtime.state import State
+def _find_aliased_import(code: str, name: str) -> str | None:
+ """If `code` imports `name`, return that import re-aliased publicly.
+
+ Builds the suggestion statement for the cell-local NameError hint,
+ e.g. `from ibis import _` -> "from ibis import _ as lib". Returns
+ None when `code` doesn't parse or doesn't import `name`.
+ """
+ try:
+ tree = ast.parse(code)
+ except SyntaxError:
+ return None
+ alias_name = name.lstrip("_") or "lib"
+ for node in ast.walk(tree):
+ if isinstance(node, ast.ImportFrom):
+ for alias in node.names:
+ if (alias.asname or alias.name) == name:
+ module = "." * node.level + (node.module or "")
+ return f"from {module} import {alias.name} as {alias_name}"
+ elif isinstance(node, ast.Import):
+ for alias in node.names:
+ if (alias.asname or alias.name.split(".")[0]) == name:
+ return f"import {alias.name} as {alias_name}"
+ return None
+
+
def _should_broadcast_data() -> bool:
"""Whether data (variables, datasets, etc.) should be broadcast.
@@ -393,6 +423,61 @@ class Runner:
# Default to regular error for self reference in relaxed
# mode.
exception = unwrapped_exception
+ elif (
+ isinstance(unwrapped_exception, NameError)
+ and (local_name := getattr(unwrapped_exception, "name", None))
+ is not None
+ and is_local(local_name)
+ ):
+ # A cell-local (underscore-prefixed) name that never resolved.
+ # Such names are not graph definitions, so the MissingRef path
+ # above cannot blame a cell; find one that defines it as a
+ # temporary — either raw (no-alias underscore imports, which
+ # are deliberately left unmangled) or mangled (every other
+ # private). The failing reference may itself be mangled
+ # (`_cell_<id>_x`); unmangle so the message and the search use
+ # the name the user wrote. Prefer an import definition for the
+ # blame: `_` in particular is commonly both an imported API
+ # (`from ibis import _`) and a throwaway assignment in
+ # unrelated cells.
+ local_name, _ = unmangle_local(local_name)
+ defining_cell: CellId_t | None = None
+ aliased_import: str | None = None
+ for cid, other in self.graph.cells.items():
+ if cid == cell_id:
+ continue
+ if (
+ local_name in other.temporaries
+ or if_local_then_mangle(local_name, cid)
+ in other.temporaries
+ ):
+ stmt = _find_aliased_import(other.code, local_name)
+ if defining_cell is None or stmt is not None:
+ defining_cell = cid
+ aliased_import = stmt
+ if stmt is not None:
+ break
+ if defining_cell is not None:
+ if aliased_import is not None:
+ remedy = (
+ "To use it across cells, alias the import to a "
+ "name without a leading underscore: "
+ f"`{aliased_import}`."
+ )
+ else:
+ remedy = (
+ "To use it across cells, remove the leading "
+ "underscore."
+ )
+ output = MarimoExceptionRaisedError(
+ f"Name `{local_name}` is not defined. Names prefixed "
+ "with an underscore are local to the cell that "
+ f"defines them. {remedy} `{local_name}` is defined "
+ "as a cell-local name in ",
+ "NameError",
+ defining_cell,
+ )
+ exception = output
# Handle other special runtime errors.
elif isinstance(
unwrapped_exception,
diff --git a/marimo/_save/hash.py b/marimo/_save/hash.py
index cf433fc555..2ad2b9b13d 100644
--- a/marimo/_save/hash.py
+++ b/marimo/_save/hash.py
@@ -690,7 +690,22 @@ class BlockHasher:
imports = get_imports(scope)
for local_ref in sorted(refs):
ref = if_local_then_mangle(local_ref, self.cell_id)
- if ref in imports:
+ # An underscore import (e.g. `import marimo as _private`) is
+ # mangled in the cell, but a cached function that references
+ # it can surface the raw, unmangled name as a ref (its body
+ # is hashed in the function scope). Depending on the path the
+ # import may therefore appear in `imports` under either the
+ # mangled `ref` or the raw `local_ref`. Accept either so the
+ # module is treated as an import (and not pickled, which
+ # would raise `cannot pickle 'module' object`).
+ import_key: Name | None = (
+ ref
+ if ref in imports
+ else local_ref
+ if local_ref in imports
+ else None
+ )
+ if import_key is not None:
# TODO: There may be a way to tie this in with module watching.
# e.g. module watcher could mutate the version number based
# last updated timestamp.
@@ -699,15 +714,18 @@ class BlockHasher:
if self.pin_modules:
# Fall back to the in-scope value (which may be a module
# stub) so its replayed `__version__` reproduces the pinned
- # hash.
- module = sys.modules.get(imports[ref].module) or scope.get(
- local_ref
+ # hash. The scope may hold the module under either the
+ # mangled or the raw name, mirroring `import_key`.
+ module = (
+ sys.modules.get(imports[import_key].module)
+ or scope.get(ref)
+ or scope.get(local_ref)
)
version = getattr(module, "__version__", "") or ""
if not version:
module = sys.modules.get(
- imports[ref].namespace
- ) or scope.get(imports[ref].namespace)
+ imports[import_key].namespace
+ ) or scope.get(imports[import_key].namespace)
version = getattr(module, "__version__", "") or ""
content_serialization[ref] = type_sign(
diff --git a/tests/_ast/test_visitor.py b/tests/_ast/test_visitor.py
index 63a5c8c78d..f7ea1632ee 100644
--- a/tests/_ast/test_visitor.py
+++ b/tests/_ast/test_visitor.py
@@ -2,6 +2,7 @@
from __future__ import annotations
import ast
+import re
from inspect import cleandoc
from textwrap import dedent
@@ -985,6 +986,109 @@ def test_relative_from_import() -> None:
]
+def test_underscore_as_imports_are_cell_local() -> None:
+ # An underscore-prefixed `as` alias is mangled, i.e. it is treated as
+ # a cell-local (private) name. This preserves the documented contract
+ # that underscore-prefixed names are private and may be redefined
+ # across cells: two cells may each `import numpy as _np` without a
+ # MultipleDefinitionError. References to the alias within the cell
+ # (including in a nested decorator/body scope) resolve to the mangled
+ # name.
+ prefix = "_cell_test_"
+ cases = [
+ ("import marimo as _mo", {f"{prefix}mo"}),
+ ("import a.b as _c", {f"{prefix}c"}),
+ ("from a.b import _c as _d", {f"{prefix}d"}),
+ (
+ "import marimo as _private\n"
+ "@_private.cache\n"
+ "def f(x):\n"
+ " return _private.md('x')\n",
+ {f"{prefix}private", "f"},
+ ),
+ # `from x import y as _p` referenced in nested scopes (class base,
+ # decorator, function body) must mangle the references too, so the
+ # cell-local definition and its uses stay consistent.
+ (
+ "from a.b import c as _private\nclass C(_private.X):\n pass\n",
+ {f"{prefix}private", "C"},
+ ),
+ (
+ "from a.b import c as _also_private\n"
+ "@_also_private.deco\n"
+ "def f(x):\n"
+ " return _also_private.g(x)\n",
+ {f"{prefix}also_private", "f"},
+ ),
+ ]
+ for source, expected_defs in cases:
+ v = visitor.ScopedVisitor(mangle_prefix="cell_test")
+ mod = ast.parse(source)
+ v.visit(mod)
+ assert v.defs == expected_defs, source
+ unparsed = ast.unparse(mod)
+ # The alias is rewritten to its mangled, cell-local form.
+ assert prefix in unparsed, (
+ f"alias was not mangled in {source!r}: {unparsed!r}"
+ )
+ # No reference to the raw alias survives unmangled: every mangled
+ # def has its raw counterpart fully rewritten (def *and* uses).
+ for mangled in expected_defs:
+ if not mangled.startswith(prefix):
+ continue
+ raw = "_" + mangled[len(prefix) :]
+ assert re.search(rf"\b{re.escape(raw)}\b", unparsed) is None, (
+ f"raw alias {raw!r} leaked unmangled in {source!r}: "
+ f"{unparsed!r}"
+ )
+
+
+def test_no_alias_underscore_import_refs_not_mangled() -> None:
+ # Regression for #9151: a no-alias underscore import (e.g.
+ # `from pkg import _camera`) defines the *raw* name, because the user
+ # can't control the package's module name. References to it inside a
+ # nested scope (class base, decorator, function body) must therefore
+ # stay raw too, otherwise they resolve to an undefined mangled name
+ # (`NameError: name '_cell_<id>_camera' is not defined`).
+ prefix = "_cell_test_"
+ cases = [
+ # (source, expected_defs)
+ ("from a.b import _c", {"_c"}),
+ ("from a.b import _c, _d", {"_c", "_d"}),
+ ("import _foo", {"_foo"}),
+ # A dotted import with an underscore root has no resolvable local
+ # name to mangle (`_private.submodule` is reached through the raw
+ # root binding) — the case that ruled out mangling imports
+ # wholesale.
+ (
+ "import _private.submodule\ny = _private.submodule.thing\n",
+ {"_private", "y"},
+ ),
+ (
+ "from a.b import _camera\nclass C(_camera.Observer):\n pass\n",
+ {"_camera", "C"},
+ ),
+ (
+ "from a.b import _camera\n"
+ "@_camera.deco\n"
+ "def f(x):\n"
+ " return _camera.g(x)\n",
+ {"_camera", "f"},
+ ),
+ ]
+ for source, expected_defs in cases:
+ v = visitor.ScopedVisitor(mangle_prefix="cell_test")
+ mod = ast.parse(source)
+ v.visit(mod)
+ assert v.defs == expected_defs, source
+ unparsed = ast.unparse(mod)
+ # The raw import name is never mangled, neither at the definition
+ # nor at any (possibly nested) reference.
+ assert prefix not in unparsed, (
+ f"no-alias import was mangled in {source!r}: {unparsed!r}"
+ )
+
+
def test_from_import_star() -> None:
expr = "from a.b.c import *"
v = visitor.ScopedVisitor()
diff --git a/tests/_runtime/test_runtime.py b/tests/_runtime/test_runtime.py
index 1c392e0dd2..59bc726d06 100644
--- a/tests/_runtime/test_runtime.py
+++ b/tests/_runtime/test_runtime.py
@@ -872,6 +872,127 @@ except NameError:
assert "_sys" not in k.globals
assert k.globals["msize"] == sys.maxsize
+ async def test_underscore_prefixed_import_in_cell(
+ self, any_kernel: Kernel
+ ) -> None:
+ # An underscore-prefixed `as` alias is cell-local (mangled), but
+ # must still resolve when used within the same cell, including in
+ # a nested decorator/body scope.
+ k = any_kernel
+ await k.run(
+ [
+ ExecuteCellCommand(
+ cell_id="0",
+ code=(
+ "import marimo as _mo\n"
+ "@_mo.cache\n"
+ "def f(x):\n"
+ " return _mo.md(str(x))\n"
+ "msg = f(1)"
+ ),
+ ),
+ ]
+ )
+ assert not k.errors, k.errors
+ # The alias is cell-local, so it never leaks into globals.
+ assert "_mo" not in k.globals
+ assert "1" in k.globals["msg"].text
+
+ async def test_underscore_prefixed_import_across_cells_no_conflict(
+ self, k: Kernel
+ ) -> None:
+ # Underscore-prefixed `as` aliases are cell-local/private: two
+ # cells may each `import sys as _sys` without triggering a
+ # MultipleDefinitionError. Each cell sees its own mangled binding.
+ await k.run(
+ [
+ ExecuteCellCommand(
+ cell_id="0",
+ code="import sys as _sys; a = _sys.maxsize",
+ ),
+ ExecuteCellCommand(
+ cell_id="1",
+ code="import sys as _sys; b = _sys.maxsize",
+ ),
+ ]
+ )
+ assert not k.errors, k.errors
+ assert k.globals["a"] == sys.maxsize
+ assert k.globals["b"] == sys.maxsize
+ # The private alias is not promoted to a graph def.
+ assert "_sys" not in k.globals
+
+ async def test_no_alias_underscore_import_nested_scope(
+ self, any_kernel: Kernel
+ ) -> None:
+ # Regression for #9151 (MO-5835): a no-alias underscore import
+ # (`from pkg import _name`) keeps its raw name — the user cannot
+ # control the package's symbol name — so references to it in
+ # nested scopes (function bodies, decorators, class bases) must
+ # stay raw as well, not be mangled to `_cell_<id>_name`.
+ k = any_kernel
+ await k.run(
+ [
+ ExecuteCellCommand(
+ cell_id="0",
+ code=(
+ "from marimo import _ast\n"
+ "top = _ast.__name__\n"
+ "def g():\n"
+ " return _ast.__name__\n"
+ "nested = g()"
+ ),
+ ),
+ ]
+ )
+ assert not k.errors, k.errors
+ assert k.globals["top"] == "marimo._ast"
+ assert k.globals["nested"] == "marimo._ast"
+
+ async def test_no_alias_underscore_import_is_cell_local(
+ self, k: Kernel
+ ) -> None:
+ # MO-5949: a no-alias underscore import keeps its raw name but is
+ # still cell-local — it never becomes a graph definition, so other
+ # cells cannot read it.
+ await k.run(
+ [
+ ExecuteCellCommand(
+ cell_id="0",
+ code="from marimo import _ast\na = _ast.__name__",
+ ),
+ ExecuteCellCommand(
+ cell_id="1",
+ code="b = _ast.__name__",
+ ),
+ ]
+ )
+ assert k.globals["a"] == "marimo._ast"
+ # The import is not shared: the other cell fails with a NameError.
+ assert "b" not in k.globals
+
+ async def test_underscore_import_public_alias_is_shared(
+ self, k: Kernel
+ ) -> None:
+ # MO-5949: aliasing an underscore-prefixed import to a name
+ # without a leading underscore makes it a regular, shared
+ # definition usable across cells.
+ await k.run(
+ [
+ ExecuteCellCommand(
+ cell_id="0",
+ code="from marimo import _ast as ast_mod",
+ ),
+ ExecuteCellCommand(
+ cell_id="1",
+ code="c = ast_mod.__name__",
+ ),
+ ]
+ )
+ assert not k.errors, k.errors
+ assert k.globals["c"] == "marimo._ast"
+ assert "ast_mod" in k.globals
+
async def test_cell_transitioned_to_error_is_not_stale(
self, lazy_kernel: Kernel
) -> None:
@@ -3825,6 +3946,66 @@ class TestErrorHandling:
if sys.version_info >= (3, 13):
assert "Did you mean: 'aaa'?" in errors[0].msg
+ async def test_name_error_private_import_hint(
+ self, mocked_kernel: MockedKernel, exec_req: ExecReqProvider
+ ) -> None:
+ # MO-6804 / #10223: referencing another cell's underscore import
+ # (`from ibis import _`) fails because such names are cell-local.
+ # The bare Python NameError is misleading; marimo should explain
+ # the privacy rule and suggest aliasing the import.
+ k = mocked_kernel.k
+ await k.run(
+ [
+ exec_req.get(
+ "import sys, types\n"
+ "_mod = types.ModuleType('fakelib')\n"
+ "_mod._ = 42\n"
+ "sys.modules['fakelib'] = _mod\n"
+ "ready = True"
+ ),
+ exec_req.get("ready\nfrom fakelib import _"),
+ exec_req.get("res = _ + 1"),
+ ]
+ )
+ assert "res" not in k.globals
+ cell_notifications = mocked_kernel.stream.cell_notifications
+ error_cell_notification = _filter_to_error_ops(cell_notifications)
+ assert len(error_cell_notification) == 1
+ errors = _parse_error_output(error_cell_notification[0])
+ assert len(errors) == 1
+ assert isinstance(errors[0], MarimoExceptionRaisedError)
+ assert errors[0].exception_type == "NameError"
+ assert "local to the cell" in errors[0].msg
+ assert "`from fakelib import _ as lib`" in errors[0].msg
+ # Blames the importing cell.
+ assert errors[0].raising_cell is not None
+
+ async def test_name_error_private_variable_hint(
+ self, mocked_kernel: MockedKernel, exec_req: ExecReqProvider
+ ) -> None:
+ # Referencing another cell's private (underscore-prefixed)
+ # variable produces a hint about the privacy rule rather than a
+ # bare NameError with a mangled name.
+ k = mocked_kernel.k
+ await k.run(
+ [
+ exec_req.get("_x = 1"),
+ exec_req.get("y = _x"),
+ ]
+ )
+ assert "y" not in k.globals
+ cell_notifications = mocked_kernel.stream.cell_notifications
+ error_cell_notification = _filter_to_error_ops(cell_notifications)
+ assert len(error_cell_notification) == 1
+ errors = _parse_error_output(error_cell_notification[0])
+ assert len(errors) == 1
+ assert isinstance(errors[0], MarimoExceptionRaisedError)
+ assert errors[0].exception_type == "NameError"
+ # The message shows the name as written, not the mangled form.
+ assert "Name `_x` is not defined" in errors[0].msg
+ assert "remove the leading underscore" in errors[0].msg
+ assert errors[0].raising_cell is not None
+
async def test_error_handling_in_run_mode_stop(
self, run_mode_kernel: MockedKernel, exec_req: ExecReqProvider
) -> None:
diff --git a/tests/_save/test_cache.py b/tests/_save/test_cache.py
index 853b69ea51..3958ba757d 100644
--- a/tests/_save/test_cache.py
+++ b/tests/_save/test_cache.py
@@ -1111,6 +1111,62 @@ class TestCacheDecorator:
assert k.stdout.messages.count("ran") == 1
assert k.globals["foo"].hits == 3
+ async def test_lru_cache_underscore_alias(
+ self, k: Kernel, exec_req: ExecReqProvider
+ ) -> None:
+ # Regression: `import marimo as _private` (underscore alias) used to
+ # blow up cache hashing because mangled scope keys (`_cell_<id>__private`)
+ # don't match the unmangled-ref lookup used during the cache attempt.
+ await k.run(
+ [
+ exec_req.get(
+ """
+ import marimo as _private
+
+ @_private.lru_cache(maxsize=128)
+ def f(x):
+ return x * 2
+
+ a = f(1)
+ b = f(1)
+ c = f(2)
+ """
+ ),
+ ]
+ )
+
+ assert not k.stderr.messages, k.stderr
+ assert k.globals["a"] == 2
+ assert k.globals["b"] == 2
+ assert k.globals["c"] == 4
+ # Second `f(1)` should hit the cache.
+ assert k.globals["f"].hits == 1
+
+ async def test_cache_underscore_alias(
+ self, k: Kernel, exec_req: ExecReqProvider
+ ) -> None:
+ await k.run(
+ [
+ exec_req.get(
+ """
+ import marimo as _private
+
+ @_private.cache
+ def f(x):
+ return x * 3
+
+ a = f(1)
+ b = f(1)
+ """
+ ),
+ ]
+ )
+
+ assert not k.stderr.messages, k.stderr
+ assert k.globals["a"] == 3
+ assert k.globals["b"] == 3
+ assert k.globals["f"].hits == 1
+
async def test_persistent_cache(
self, k: Kernel, exec_req: ExecReqProvider
) -> None: