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
Run notebook sandboxes from uv script environments (#10696)
Trevor Manz3ae4a1596208
diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.pyindex 0b7fff5b33..224738e046 100644--- a/marimo/_cli/cli.py+++ b/marimo/_cli/cli.py@@ -21,10 +21,7 @@ from marimo._cli.config.commands import configfrom marimo._cli.convert.commands import convertfrom marimo._cli.development.commands import developmentfrom marimo._cli.envinfo import get_system_info-from marimo._cli.errors import (- MarimoCLIMissingDependencyError,- MarimoCLIRuntimeError,-)+from marimo._cli.errors import MarimoCLIRuntimeErrorfrom marimo._cli.export.commands import exportfrom marimo._cli.files.file_path import validate_namefrom marimo._cli.help_formatter import ColoredGroup, RunCommand@@ -540,23 +537,19 @@ def edit(if sandbox_mode is SandboxMode.SINGLE:from marimo._cli.sandbox import run_in_sandbox- run_in_sandbox(sys.argv[1:], name=name, additional_features=["lsp"])- return+ sys.exit(+ run_in_sandbox(+ sys.argv[1:], name=name, additional_features=["lsp"]+ )+ )# Multi-file sandbox: use IPC kernels with per-notebook sandboxed venvsif sandbox_mode is SandboxMode.MULTI:- # Check for pyzmq dependency- from marimo._dependencies.dependencies import DependencyManager-- if not DependencyManager.zmq.has():- raise MarimoCLIMissingDependencyError(- "pyzmq is required when running the marimo edit server on a directory with --sandbox.",- "marimo[sandbox]",- )-# Enable script metadata management for sandboxed notebooksos.environ["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA = True+ os.environ["MARIMO_SANDBOX_MODE"] = "multi"+ GLOBAL_SETTINGS.SANDBOX_MODE = "multi"# Check shared memory availability early (required for edit mode to# communicate between the server process and kernel subprocess)@@ -747,8 +740,11 @@ def new(from marimo._cli.sandbox import run_in_sandbox# TODO: consider adding recommended as well- run_in_sandbox(sys.argv[1:], name=None, additional_features=["lsp"])- return+ sys.exit(+ run_in_sandbox(+ sys.argv[1:], name=None, additional_features=["lsp"]+ )+ )workspace: NotebookWorkspace | None = None@@ -1234,27 +1230,7 @@ def run(sandbox=sandbox, name=validated_paths[0])if sandbox_mode is SandboxMode.SINGLE:- run_in_sandbox(sys.argv[1:], name=validated_paths[0])- return-- # Multi-file sandbox: use IPC kernels with per-notebook sandboxed venvs- if sandbox_mode is SandboxMode.MULTI:- # Check for pyzmq dependency- from marimo._dependencies.dependencies import DependencyManager-- if not DependencyManager.zmq.has():- raise MarimoCLIMissingDependencyError(- "pyzmq is required when running a gallery with --sandbox.",- "marimo[sandbox]",- )- elif is_multi:- from marimo._dependencies.dependencies import DependencyManager-- if not DependencyManager.zmq.has():- raise MarimoCLIMissingDependencyError(- "pyzmq is required for running multiple notebooks.",- "pyzmq",- )+ sys.exit(run_in_sandbox(sys.argv[1:], name=validated_paths[0]))workspace = _create_run_workspace(validated_paths, watch=watch)diff --git a/marimo/_cli/export/_common.py b/marimo/_cli/export/_common.pyindex 30c578ab27..4619d794f4 100644--- a/marimo/_cli/export/_common.py+++ b/marimo/_cli/export/_common.py@@ -1,8 +1,12 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations+import contextlibimport json+import signalimport subprocess+import threading+from dataclasses import dataclassfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any@@ -12,9 +16,12 @@ from marimo._server.files.directory_scanner import DirectoryScannerfrom marimo._server.workspace import flatten_filesfrom marimo._utils.http import HTTPException, HTTPStatusfrom marimo._utils.marimo_path import MarimoPath+from marimo._utils.subprocess import kill_subprocessif TYPE_CHECKING:- from collections.abc import Iterable+ from collections.abc import Iterable, Iterator++ from marimo._environments.environment import Environmentdef is_multi_target(paths: list[Path]) -> bool:@@ -45,51 +52,111 @@ def collect_notebooks(paths: Iterable[Path]) -> list[MarimoPath]:return [notebooks[k] for k in sorted(notebooks)]+@dataclass(frozen=True)+class SandboxTarget:+ """Where a sandboxed export runs.++ `environment` is the notebook's script environment, or None for a+ notebook without a metadata block, which runs ephemerally.+ """++ environment: Environment | None++class SandboxVenvPool:+ """Caches synchronized script environments by notebook path."""+def __init__(self) -> None:- self._envs: dict[tuple[str, ...], tuple[str, str]] = {}+ self._targets: dict[str, SandboxTarget] = {}- def get_python(self, notebook_path: str) -> str:- from marimo._cli.sandbox import (- build_sandbox_venv,- get_sandbox_requirements,- )+ def get_target(self, notebook_path: str) -> SandboxTarget:+ from marimo._environments.environment import sync_notebook+ from marimo._environments.uv import UvMissingScriptMetadataError- requirements = tuple(get_sandbox_requirements(notebook_path))- existing = self._envs.get(requirements)+ key = str(Path(notebook_path).resolve())+ existing = self._targets.get(key)if existing is not None:- return existing[1]+ return existing- sandbox_dir, venv_python = build_sandbox_venv(notebook_path)- self._envs[requirements] = (sandbox_dir, venv_python)- return venv_python+ try:+ target = SandboxTarget(environment=sync_notebook(key))+ except UvMissingScriptMetadataError:+ target = SandboxTarget(environment=None)+ self._targets[key] = target+ return targetdef close(self) -> None:- from marimo._cli.sandbox import cleanup_sandbox_dir+ # uv owns the environments; there is nothing to remove.+ self._targets.clear()+++def _export_termination_signals() -> Iterator[None]:+ """Let termination unwind the runner so its isolated child is reaped."""+ previous = {}- for sandbox_dir, _ in self._envs.values():- cleanup_sandbox_dir(sandbox_dir)- self._envs.clear()+ def terminate(signum: int, _frame: object) -> None:+ raise SystemExit(128 + signum)++ try:+ if threading.current_thread() is threading.main_thread():+ for name in ("SIGTERM", "SIGHUP"):+ signum = getattr(signal, name, None)+ if (+ signum is not None+ and signal.getsignal(signum) == signal.SIG_DFL+ ):+ previous[signum] = signal.signal(signum, terminate)+ yield+ finally:+ for signum, handler in previous.items():+ signal.signal(signum, handler)def run_python_subprocess(*,- venv_python: str,+ sandbox: SandboxTarget,script: str,payload: dict[str, Any],action: str,) -> str:- result = subprocess.run(- [venv_python, "-c", script, json.dumps(payload)],- check=False,- capture_output=True,- text=True,- )- if result.returncode != 0:- stderr = result.stderr.strip()+ import platform++ from marimo._environments.environment import launch, launch_isolated+ from marimo._environments.overlay import runtime_overlay++ args = ["-c", script, json.dumps(payload)]+ overlay = runtime_overlay()+ if sandbox.environment is not None:+ plan = launch(sandbox.environment, args, overlay=overlay)+ else:+ plan = launch_isolated(+ args, overlay=overlay, python=platform.python_version()+ )+ with (+ _export_termination_signals(),+ subprocess.Popen(+ list(plan.argv),+ env=plan.env,+ start_new_session=plan.start_new_session,+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ text=True,+ ) as process,+ ):+ try:+ stdout, stderr = process.communicate()+ except BaseException:+ kill_subprocess(process, start_new_session=plan.start_new_session)+ raise+ if process.returncode != 0:+ # Identify the real launcher without exposing requirement URLs,+ # credentials, notebook code, or the serialized request payload.+ launcher = Path(plan.argv[0]).name+ command = f"{launcher} <sandbox arguments> -c <script> <payload>"raise click.ClickException(f"Failed to {action} in sandbox.\n\n"- f"Command:\n\n {venv_python} -c <script>\n\n"- f"Stderr:\n\n{stderr}"+ f"Command:\n\n {command}\n\n"+ f"Stderr:\n\n{stderr.strip()}")- return result.stdout+ return stdoutdiff --git a/marimo/_cli/export/commands.py b/marimo/_cli/export/commands.pyindex d5cfb4914b..d3f3176285 100644--- a/marimo/_cli/export/commands.py+++ b/marimo/_cli/export/commands.py@@ -295,8 +295,7 @@ def html(sandbox = maybe_prompt_run_in_sandbox(name)if sandbox:- run_in_sandbox(sys.argv[1:], name=name)- return+ sys.exit(run_in_sandbox(sys.argv[1:], name=name))cli_args = parse_args(args)@@ -379,8 +378,7 @@ def script(Export a marimo notebook as a flat script, in topological order."""if sandbox:- run_in_sandbox(sys.argv[1:], name=name)- return+ sys.exit(run_in_sandbox(sys.argv[1:], name=name))def export_callback(file_path: MarimoPath) -> ExportResult:try:@@ -462,8 +460,7 @@ def md(Export a marimo notebook as a code fenced markdown document."""if sandbox:- run_in_sandbox(sys.argv[1:], name=name)- return+ sys.exit(run_in_sandbox(sys.argv[1:], name=name))filename = str(output) if output is not None else None@@ -570,12 +567,13 @@ def ipynb(sandbox = maybe_prompt_run_in_sandbox(name)if sandbox:- run_in_sandbox(- sys.argv[1:],- name=name,- additional_deps=["nbformat"],+ sys.exit(+ run_in_sandbox(+ sys.argv[1:],+ name=name,+ additional_deps=["nbformat"],+ ))- returntry:DependencyManager.nbformat.require(@@ -760,12 +758,13 @@ def pdf(export_deps = ["nbformat"]# Adding webpdf extras to sandbox even if `webpdf` is False, since standard PDF export may fall back to it.export_deps.append("nbconvert[webpdf]")- run_in_sandbox(- sys.argv[1:],- name=name,- additional_deps=export_deps,+ sys.exit(+ run_in_sandbox(+ sys.argv[1:],+ name=name,+ additional_deps=export_deps,+ ))- returntry:DependencyManager.require_many(@@ -1026,8 +1025,7 @@ def html_wasm(sandbox = maybe_prompt_run_in_sandbox(name)if sandbox:- run_in_sandbox(sys.argv[1:], name=name)- return+ sys.exit(run_in_sandbox(sys.argv[1:], name=name))out_dir = outputfilename = "index.html"diff --git a/marimo/_cli/export/session.py b/marimo/_cli/export/session.pyindex f0080209d4..8a017324da 100644--- a/marimo/_cli/export/session.py+++ b/marimo/_cli/export/session.py@@ -11,6 +11,7 @@ import clickfrom marimo._cli.errors import MarimoCLIMissingDependencyErrorfrom marimo._cli.export._common import (+ SandboxTarget,SandboxVenvPool,collect_notebooks,is_multi_target,@@ -64,9 +65,9 @@ async def _export_session_snapshot(marimo_path: MarimoPath,*,notebook_args: tuple[str, ...],- venv_python: str | None = None,+ sandbox: SandboxTarget | None = None,) -> tuple[NotebookSessionV1, bool]:- if venv_python is None:+ if sandbox is None:cli_args = parse_args(notebook_args) if notebook_args else {}file_manager = load_notebook(marimo_path.absolute_name)@@ -95,13 +96,13 @@ async def _export_session_snapshot(}return await asyncio.to_thread(_export_session_snapshot_in_subprocess,- venv_python,+ sandbox,payload,)def _export_session_snapshot_in_subprocess(- venv_python: str, payload: dict[str, Any]+ sandbox: SandboxTarget, payload: dict[str, Any]) -> tuple[NotebookSessionV1, bool]:script = r"""import asyncio@@ -155,7 +156,7 @@ sys.stdout.write("""output = run_python_subprocess(- venv_python=venv_python,+ sandbox=sandbox,script=script,payload=payload,action="export session",@@ -191,8 +192,8 @@ async def _export_session_for_notebook(returnecho(f"Running {notebook.short_name}...")- venv_python = (- sandbox_pool.get_python(str(notebook.path))+ sandbox = (+ sandbox_pool.get_target(str(notebook.path))if sandbox_pool is not Noneelse None)@@ -200,7 +201,7 @@ async def _export_session_for_notebook(session_snapshot, did_error = await _export_session_snapshot(notebook,notebook_args=notebook_args,- venv_python=venv_python,+ sandbox=sandbox,)output = write_session_snapshot(@@ -340,8 +341,7 @@ def session(notebook, force_overwrite=force_overwrite):return- run_in_sandbox(sys.argv[1:], name=str(name))- return+ sys.exit(run_in_sandbox(sys.argv[1:], name=str(name)))asyncio_run(_export_sessions(diff --git a/marimo/_cli/export/thumbnail.py b/marimo/_cli/export/thumbnail.pyindex c076554fc6..04dc3104fe 100644--- a/marimo/_cli/export/thumbnail.py+++ b/marimo/_cli/export/thumbnail.py@@ -11,6 +11,7 @@ import clickfrom marimo._cli.errors import MarimoCLIMissingDependencyErrorfrom marimo._cli.export._common import (+ SandboxTarget,SandboxVenvPool,collect_notebooks,is_multi_target,@@ -104,14 +105,16 @@ def _bootstrap_thumbnail_sandbox() -> None:from marimo._cli.sandbox import run_in_sandbox- run_in_sandbox(- args,- name=name,- additional_deps=_thumbnail_sandbox_deps,- extra_env={- _sandbox_bootstrapped_env: "1",- _sandbox_mode_env: sandbox_mode.value,- },+ sys.exit(+ run_in_sandbox(+ args,+ name=name,+ additional_deps=_thumbnail_sandbox_deps,+ extra_env={+ _sandbox_bootstrapped_env: "1",+ _sandbox_mode_env: sandbox_mode.value,+ },+ ))@@ -122,7 +125,7 @@ async def _render_html(include_code: bool,args: tuple[str, ...],asset_url: str | None = None,- venv_python: str | None = None,+ sandbox: SandboxTarget | None = None,) -> str:if not execute:result = await export_html(@@ -137,7 +140,7 @@ async def _render_html()return result.text- if venv_python is None:+ if sandbox is None:cli_args = parse_args(args) if args else {}result = await export_html(HTMLFileExportRequest(@@ -166,13 +169,13 @@ async def _render_html(# Render in a separate process so we can use a sandboxed venv without polluting the current environment.return await asyncio.to_thread(_render_html_in_subprocess,- venv_python,+ sandbox,payload,)def _render_html_in_subprocess(- venv_python: str, payload: dict[str, Any]+ sandbox: SandboxTarget, payload: dict[str, Any]) -> str:"""Render a notebook to HTML in a separate Python process."""script = r"""@@ -216,7 +219,7 @@ sys.stdout.write(result.text)"""return run_python_subprocess(- venv_python=venv_python,+ sandbox=sandbox,script=script,payload=payload,action="render notebook",@@ -303,8 +306,8 @@ async def _generate_thumbnails(maybe_make_dirs(out_path)echo(f"Rendering {notebook.short_name}...")- venv_python = (- sandbox_pool.get_python(str(notebook.path))+ sandbox = (+ sandbox_pool.get_target(str(notebook.path))if sandbox_pool is not Noneelse None)@@ -314,7 +317,7 @@ async def _generate_thumbnails(include_code=include_code,args=notebook_args,asset_url=server.base_url,- venv_python=venv_python,+ sandbox=sandbox,)server.set_html(html)diff --git a/marimo/_cli/sandbox.py b/marimo/_cli/sandbox.pyindex c0adb31829..7af52d34ed 100644--- a/marimo/_cli/sandbox.py+++ b/marimo/_cli/sandbox.py@@ -4,7 +4,6 @@ from __future__ import annotationsimport atexitimport osimport platform-import shutilimport signalimport subprocessimport sys@@ -19,9 +18,11 @@ from marimo import _loggersfrom marimo._cli.errors import MarimoCLIMissingDependencyErrorfrom marimo._cli.print import bold, echo, green, mutedfrom marimo._config.settings import GLOBAL_SETTINGS-from marimo._environments import script_metadata+from marimo._environments import environment, script_metadata+from marimo._environments.overlay import runtime_overlayfrom marimo._environments.uv import (UvCommandError,+ UvError,UvMissingScriptMetadataError,UvNotFoundError,find_uv_bin,@@ -40,7 +41,8 @@ from marimo._version import __version__class SandboxMode(Enum):"""Sandbox mode for marimo notebooks.- - SINGLE: Single-file sandbox (wraps entire process with uv run)+ - SINGLE: Single-file sandbox (the server runs from the notebook's+ script environment)- MULTI: Multi-file sandbox (IPC kernels with per-notebook venvs)"""@@ -107,7 +109,8 @@ def resolve_sandbox_mode(Returns:- None: No sandboxing- - SandboxMode.SINGLE: Single-file sandbox (wrap with uv run)+ - SandboxMode.SINGLE: Single-file sandbox (server in the script+ environment)- SandboxMode.MULTI: Multi-file sandbox (IPC kernels with per-notebook venvs)When sandbox is None, prompts the user if the notebook has sandbox metadata@@ -131,7 +134,7 @@ def resolve_sandbox_mode(# Sandbox enabled - determine mode based on target type# Directory or home page -> multi-file sandbox (IPC kernels)- # Single file -> single-file sandbox (uv run wrapper)+ # Single file -> single-file sandbox (server in the script environment)return SandboxMode.MULTI if is_directory else SandboxMode.SINGLE@@ -258,7 +261,9 @@ def _resolve_requirements_txt_lines(pyproject: PyProjectReader) -> list[str]:def get_marimo_dir() -> Path:- return Path(__file__).parent.parent.parent+ from marimo._environments.overlay import marimo_dir++ return marimo_dir()def construct_uv_flags(@@ -268,7 +273,9 @@ def construct_uv_flags(additional_deps: list[str],python_version_override: str | None = None,) -> list[str]:- # NB. Used in quarto plugin+ # Deprecated: retained for the quarto plugin. marimo launches+ # sandboxes from the script environment instead; the flags built here+ # flatten `[[tool.uv.index]]` semantics (#10547).# If name if a filepath, parse the dependencies from the filedependencies = _resolve_requirements_txt_lines(pyproject)@@ -342,6 +349,7 @@ def construct_uv_command(additional_deps: list[str],python_version_override: str | None = None,) -> list[str]:+ """Deprecated: retained for the quarto plugin."""cmd = ["marimo"] + argsif "--sandbox" in cmd:cmd.remove("--sandbox")@@ -384,14 +392,17 @@ def run_in_sandbox(python_version_override: str | None = None,pyodide_constraints: bool = False,) -> int:- """Run marimo in a sandboxed uv environment.+ """Runs marimo inside the notebook's script environment.- This wraps the marimo command with `uv run` to create an isolated- virtual environment with the notebook's dependencies.+ Synchronizes the environment from the notebook's metadata, then+ launches `python -m marimo <args...>` from it with marimo layered on+ top. uv resolves the metadata with its full semantics, so indexes,+ sources, and credentials behave as they do for `uv run notebook.py`,+ and the environment is shared with it. A target without a metadata+ block runs in an ephemeral environment instead.Used for "single" sandbox mode (marimo edit --sandbox notebook.py).- For "multi" sandbox mode (directory), see IPCKernelManagerImpl which- creates per-notebook sandboxed kernels.+ For "multi" sandbox mode (directory), see IPCKernelManagerImpl."""try:require_uv_bin()@@ -404,7 +415,7 @@ def run_in_sandbox(# Ensure marimo and the python version are in the script metadata before# running. Adding marimo is best-effort: the sandbox still runs without- # it, since the requirements normalization injects marimo.+ # it, since the runtime overlay carries marimo.if name is not None and name.endswith(".py"):try:script_metadata.ensure_marimo(name)@@ -417,15 +428,9 @@ def run_in_sandbox(LOGGER.warning(f"Failed to add marimo to script metadata: {e}")script_metadata.ensure_requires_python(name)- uv_cmd = construct_uv_command(- args,- name,- additional_features or [],- additional_deps or [],- python_version_override=python_version_override,- )-- echo(f"Running in a sandbox: {muted(' '.join(uv_cmd))}", err=True)+ cmd = ["-m", "marimo", *args]+ if "--sandbox" in cmd:+ cmd.remove("--sandbox")env = os.environ.copy()env["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"@@ -449,6 +454,7 @@ def run_in_sandbox(constraint_tmp.close()constraint_path = constraint_tmp.nameif write_constraint_file(constraint_path):+ # Resolution happens in the child uv process; see below.env["UV_CONSTRAINT"] = constraint_pathdef cleanup_constraint_file() -> None:@@ -459,20 +465,81 @@ def run_in_sandbox(atexit.register(cleanup_constraint_file)+ overlay = runtime_overlay(additional_features or [], additional_deps or [])++ # Explicit override > metadata requires-python (uv reads it) > host.+ pyproject = (+ PyProjectReader.from_filename(name)+ if name is not None+ else PyProjectReader({}, config_path=None)+ )+ python_request = python_version_override or (+ None if pyproject.python_version else platform.python_version()+ )++ # An interpreter override (html-wasm pins the Pyodide version) must+ # not replace the notebook's shared script environment; it resolves+ # ephemerally with the notebook's dependencies layered instead.+ overridden = python_version_override is not None or pyodide_constraints++ plan: environment.ProcessPlan | None = None+ if name is not None and not overridden and os.path.isfile(name):+ try:+ handle = environment.sync_notebook(+ name,+ python_override=python_request,+ # Stream uv's progress to the terminal; a first+ # synchronization can install for a while.+ on_output=lambda _line: None,+ )+ echo(+ f"Using script environment: {muted(handle.root)}",+ err=True,+ )+ # Only a server whose kernel runs in the script environment+ # may route package changes through it.+ env["MARIMO_SANDBOX_MODE"] = "single"+ plan = environment.launch(+ handle, cmd, overlay=overlay, base_env=env+ )+ except UvMissingScriptMetadataError:+ # No metadata block yet; run ephemerally below.+ pass+ except UvError as e:+ echo(str(e), err=True)+ return getattr(e, "returncode", None) or 1++ if plan is None:+ if overridden and name is not None and os.path.isfile(name):+ overlay = [+ line+ for line in _resolve_requirements_txt_lines(pyproject)+ if line.strip() and not is_marimo_dependency(line)+ ] + overlay+ plan = environment.launch_isolated(+ cmd,+ overlay=overlay,+ python=python_request or platform.python_version(),+ base_env=env,+ )++ echo(f"Running in a sandbox: {muted(' '.join(plan.argv))}", err=True)+if sys.platform == "win32":# The console already delivers Ctrl-C to uv and the inner server;# forwarding CTRL_C_EVENT would rebroadcast to the whole console,# including ourselves (#4842). Let the inner server drive shutdown.signal.signal(signal.SIGINT, signal.SIG_IGN)- process = subprocess.Popen(uv_cmd, env=env)+ process = subprocess.Popen(plan.argv, env=plan.env)else:- # On Unix, run `uv` in its own session so that (a) the tty no+ # On Unix, run the child in its own session so that (a) the tty no# longer delivers SIGINT/SIGTERM to it directly and (b) we can# signal the whole subtree with a single killpg. The signal# handlers below are then the sole path for forwarding signals- # from the CLI down to uv, the inner marimo server, and the- # kernel.- process = subprocess.Popen(uv_cmd, env=env, start_new_session=True)+ # from the CLI down to the inner marimo server and the kernel.+ process = subprocess.Popen(+ plan.argv, env=plan.env, start_new_session=True+ )def handler(sig: int, frame: object) -> None:del frame@@ -486,143 +553,5 @@ def run_in_sandbox(signal.signal(signal.SIGTERM, handler)signal.signal(signal.SIGHUP, handler)- return process.wait()---def get_sandbox_requirements(- filename: str | None,- additional_deps: list[str] | None = None,-) -> list[str]:- """Get normalized requirements for sandbox venv.-- Reads dependencies from the notebook's PEP 723 script metadata,- normalizes marimo dependency, and adds any additional deps- (e.g., get_ipc_kernel_deps() for kernel communication).-- Args:- filename: Path to notebook file, or None for empty deps.- additional_deps: Extra dependencies to add if not already present.-- Returns:- List of normalized requirement strings.- """- pyproject = (- PyProjectReader.from_filename(filename)- if filename is not None- else PyProjectReader({}, config_path=None)- )-- dependencies = _resolve_requirements_txt_lines(pyproject)- normalized = _normalize_sandbox_dependencies(- dependencies, __version__, additional_features=[]- )-- # Add additional deps if not already present- if additional_deps:- existing_lower = {- d.lower().split("[")[0].split(">=")[0].split("==")[0]- for d in normalized- }- for dep in additional_deps:- if dep.lower() not in existing_lower:- normalized.append(dep)-- return normalized---def build_sandbox_venv(- filename: str | None,- additional_deps: list[str] | None = None,-) -> tuple[str, str]:- """Build sandbox venv and install dependencies.-- Creates an ephemeral virtual environment using uv with the notebook's- dependencies installed. Used for "multi" sandbox mode where each notebook- gets its own sandboxed environment.-- Args:- filename: Path to notebook file for reading dependencies.- additional_deps: Extra dependencies to add (e.g., get_ipc_kernel_deps()).-- Returns:- Tuple of (sandbox_dir, venv_python_path).-- Raises:- RuntimeError: If dependency installation fails.- """- # Create temp directory for sandbox venv- sandbox_dir = tempfile.mkdtemp(prefix="marimo-sandbox-")- venv_path = os.path.join(sandbox_dir, "venv")-- # Phase 1: Create venv- echo(f"Creating sandbox environment: {muted(venv_path)}", err=True)- uv(["venv", "--seed", venv_path])-- # Get venv Python path- if sys.platform == "win32":- venv_python = os.path.join(venv_path, "Scripts", "python.exe")- else:- venv_python = os.path.join(venv_path, "bin", "python")-- # Phase 2: Install dependencies- requirements = get_sandbox_requirements(filename, additional_deps)- echo("Installing sandbox dependencies...", err=True)-- # Separate editable installs from regular requirements- # Editable installs look like "-e /path/to/package"- editable_reqs = [r for r in requirements if r.startswith("-e ")]- regular_reqs = [r for r in requirements if not r.startswith("-e ")]-- # Install editable packages directly (not via requirements file)- for editable in editable_reqs:- # Extract path from "-e /path/to/package"- editable_path = editable[3:].strip()- try:- uv(- [- "pip",- "install",- "--python",- venv_python,- "-e",- editable_path,- ]- )- except UvCommandError as e:- echo(- f"Warning: Editable install failed: {e.stderr}",- err=True,- )-- # Install regular packages via requirements file- if regular_reqs:- req_file = os.path.join(sandbox_dir, "requirements.txt")- with open(req_file, "w", encoding="utf-8") as f:- f.write("\n".join(regular_reqs))-- try:- uv(["pip", "install", "--python", venv_python, "-r", req_file])- except UvCommandError as e:- # Clean up on failure- cleanup_sandbox_dir(sandbox_dir)- raise RuntimeError(- f"Failed to install sandbox dependencies: {e.stderr}"- ) from e-- return sandbox_dir, venv_python---def cleanup_sandbox_dir(sandbox_dir: str | None) -> None:- """Clean up sandbox directory.-- Safely removes the sandbox directory and all its contents.- Silently ignores errors (e.g., if directory doesn't exist).-- Args:- sandbox_dir: Path to sandbox directory, or None (no-op).- """- if sandbox_dir:- try:- shutil.rmtree(sandbox_dir)- except OSError:- pass+ returncode = process.wait()+ return 128 - returncode if returncode < 0 else returncodediff --git a/marimo/_config/settings.py b/marimo/_config/settings.pyindex 49a6c8b30f..bcc61a7ed3 100644--- a/marimo/_config/settings.py+++ b/marimo/_config/settings.py@@ -18,6 +18,9 @@ class GlobalSettings:PROFILE_DIR: str | None = NoneLOG_LEVEL: int = logging.WARNINGMANAGE_SCRIPT_METADATA: bool = is_env_true("MARIMO_MANAGE_SCRIPT_METADATA")+ # "single" or "multi" when this process belongs to a sandbox whose+ # dependencies live in script environments; None otherwise.+ SANDBOX_MODE: str | None = os.environ.get("MARIMO_SANDBOX_MODE") or NoneIN_SECURE_ENVIRONMENT: bool = is_env_true("MARIMO_IN_SECURE_ENVIRONMENT")# Mark the session cookie as `Secure` so browsers only send it over HTTPS.# Enable when serving marimo behind TLS / a TLS-terminating proxy. Defaultdiff --git a/marimo/_environments/environment.py b/marimo/_environments/environment.pynew file mode 100644index 0000000000..7d6ed52d16--- /dev/null+++ b/marimo/_environments/environment.py@@ -0,0 +1,360 @@+# Copyright 2026 Marimo. All rights reserved.+"""Provision script environments with uv.++`sync()` makes a script's environment match its PEP 723 metadata and+returns a frozen `Environment`. Synchronizing is idempotent and cheap+when nothing changed; callers synchronize before every launch. uv owns+resolution, so the metadata's indexes, sources, and credentials apply+exactly as they do for `uv run script.py`, and the environment is the+same one `uv run` uses.+"""++from __future__ import annotations++import os+import re+from dataclasses import dataclass+from typing import TYPE_CHECKING, Literal++import msgspec++from marimo import _loggers+from marimo._environments.uv import (+ UvError,+ require_uv_bin,+ uv,+ uv_stream,+)++if TYPE_CHECKING:+ from collections.abc import Callable, Mapping, Sequence++LOGGER = _loggers.marimo_logger()++Action = Literal["created", "updated", "replaced", "unchanged"]++# `uv sync --script --output-format json` reports the environment path and+# interpreter on stdout. The flag landed in uv 0.7.21.+MINIMUM_UV_VERSION = (0, 7, 21)+++class UvUnsupportedVersionError(UvError):+ """The installed uv predates the script-environment interface."""++ def __init__(self, found: str) -> None:+ minimum = ".".join(str(part) for part in MINIMUM_UV_VERSION)+ super().__init__(+ f"uv {minimum} or newer is required to manage sandbox "+ f"environments; found uv {found}. "+ "Upgrade with `uv self update`."+ )+++class UvSyncReportError(UvError):+ """uv synchronized the script but its report was unreadable."""+++@dataclass(frozen=True)+class Environment:+ """A synchronized script environment.++ An `updated` environment keeps its interpreter; newly installed+ packages are importable without a relaunch.+ """++ python: str+ root: str+ action: Action++ def requires_restart(self, previous: Environment | None) -> bool:+ """Whether a process launched from `previous` must be relaunched."""+ if previous is None:+ return False+ return self.action == "replaced" or self.python != previous.python++ def process_env(+ self, base: Mapping[str, str] | None = None+ ) -> dict[str, str]:+ """Environment variables for a process in this environment.++ Sets `VIRTUAL_ENV`, drops `UV_PROJECT_ENVIRONMENT`, and puts the+ environment's bin directory first on `PATH`, as `uv run` would.+ """+ env = dict(os.environ if base is None else base)+ env["VIRTUAL_ENV"] = self.root+ env.pop("UV_PROJECT_ENVIRONMENT", None)+ bin_dir = _venv_bin_dir(self.root)+ path = env.get("PATH")+ env["PATH"] = bin_dir if not path else bin_dir + os.pathsep + path+ return env+++@dataclass(frozen=True)+class ProcessPlan:+ """A command ready to run inside a script environment."""++ argv: tuple[str, ...]+ env: dict[str, str]+ # A launcher such as uv sits between marimo and the process it starts.+ # Put that launcher in its own session so startup failure can terminate+ # the whole pre-handshake process tree without signaling the server.+ start_new_session: bool = False+++def launch(+ environment: Environment,+ args: Sequence[str],+ *,+ overlay: Sequence[str] = (),+ base_env: Mapping[str, str] | None = None,+) -> ProcessPlan:+ """Plans running `python <args...>` inside the environment.++ With no overlay, the plan invokes the environment's interpreter+ directly. Overlay requirements (PEP 508, or `-e <path>` for an+ editable install) are layered via `uv run --with` into a cached side+ environment for this process only; the script environment and the+ manifest are never modified.+ """+ env = environment.process_env(base_env)+ if not overlay:+ return ProcessPlan(argv=(environment.python, *args), env=env)++ return ProcessPlan(+ argv=(+ require_uv_bin(),+ "run",+ # The script environment is VIRTUAL_ENV in `env`; --active+ # makes uv layer on top of it instead of ignoring it.+ "--active",+ "--no-project",+ "--python",+ environment.python,+ *_with_args(overlay),+ "--",+ "python",+ *args,+ ),+ env=env,+ start_new_session=True,+ )+++def launch_isolated(+ args: Sequence[str],+ *,+ overlay: Sequence[str],+ python: str,+ base_env: Mapping[str, str] | None = None,+) -> ProcessPlan:+ """Plans `python <args...>` in an ephemeral environment.++ For targets without a manifest, such as a new notebook. uv resolves+ the overlay into a cached environment and runs the process in an+ ephemeral copy, so packages installed during the session die with+ it and nothing persists per invocation.+ """+ env = dict(os.environ if base_env is None else base_env)+ env.pop("VIRTUAL_ENV", None)+ env.pop("UV_PROJECT_ENVIRONMENT", None)+ return ProcessPlan(+ argv=(+ require_uv_bin(),+ "run",+ "--isolated",+ "--no-project",+ "--compile-bytecode",+ "--python",+ python,+ *_with_args(overlay),+ "--",+ "python",+ *args,+ ),+ env=env,+ start_new_session=True,+ )+++def _with_args(overlay: Sequence[str]) -> list[str]:+ """`uv run` flags for overlay requirements; `-e <path>` is editable."""+ with_args: list[str] = []+ for requirement in overlay:+ if requirement.startswith("-e "):+ with_args.extend(["--with-editable", requirement[3:].strip()])+ else:+ with_args.extend(["--with", requirement])+ return with_args+++def sync(+ script: str,+ *,+ cwd: str | None = None,+ python_override: str | None = None,+ on_output: Callable[[str], None] | None = None,+) -> Environment:+ """Makes the script's environment match its metadata.++ Runs uv from `cwd`, normally the notebook's directory, so+ directory-scoped uv configuration applies. `python_override` wins+ over the script's `requires-python` (html-wasm export pins the+ Pyodide interpreter). With `on_output`, uv's progress streams to the+ callback line by line. Raises `UvCommandError` on failure and never+ mutates `script`.+ """+ ensure_supported_uv()+ args = [+ "sync",+ "--script",+ script,+ "--compile-bytecode",+ "--output-format",+ "json",+ ]+ if python_override is not None:+ args.extend(["--python", python_override])+ if on_output is not None:+ completed = uv_stream(args, on_output, env=_sync_env(), cwd=cwd)+ else:+ completed = uv(args, env=_sync_env(), cwd=cwd)+ return _parse_report(completed.stdout)+++def sync_notebook(+ path: str,+ *,+ python_override: str | None = None,+ on_output: Callable[[str], None] | None = None,+) -> Environment:+ """Synchronizes a notebook's script environment.++ Materializes the manifest when it lives in frontmatter. Raises+ `UvMissingScriptMetadataError` when the notebook has no metadata+ block.+ """+ from marimo._environments.script_metadata import (+ materialized_for_environment,+ )++ with materialized_for_environment(path) as target:+ return sync(+ target.path,+ cwd=target.directory,+ python_override=python_override,+ on_output=on_output,+ )+++def ensure_supported_uv() -> None:+ """Raise `UvUnsupportedVersionError` for a uv below the minimum."""+ version = _uv_version()+ parsed = _parse_version(version)+ if parsed is None:+ # An unparsable version is likely newer than anything we know;+ # let the actual command fail if the interface is missing.+ LOGGER.debug("Could not parse uv version: %s", version)+ return+ if parsed < MINIMUM_UV_VERSION:+ raise UvUnsupportedVersionError(version)+++def _uv_version() -> str:+ """The invoked uv's version string.++ Probed per call; caching would pin a stale answer across+ `uv self update` or a changed `UV` environment variable.+ """+ # "uv 0.7.21 (a1b2c3d4 2025-01-01)"+ stdout = uv(["--version"]).stdout.strip()+ return stdout.removeprefix("uv ").split(" ")[0]+++def _parse_version(version: str) -> tuple[int, ...] | None:+ match = re.match(r"(\d+)\.(\d+)\.(\d+)", version)+ if match is None:+ return None+ return tuple(int(part) for part in match.groups())+++# The report schema is labeled preview upstream; only the fields consumed+# here are declared, and drift raises `UvSyncReportError` rather than+# guessing.+_ACTIONS: dict[str, Action] = {+ "create": "created",+ "update": "updated",+ "replace": "replaced",+ "check": "unchanged",+}+++class _ReportPython(msgspec.Struct):+ path: str+++class _ReportEnvironment(msgspec.Struct):+ path: str+ python: _ReportPython+++class _ReportSync(msgspec.Struct):+ environment: _ReportEnvironment+ action: str+++class _Report(msgspec.Struct):+ sync: _ReportSync+++def _parse_report(stdout: str) -> Environment:+ try:+ report = msgspec.json.decode(stdout, type=_Report)+ except msgspec.DecodeError as error:+ raise UvSyncReportError(+ "uv synchronized the script but did not report its environment"+ ) from error+ reported_python = report.sync.environment.python.path+ root = report.sync.environment.path+ raw_action = report.sync.action+ action = _ACTIONS.get(raw_action)+ if action is None:+ # An unknown action still names a usable environment; interpreter+ # identity drives restarts, so treat it as an in-place update.+ LOGGER.debug("Unknown uv sync action: %s", raw_action)+ action = "updated"+ # The report spells the interpreter differently across actions (e.g.+ # bin/python on create, bin/python3 on check). Pick a stable name from+ # the root so interpreter identity is comparable across syncs.+ python = _venv_python(root) or reported_python+ return Environment(python=python, root=root, action=action)+++def _venv_python(root: str) -> str | None:+ """The environment's interpreter, preferring the unversioned name.++ Symlinks are not resolved: bin/python commonly links to the base+ interpreter, and resolving it would launch outside the environment.+ """+ bin_dir = _venv_bin_dir(root)+ candidates: tuple[str, ...]+ if os.name == "nt":+ candidates = (os.path.join(bin_dir, "python.exe"),)+ else:+ candidates = (+ os.path.join(bin_dir, "python"),+ os.path.join(bin_dir, "python3"),+ )+ for candidate in candidates:+ if os.path.exists(candidate):+ return candidate+ return None+++def _venv_bin_dir(root: str) -> str:+ return os.path.join(root, "Scripts" if os.name == "nt" else "bin")+++def _sync_env() -> dict[str, str]:+ from marimo._environments.uv import script_command_env++ return script_command_env()diff --git a/marimo/_environments/overlay.py b/marimo/_environments/overlay.pynew file mode 100644index 0000000000..6aa6159c0c--- /dev/null+++ b/marimo/_environments/overlay.py@@ -0,0 +1,41 @@+# Copyright 2026 Marimo. All rights reserved.+"""What marimo layers into sandbox launches."""++from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING++from marimo import _loggers+from marimo._utils.versions import is_editable+from marimo._version import __version__++if TYPE_CHECKING:+ from collections.abc import Sequence++LOGGER = _loggers.marimo_logger()+++def marimo_dir() -> Path:+ """The repository root when marimo runs from a checkout."""+ return Path(__file__).parent.parent.parent+++def runtime_overlay(+ features: Sequence[str] = (),+ additional_deps: Sequence[str] = (),+) -> list[str]:+ """The requirements marimo layers into a sandbox launch.++ marimo itself rides the overlay, pinned to the running version or as+ an editable install from a development checkout, so the launched+ process matches the CLI regardless of what a manifest's `marimo`+ resolves to. Overlay entries never enter the manifest.+ """+ extras = f"[{','.join(features)}]" if features else ""+ if is_editable("marimo"):+ LOGGER.info("Using editable of marimo for sandbox")+ marimo_dep = f"-e {marimo_dir()}{extras}"+ else:+ marimo_dep = f"marimo{extras}=={__version__}"+ return [marimo_dep, *additional_deps]diff --git a/marimo/_environments/script_metadata.py b/marimo/_environments/script_metadata.pyindex 4e99d61ebe..d5527e7766 100644--- a/marimo/_environments/script_metadata.py+++ b/marimo/_environments/script_metadata.py@@ -17,18 +17,27 @@ directory-scoped uv configuration applies.from __future__ import annotationsimport contextlib+import errnoimport osimport platformimport re+import statimport subprocess+import sysimport tempfile+import timefrom dataclasses import dataclassfrom pathlib import Pathfrom typing import TYPE_CHECKING, Anyfrom marimo import _loggersfrom marimo._environments.errors import EnvironmentManagerError-from marimo._environments.uv import UvError, uv+from marimo._environments.uv import (+ UvError,+ script_command_env,+ uv,+ uv_stream,+)from marimo._utils.toml import toml_readerif TYPE_CHECKING:@@ -99,32 +108,48 @@ def with_python_version_requirement(project: dict[str, Any]) -> dict[str, Any]:def add_dependencies(- path: str, packages: Sequence[str], *, upgrade: bool = False+ path: str,+ packages: Sequence[str],+ *,+ upgrade: bool = False,+ on_output: Callable[[str], None] | None = None,) -> None:"""Add packages to the script's metadata via `uv add --script`."""if not packages:return- args = ["--quiet", "add", "--script"]+ args = ["add", "--script"]def edit(target: str, cwd: str) -> None:- uv(- [*args, target, *(["--upgrade"] if upgrade else []), *packages],- cwd=cwd,- )+ command = [+ *args,+ target,+ *(["--upgrade"] if upgrade else []),+ *packages,+ ]+ if on_output is not None:+ uv_stream(command, on_output, env=script_command_env(), cwd=cwd)+ else:+ uv(["--quiet", *command], env=script_command_env(), cwd=cwd)_edit(path, edit)-def remove_dependencies(path: str, packages: Sequence[str]) -> None:+def remove_dependencies(+ path: str,+ packages: Sequence[str],+ *,+ on_output: Callable[[str], None] | None = None,+) -> None:"""Remove packages from the script's metadata via `uv remove --script`."""if not packages:returndef edit(target: str, cwd: str) -> None:- uv(- ["--quiet", "remove", "--script", target, *packages],- cwd=cwd,- )+ command = ["remove", "--script", target, *packages]+ if on_output is not None:+ uv_stream(command, on_output, env=script_command_env(), cwd=cwd)+ else:+ uv(["--quiet", *command], env=script_command_env(), cwd=cwd)_edit(path, edit)@@ -149,7 +174,12 @@ def ensure_marimo(path: str) -> None:returndef edit(target: str, cwd: str) -> None:- uv(["add", "--script", target, "marimo"], timeout=30, cwd=cwd)+ uv(+ ["add", "--script", target, "marimo"],+ env=script_command_env(),+ timeout=30,+ cwd=cwd,+ )_edit(path, edit)@@ -245,61 +275,91 @@ def _read_frontmatter(path: str) -> _Frontmatter:)-# Bumping the version orphans every older carrier; `_sweep_carriers`-# recognizes and removes all versions._CARRIER_VERSION = 1def _carrier_prefix(path: str) -> str:- """The ownership-signed carrier prefix for a notebook.-- Deterministic per notebook filename, so a carrier is recognizably- marimo's: safe to overwrite, sweep, and ignore.- """return f".marimo-v{_CARRIER_VERSION}-{os.path.basename(path)}"-# A carrier lives for one uv command; a stray this old is stranded.-_SWEEP_AGE_SECONDS = 15 * 60---def _sweep_carriers(directory: str, path: str) -> None:- """Removes stranded carriers for the notebook, best effort.+def _stable_carrier_lock(path: str) -> Iterator[None]:+ """Hold an OS lock through creation, use, and removal of the carrier.- Carriers are deleted after use; a killed process can strand one.- Only strays older than `_SWEEP_AGE_SECONDS` are removed, sparing a- concurrent process's in-flight carrier.+ The lock file stays in place: unlinking it would let a new caller lock+ a different inode while existing callers still wait on the old one.+ Process exit releases the lock, including after a crash."""- import time+ target = Path(path).with_name(f"{_carrier_prefix(path)}.lock")+ # Never truncate or follow a pre-existing link, even for the lock file.+ if target.is_symlink():+ raise OSError(f"Refusing to use symlink as carrier lock: {target}")+ descriptor = os.open(+ target, os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0), 0o600+ )+ with os.fdopen(descriptor, "r+b", buffering=0) as lock:+ if not stat.S_ISREG(os.fstat(lock.fileno()).st_mode):+ raise OSError(f"Carrier lock is not a regular file: {target}")+ if sys.platform == "win32":+ import msvcrt++ while True:+ try:+ msvcrt.locking(lock.fileno(), msvcrt.LK_NBLCK, 1)+ break+ except OSError as error:+ if error.errno not in (errno.EACCES, errno.EDEADLK):+ raise+ time.sleep(0.05)+ try:+ yield+ finally:+ msvcrt.locking(lock.fileno(), msvcrt.LK_UNLCK, 1)+ else:+ import fcntl- pattern = f".marimo-v*-{os.path.basename(path)}*.py"- cutoff = time.time() - _SWEEP_AGE_SECONDS- for stray in Path(directory).glob(pattern):- try:- if stray.stat().st_mtime < cutoff:- stray.unlink()- except OSError:- LOGGER.debug("Could not remove carrier %s", stray)+ fcntl.flock(lock.fileno(), fcntl.LOCK_EX)+ try:+ yield+ finally:+ fcntl.flock(lock.fileno(), fcntl.LOCK_UN)@contextlib.contextmanager-def _carrier(notebook: str, content: str) -> Iterator[str]:- """A sidecar script uv can operate on, next to the notebook.-- uv anchors relative paths in script metadata to the script's own- directory, so a manifest that lives in frontmatter must be- materialized beside its notebook before uv can act on it. The- versioned, deterministic name (`.marimo-v<N>-<name>.<rand>.py`)- marks the file as marimo's: safe to overwrite, sweep, and ignore.- Entry sweeps carriers stranded by killed processes; exit always- removes the carrier, best effort.+def _carrier(+ notebook: str, content: str, *, stable: bool = False+) -> Iterator[str]:+ """Materialize beside the notebook so uv preserves path semantics.++ Stable callers must hold `_stable_carrier_lock` for the full lifetime.+ Only that carrier can be reclaimed after a crash; age alone cannot+ distinguish another operation's active carrier from an abandoned one."""absolute = os.path.abspath(notebook)directory = os.path.dirname(absolute)- _sweep_carriers(directory, absolute)- descriptor, target = tempfile.mkstemp(- dir=directory, prefix=f"{_carrier_prefix(absolute)}.", suffix=".py"- )+ try:+ if stable:+ target = os.path.join(directory, f"{_carrier_prefix(absolute)}.py")+ if os.path.islink(target):+ raise OSError(f"Refusing to replace carrier symlink: {target}")+ # The lock proves no cooperating process is still using it.+ with contextlib.suppress(FileNotFoundError):+ os.unlink(target)+ descriptor = os.open(+ target, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600+ )+ else:+ descriptor, target = tempfile.mkstemp(+ dir=directory,+ prefix=f"{_carrier_prefix(absolute)}.",+ suffix=".py",+ )+ except OSError as error:+ raise ScriptMetadataError(+ f"Cannot create a metadata carrier beside {notebook}. "+ "Make the notebook directory writable and remove any "+ "conflicting carrier symlinks."+ ) from errortry:with os.fdopen(descriptor, "w", encoding="utf-8") as f:f.write(content)@@ -344,3 +404,47 @@ def _edit_frontmatter(path: str, edit: Callable[[str, str], None]) -> None:document = f"---\n{header.strip()}\n---{front.body}"with open(path, "w", encoding="utf-8", newline="") as f:f.write(document)+++@dataclass(frozen=True)+class MaterializedScript:+ """A script uv can operate on and the directory to run uv from."""++ path: str+ directory: str+++def materialized_for_environment(path: str) -> Iterator[MaterializedScript]:+ """Materializes a notebook's manifest for environment operations.++ A Python notebook is its own script, so its environment is the one+ `uv run notebook.py` uses and nothing is created. A markdown or+ Quarto notebook writes its header verbatim to the stable carrier+ `.marimo-v<N>-<name>.py` next to the notebook, deleted on exit. uv+ keys a script environment on the script's absolute path, so the+ stable name maps one notebook to one environment, reconciled in+ place across sessions. An OS lock serializes carrier lifetimes across+ threads and processes.+ """+ absolute = os.path.abspath(path)+ directory = os.path.dirname(absolute)+ if not path.endswith((".md", ".qmd")):+ yield MaterializedScript(path=absolute, directory=directory)+ return++ with contextlib.ExitStack() as stack:+ try:+ stack.enter_context(_stable_carrier_lock(absolute))+ except OSError as error:+ raise ScriptMetadataError(+ f"Cannot lock a metadata carrier beside {path}. "+ "Make the notebook directory writable and remove any "+ "conflicting carrier lock symlinks."+ ) from error+ content = (+ "# Generated by marimo; safe to delete.\n"+ + _read_frontmatter(absolute).header+ )+ with _carrier(absolute, content, stable=True) as target:+ yield MaterializedScript(path=target, directory=directory)diff --git a/marimo/_environments/uv.py b/marimo/_environments/uv.pyindex e1a92118d2..91d0ded007 100644--- a/marimo/_environments/uv.py+++ b/marimo/_environments/uv.py@@ -12,12 +12,17 @@ from __future__ import annotationsimport osimport shutilimport subprocess+import sys+import threadingfrom typing import TYPE_CHECKING+from marimo import _loggersfrom marimo._environments.errors import EnvironmentManagerErrorif TYPE_CHECKING:- from collections.abc import Mapping, Sequence+ from collections.abc import Callable, Mapping, Sequence++LOGGER = _loggers.marimo_logger()UV_INSTALL_HINT = ("Install uv from https://docs.astral.sh/uv/getting-started/installation/"@@ -173,3 +178,107 @@ def uv(if completed.returncode != 0:raise _refine(completed)return completed+++def uv_stream(+ args: Sequence[str],+ on_output: Callable[[str], None],+ *,+ env: Mapping[str, str] | None = None,+ cwd: str | None = None,+) -> subprocess.CompletedProcess[str]:+ """Runs a uv command, streaming its diagnostics to a callback.++ uv writes progress to stderr and machine-readable output to stdout:+ stderr lines stream to `on_output` (and this process's stderr) while+ stdout is captured for the caller. `on_output` runs in the calling+ thread, so callbacks that rely on thread-local state, such as a+ kernel's notification context, keep working. Failures raise the same+ refined errors as `uv()`.+ """+ from marimo._utils.subprocess import kill_subprocess++ command = [find_uv_bin(), *args]+ try:+ process = subprocess.Popen(+ command,+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ stdin=subprocess.DEVNULL,+ env=dict(env) if env is not None else None,+ cwd=cwd,+ bufsize=0,+ # A kernel interrupt must not propagate to uv; run it in its+ # own session (ignored on Windows).+ start_new_session=True,+ )+ except OSError as e:+ if cwd is not None:+ os.stat(cwd)+ if isinstance(e, FileNotFoundError):+ raise UvNotFoundError() from e+ raise++ assert process.stdout is not None+ assert process.stderr is not None+ stdout_pipe = process.stdout+ stdout_chunks: list[bytes] = []++ def drain_stdout() -> None:+ stdout_chunks.append(stdout_pipe.read())+ stdout_pipe.close()++ reader = threading.Thread(target=drain_stdout, daemon=True)+ reader.start()++ stderr_lines: list[bytes] = []+ try:+ for line in iter(process.stderr.readline, b""):+ stderr_lines.append(line)+ decoded = line.decode("utf-8", errors="replace")+ # The terminal tee is best effort: a kernel replaces sys.stderr+ # with a redirect whose `buffer` may be None, and nothing here+ # may stop the stream or deadlock uv.+ try:+ buffer = getattr(sys.stderr, "buffer", None)+ if buffer is not None:+ buffer.write(line)+ buffer.flush()+ else:+ sys.stderr.write(decoded)+ except Exception:+ pass+ try:+ on_output(decoded)+ except Exception:+ LOGGER.exception("Failed to stream uv output")+ returncode = process.wait()+ except BaseException:+ kill_subprocess(process, start_new_session=True)+ raise+ finally:+ process.stderr.close()+ reader.join()++ completed = subprocess.CompletedProcess(+ command,+ returncode,+ stdout=b"".join(stdout_chunks).decode("utf-8", errors="replace"),+ stderr=b"".join(stderr_lines).decode("utf-8", errors="replace"),+ )+ if completed.returncode != 0:+ raise _refine(completed)+ return completed+++def script_command_env() -> dict[str, str]:+ """Environment for uv script commands.++ A script's environment is selected by the script and its metadata; an+ enclosing project or virtualenv must not redirect it or warn about+ the mismatch.+ """+ env = dict(os.environ)+ env.pop("VIRTUAL_ENV", None)+ env.pop("UV_PROJECT_ENVIRONMENT", None)+ return envdiff --git a/marimo/_ipc/launch_kernel.py b/marimo/_ipc/launch_kernel.pyindex 67bac4aaac..28e636e631 100644--- a/marimo/_ipc/launch_kernel.py+++ b/marimo/_ipc/launch_kernel.py@@ -3,6 +3,7 @@from __future__ import annotations+import osimport sysfrom marimo._ipc.queue_manager import QueueManager@@ -29,6 +30,11 @@ def main() -> None:queue_manager = QueueManager.connect(args.connection_info)sys.stdout.write("KERNEL_READY\n")+ # A second line reports the kernel's identity: a launcher such as uv+ # may sit between the manager and this process, so the manager cannot+ # rely on its direct child's pid. Emitted after KERNEL_READY so+ # managers that only read the ready line keep working.+ sys.stdout.write(f"KERNEL_INFO {os.getpid()} {sys.executable}\n")sys.stdout.flush()runtime.launch_kernel(@@ -42,9 +48,11 @@ def main() -> None:user_config=args.user_config,configs=args.configs,profile_path=args.profile_path,- # Virtual files require a web server to serve file URLs. Since we're- # not running one, content must be embedded as data URLs instead.- virtual_file_storage=None,+ # None (the default) means no web server serves /@file/ URLs, so+ # content is embedded as data URLs -- correct for standalone+ # consumers like marimo-lsp. A marimo server passes+ # "shared_memory" so its /@file endpoint can read the buffers.+ virtual_file_storage=args.virtual_file_storage,# NB: IPC kernels are always subprocesses (is_ipc=True) but may be# edit or run mode based on is_edit_mode.stream_queue=queue_manager.stream_queue,diff --git a/marimo/_ipc/types.py b/marimo/_ipc/types.pyindex cfb5b609ce..79e69dfc49 100644--- a/marimo/_ipc/types.py+++ b/marimo/_ipc/types.py@@ -8,6 +8,7 @@ from marimo._ast.cell import CellConfigfrom marimo._config.config import MarimoConfigfrom marimo._messaging.msgspec_encoder import encode_json_bytesfrom marimo._runtime.commands import AppMetadata+from marimo._runtime.virtual_file.storage import VirtualFileStorageTypefrom marimo._types.ids import CellId_t@@ -39,6 +40,11 @@ class KernelArgs(msgspec.Struct):virtual_files_supported: bool = Trueredirect_console_to_browser: bool = Trueparent_pid: int | None = None+ # None means virtual files are unsupported and content is inlined as+ # data URLs -- required when no server is mounted to serve /@file/+ # (e.g. marimo-lsp). A server-managed kernel passes "shared_memory".+ # Unknown to older kernels, which ignore it and behave as None.+ virtual_file_storage: VirtualFileStorageType | None = Nonedef encode_json(self) -> bytes:return encode_json_bytes(self)diff --git a/marimo/_runtime/callbacks/packages.py b/marimo/_runtime/callbacks/packages.pyindex 622182785e..76242520d2 100644--- a/marimo/_runtime/callbacks/packages.py+++ b/marimo/_runtime/callbacks/packages.py@@ -15,6 +15,10 @@ from marimo._messaging.notification import ()from marimo._messaging.notification_utils import broadcast_notificationfrom marimo._runtime.commands import InstallPackagesCommand+from marimo._runtime.context.types import (+ ContextNotInitializedError,+ get_context,+)from marimo._runtime.packages.import_error_extractors import (extract_missing_module_from_cause_chain,try_extract_packages_from_import_error_message,@@ -96,7 +100,9 @@ class PackagesCallbacks:self.package_manager is Noneor package_manager != self.package_manager.name):- self.package_manager = create_package_manager(package_manager)+ self.package_manager = create_package_manager(+ package_manager, script_path=self._sandbox_script_path()+ )# All marimo notebooks depend on the marimo package; if the# notebook already has marimo as a dependency, or an optional@@ -232,7 +238,9 @@ class PackagesCallbacks:)if request.manager != self.package_manager.name:# Swap out the package manager- self.package_manager = create_package_manager(request.manager)+ self.package_manager = create_package_manager(+ request.manager, script_path=self._sandbox_script_path()+ )if not self.package_manager.is_manager_installed():self.package_manager.alert_not_installed()@@ -270,6 +278,14 @@ class PackagesCallbacks:)def create_log_callback(pkg: str) -> LogCallback:+ # Bind the stream now, on the kernel thread: the callback+ # fires from worker threads, which do not carry the kernel's+ # thread-local context, so a bare broadcast would be dropped.+ try:+ stream = get_context().stream+ except ContextNotInitializedError:+ stream = None+def log_callback(log_line: str) -> None:broadcast_notification(InstallingPackageAlertNotification(@@ -278,6 +294,7 @@ class PackagesCallbacks:log_status="append",source=request.source,),+ stream=stream,)return log_callback@@ -373,6 +390,13 @@ class PackagesCallbacks:if cells_to_run:await self._kernel.maybe_autorun_cells(cells_to_run)+ def _sandbox_script_path(self) -> str | None:+ """The notebook path when its dependencies live in a script+ environment; None otherwise."""+ if GLOBAL_SETTINGS.SANDBOX_MODE is None:+ return None+ return self._kernel.app_metadata.filename+def _maybe_add_marimo_to_script_metadata(self) -> None:if self.should_update_script_metadata():self.update_script_metadata(["marimo"])diff --git a/marimo/_runtime/packages/package_manager.py b/marimo/_runtime/packages/package_manager.pyindex 26e537c92f..d631d666be 100644--- a/marimo/_runtime/packages/package_manager.py+++ b/marimo/_runtime/packages/package_manager.py@@ -200,9 +200,15 @@ class PackageManager(abc.ABC):if proc.stdout:for line in iter(proc.stdout.readline, b""):- # Send to terminal (original behavior)- sys.stdout.buffer.write(line)- sys.stdout.buffer.flush()+ # The terminal tee is best effort: a kernel replaces+ # sys.stdout with a redirect whose buffer may be None.+ try:+ buffer = getattr(sys.stdout, "buffer", None)+ if buffer is not None:+ buffer.write(line)+ buffer.flush()+ except Exception:+ pass# Send to callback for streaminglog_callback(line.decode("utf-8", errors="replace"))proc.stdout.close()diff --git a/marimo/_runtime/packages/package_managers.py b/marimo/_runtime/packages/package_managers.pyindex b71f7f9a10..bfa8751065 100644--- a/marimo/_runtime/packages/package_managers.py+++ b/marimo/_runtime/packages/package_managers.py@@ -23,14 +23,27 @@ PACKAGE_MANAGERS = {def create_package_manager(- name: str, python_exe: str | None = None+ name: str,+ python_exe: str | None = None,+ script_path: str | None = None,) -> PackageManager:+ """Creates the named package manager.++ `script_path` puts uv in script mode: package changes edit the+ notebook's metadata and synchronize its script environment instead of+ installing imperatively. Other managers ignore it.+ """if is_pyodide():# user config has name "pip", but micropip's name is "micropip" ...return MicropipPackageManager()+ if name == UvPackageManager.name:+ return UvPackageManager(python_exe=python_exe, script_path=script_path)+if name in PACKAGE_MANAGERS:- return PACKAGE_MANAGERS[name](python_exe=python_exe) # type:ignore[abstract]+ return PACKAGE_MANAGERS[name]( # type:ignore[abstract,no-any-return]+ python_exe=python_exe+ )raise RuntimeError(f"Unknown package manager {name}. ""This is a bug in marimo."diff --git a/marimo/_runtime/packages/pypi_package_manager.py b/marimo/_runtime/packages/pypi_package_manager.pyindex 812bb26119..68ab54c1dc 100644--- a/marimo/_runtime/packages/pypi_package_manager.py+++ b/marimo/_runtime/packages/pypi_package_manager.py@@ -3,6 +3,7 @@ from __future__ import annotationsimport jsonimport os+import reimport subprocessimport sysfrom functools import cached_property@@ -15,7 +16,12 @@ if TYPE_CHECKING:from marimo import _loggersfrom marimo._dependencies.dependencies import DependencyManagerfrom marimo._environments import script_metadata-from marimo._environments.uv import UvCommandError, find_uv_bin, uv+from marimo._environments.uv import (+ UvCommandError,+ UvError,+ find_uv_bin,+ uv,+)from marimo._runtime.packages._micropip_streaming import (stream_transaction_install,)@@ -26,6 +32,7 @@ from marimo._runtime.packages.package_manager import (CanonicalizingPackageManager,LogCallback,PackageDescription,+ _normalize_package_name,)from marimo._runtime.packages.utils import (popen_package_command,@@ -46,6 +53,13 @@ PY_EXE = sys.executableLOGGER = _loggers.marimo_logger()+def _normalized_requirement_name(requirement: str) -> str | None:+ match = re.match(r"[A-Za-z0-9][A-Za-z0-9._-]*", requirement.strip())+ if match is None:+ return None+ return _normalize_package_name(match.group(0))++class VersionMap:"""A map of package names to versions, with some extra@@ -343,6 +357,16 @@ class UvPackageManager(PypiPackageManager):SCRIPT_METADATA_MARKER = "# /// script"_use_project = True+ def __init__(+ self,+ python_exe: str | None = None,+ script_path: str | None = None,+ ) -> None:+ # In script mode, package changes edit the notebook's metadata and+ # synchronize its script environment; nothing installs imperatively.+ self._script_path = script_path+ super().__init__(python_exe)+@classmethoddef for_pip_install(cls, python_exe: str) -> UvPackageManager:"""Target an interpreter without changing its uv project."""@@ -354,6 +378,65 @@ class UvPackageManager(PypiPackageManager):def _uv_bin(self) -> str:return find_uv_bin()+ def _declared_dependencies(self, script_path: str) -> set[str]:+ """Normalized names declared in the notebook's script metadata."""+ from marimo._utils.inline_script_metadata import PyProjectReader++ try:+ dependencies = PyProjectReader.from_filename(+ script_path+ ).dependencies+ except (OSError, ValueError):+ return set()+ return {+ name+ for dep in dependencies+ if (name := _normalized_requirement_name(str(dep))) is not None+ }++ def _change_script_environment(+ self,+ script_path: str,+ *,+ add: list[str] | None = None,+ remove: list[str] | None = None,+ upgrade: bool = False,+ log_callback: LogCallback | None = None,+ ) -> bool:+ """Edits the manifest and synchronizes its script environment.++ uv writes the constraint and resolves with the metadata's full+ semantics, streaming its output to `log_callback` line by line.+ Failures stream the solver's message rather than pointing at the+ terminal.+ """+ from marimo._environments import environment++ try:+ if add:+ script_metadata.add_dependencies(+ script_path,+ add,+ upgrade=upgrade,+ on_output=log_callback,+ )+ if remove:+ script_metadata.remove_dependencies(+ script_path, remove, on_output=log_callback+ )+ environment.sync_notebook(script_path, on_output=log_callback)+ return True+ except (script_metadata.ScriptMetadataError, UvError) as e:+ message = str(e.__cause__ or e)+ LOGGER.error(+ "Failed to update script environment for %s: %s",+ script_path,+ message,+ )+ if log_callback is not None:+ log_callback(message + "\n")+ return False+def _is_cache_write_error(self, output_text: str) -> bool:"""Check if the output text indicates a cache write error.@@ -405,6 +488,17 @@ class UvPackageManager(PypiPackageManager):log_callback: LogCallback | None = None,) -> bool:"""Installation logic with fallback to --no-cache on cache write errors."""+ import asyncio++ if self._script_path is not None:+ return await asyncio.to_thread(+ self._change_script_environment,+ self._script_path,+ add=split_packages(package),+ upgrade=upgrade,+ log_callback=log_callback,+ )+LOGGER.info(f"Installing in {package} with 'uv {'add' if self.is_in_uv_project else 'pip install'}'")@@ -504,6 +598,13 @@ class UvPackageManager(PypiPackageManager):import_namespaces_to_remove: List of import namespaces to removeupgrade: Whether to upgrade the packages"""+ if self._script_path is not None:+ # Script mode: install and uninstall already wrote these+ # packages through the script environment. Only namespace+ # changes from cell registration remain.+ packages_to_add = None+ packages_to_remove = None+packages_to_add = packages_to_add or []packages_to_remove = packages_to_remove or []import_namespaces_to_add = import_namespaces_to_add or []@@ -516,6 +617,14 @@ class UvPackageManager(PypiPackageManager):self.module_to_package(im) for im in import_namespaces_to_remove]+ if self._script_path is not None and packages_to_add:+ declared = self._declared_dependencies(filepath)+ packages_to_add = [+ package+ for package in packages_to_add+ if _normalized_requirement_name(package) not in declared+ ]+if not packages_to_add and not packages_to_remove:return True@@ -626,6 +735,39 @@ class UvPackageManager(PypiPackageManager):return uv_lock_path.exists() and pyproject_path.exists()async def uninstall(self, package: str, group: str | None = None) -> bool:+ if self._script_path is not None:+ import asyncio++ requested = split_packages(package)+ declared = await asyncio.to_thread(+ self._declared_dependencies, self._script_path+ )+ undeclared = [+ pkg+ for pkg in requested+ if _normalized_requirement_name(pkg) not in declared+ ]+ if undeclared:+ # A transitive dependency is not the notebook's to remove;+ # removing it from the environment alone would be undone+ # by the next synchronization.+ LOGGER.warning(+ "%s is not declared in the notebook's script metadata "+ "(likely a dependency of another package), so it "+ "cannot be removed.",+ ", ".join(undeclared),+ )+ return False+ return await asyncio.to_thread(+ self._change_script_environment,+ self._script_path,+ remove=[+ name+ for pkg in requested+ if (name := _normalized_requirement_name(pkg)) is not None+ ],+ )+uninstall_cmd: list[str]if self.is_in_uv_project:LOGGER.info(f"Uninstalling {package} with 'uv remove'")@@ -692,12 +834,22 @@ class UvPackageManager(PypiPackageManager):if filename is None and not self.is_in_uv_project:return None- tree_cmd = ["tree", "--no-dedupe"]- if filename:- tree_cmd += ["--script", filename]-try:- result = uv(tree_cmd)+ tree_cmd = ["tree", "--no-dedupe"]+ if filename is not None:+ from marimo._environments.script_metadata import (+ materialized_for_environment,+ )+ from marimo._environments.uv import script_command_env++ with materialized_for_environment(filename) as target:+ result = uv(+ [*tree_cmd, "--script", target.path],+ env=script_command_env(),+ cwd=target.directory,+ )+ else:+ result = uv(tree_cmd)tree = parse_uv_tree(result.stdout)# If in a uv project and the only top-level item is the project itself,diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.pyindex f745a64992..ea91a8f97d 100644--- a/marimo/_runtime/runtime.py+++ b/marimo/_runtime/runtime.py@@ -2505,7 +2505,9 @@ def _bootstrap_subprocess(# process (which assumes its child is in another process group).if sys.platform != "win32":os.setsid()- start_parent_poller(parent_pid)+ # The direct parent may be a launcher such as uv; also probe+ # the server pid so its ungraceful death is still detected.+ start_parent_poller(os.getppid(), ancestor_pid=parent_pid)else:ignore_console_ctrl_c()diff --git a/marimo/_server/api/endpoints/packages.py b/marimo/_server/api/endpoints/packages.pyindex b0caeac848..09379bac71 100644--- a/marimo/_server/api/endpoints/packages.py+++ b/marimo/_server/api/endpoints/packages.py@@ -173,10 +173,8 @@ async def dependency_tree(request: Request) -> DependencyTreeResponse:package_manager = _get_package_manager(request)filename = _get_filename(request)- # TODO(manzt): Same as check below when installing packages. If we are- # managing script metadata, we are in sandbox mode.is_sandbox = (- filename is not None and GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA+ filename is not None and GLOBAL_SETTINGS.SANDBOX_MODE is not None)if is_sandbox:tree = await asyncio.to_thread(@@ -198,6 +196,7 @@ def _get_package_manager(request: Request) -> PackageManager:# Check if IPC mode - use kernel's venv Pythonpython_exe: str | None = None+ script_path: str | None = Nonefrom marimo._session.managers.ipc import IPCKernelManagerImplfrom marimo._session.session import SessionImpl@@ -205,9 +204,17 @@ def _get_package_manager(request: Request) -> PackageManager:kernel_manager = session._kernel_managerif isinstance(kernel_manager, IPCKernelManagerImpl):python_exe = kernel_manager.venv_python+ if kernel_manager.script_environment is not None:+ # The kernel runs in the notebook's script environment;+ # package changes edit the manifest and synchronize it.+ script_path = session.app_file_manager.filename+ elif GLOBAL_SETTINGS.SANDBOX_MODE == "single":+ script_path = session.app_file_manager.filenamereturn create_package_manager(- config_manager.package_manager, python_exe=python_exe+ config_manager.package_manager,+ python_exe=python_exe,+ script_path=script_path,)diff --git a/marimo/_session/_venv.py b/marimo/_session/_venv.pyindex 2d3418dd20..01c8076490 100644--- a/marimo/_session/_venv.py+++ b/marimo/_session/_venv.py@@ -14,7 +14,6 @@ from __future__ import annotationsimport osimport subprocessimport sys-from importlib.metadata import versionfrom pathlib import Pathfrom typing import TYPE_CHECKING@@ -29,20 +28,6 @@ if TYPE_CHECKING:LOGGER = _loggers.marimo_logger()-def get_ipc_kernel_deps() -> list[str]:- """Get dependencies required for IPC kernel communication.-- Returns pyzmq pinned to the currently installed version to ensure- compatibility between host and sandbox environments.- """- try:- pyzmq_version = version("pyzmq")- return [f"pyzmq=={pyzmq_version}"]- except Exception:- # Fallback if pyzmq not installed- return ["pyzmq>=27.1.0"]--def _find_python_in_venv(venv_path: str) -> str | None:"""Find Python interpreter in a venv directory.@@ -200,14 +185,12 @@ def check_python_version_compatibility(venv_python: str) -> bool:def install_marimo_into_venv(venv_python: str) -> None:- """Install marimo and IPC dependencies into a venv.-- Installs marimo and IPC dependencies (pyzmq) into the specified venv.+ """Install marimo into a venv.Args:venv_python: Path to the venv's Python interpreter."""- packages = [f"marimo=={__version__}"] + get_ipc_kernel_deps()+ packages = [f"marimo=={__version__}"]echo("Installing marimo into configured venv...", err=True)diff --git a/marimo/_session/app_host/host.py b/marimo/_session/app_host/host.pyindex 6190a4031c..9f0f0755ab 100644--- a/marimo/_session/app_host/host.py+++ b/marimo/_session/app_host/host.py@@ -10,6 +10,7 @@ import threadingfrom typing import TYPE_CHECKING, castfrom marimo import _loggers+from marimo._environments.environment import ProcessPlanfrom marimo._messaging.types import KernelMessagefrom marimo._session.app_host.commands import (AppHostReadyResponse,@@ -48,21 +49,19 @@ class AppHost:Args:file_path: the notebook's absolute path, for debugging- python: absolute path to the Python executable- sandbox_dir: where to store the temporary venv if the notebook is sandboxed+ plan: how to launch the host process; defaults to the current+ interpreteron_empty: callable invoked when the AppHost spins down to zero sessions"""def __init__(self,file_path: str,- python: str | None = None,- sandbox_dir: str | None = None,+ plan: ProcessPlan | None = None,on_empty: Callable[[], None] | None = None,) -> None:self._file_path = file_path- self._python = python or sys.executable- self._sandbox_dir = sandbox_dir+ self._plan = planself._on_empty = on_empty# The process hosting client kernels.@@ -165,11 +164,12 @@ class AppHost:conn, args = AppHostConnection.create(self._file_path)self._conn = conn- cmd = [- self._python,- "-m",- "marimo._session.app_host.main",- ]+ if self._plan is not None:+ cmd = list(self._plan.argv)+ env = self._plan.env+ else:+ cmd = [sys.executable, "-m", "marimo._session.app_host.main"]+ env = NoneLOGGER.debug("Launching app host: %s", " ".join(cmd))# stdin is piped to send startup args; stdout/stderr inherit the@@ -178,6 +178,12 @@ class AppHost:self._process = subprocess.Popen(cmd,stdin=subprocess.PIPE,+ env=env,+ start_new_session=(+ self._plan.start_new_session+ if self._plan is not None+ else False+ ),)proc_stdin = self._process.stdin@@ -185,7 +191,9 @@ class AppHost:self.shutdown()raise RuntimeError("Failed to open stdin for app host")- ready_timeout_ms = 30_000+ # A launcher plan may resolve packages before the host starts;+ # a cold resolution can take minutes.+ ready_timeout_ms = 180_000 if self._plan is not None else 30_000try:proc_stdin.write(args.encode_json())proc_stdin.flush()@@ -373,10 +381,4 @@ class AppHost:if conn is not None:conn.close()- if self._sandbox_dir is not None:- from marimo._cli.sandbox import cleanup_sandbox_dir-- cleanup_sandbox_dir(self._sandbox_dir)- self._sandbox_dir = None-LOGGER.debug("App host shut down for %s", self._file_path)diff --git a/marimo/_session/app_host/main.py b/marimo/_session/app_host/main.pyindex 4a4a721da4..39dc129e4b 100644--- a/marimo/_session/app_host/main.py+++ b/marimo/_session/app_host/main.py@@ -250,7 +250,9 @@ def app_host_main(args: AppHostArgs) -> None:if sys.platform != "win32":os.setsid()- start_parent_poller(args.parent_pid)+ # The direct parent may be a launcher such as uv; also probe+ # the server pid so its ungraceful death is still detected.+ start_parent_poller(os.getppid(), ancestor_pid=args.parent_pid)_loggers.set_level(args.log_level)LOGGER.debug(diff --git a/marimo/_session/app_host/pool.py b/marimo/_session/app_host/pool.pyindex 2972b47205..087e859f30 100644--- a/marimo/_session/app_host/pool.py+++ b/marimo/_session/app_host/pool.py@@ -8,14 +8,20 @@ from __future__ import annotationsimport osimport threading+from concurrent.futures import Futurefrom dataclasses import dataclass-from marimo import _loggers-from marimo._cli.sandbox import build_sandbox_venv, cleanup_sandbox_dir-from marimo._session._venv import get_ipc_kernel_deps+from marimo._environments.environment import (+ ProcessPlan,+ launch,+ launch_isolated,+ sync_notebook,+)+from marimo._environments.errors import EnvironmentManagerError+from marimo._environments.overlay import runtime_overlay+from marimo._environments.uv import UvMissingScriptMetadataErrorfrom marimo._session.app_host.host import AppHost--LOGGER = _loggers.marimo_logger()+from marimo._session.managers.ipc import KernelStartupErrorclass AppHostPool:@@ -23,99 +29,91 @@ class AppHostPool:self._workers: dict[str, AppHost] = {}self._lock = threading.Lock()self._sandbox = sandbox+ self._pending: dict[str, Future[AppHost]] = {}+ self._closed = False- def _remove_and_shutdown(self, abs_path: str) -> None:- """Remove an app host from the pool and shut it down.-- Called when the host has zero active kernels.- """+ def _remove_and_shutdown(self, abs_path: str, worker: AppHost) -> None:+ # A delayed callback from a dead host must not remove its replacement.with self._lock:- worker = self._workers.pop(abs_path, None)-- if worker is not None:- LOGGER.debug(- "Shutting down app host for %s (no active kernels)",- abs_path,- )- worker.shutdown()+ if self._workers.get(abs_path) is not worker:+ return+ del self._workers[abs_path]+ worker.shutdown()def get_or_create(self, file_path: str) -> AppHost:abs_path = os.path.abspath(file_path)-- if self._sandbox:- return self._get_or_create_sandboxed(abs_path)-- with self._lock:- return self._create_locked(abs_path)-- def _get_or_create_sandboxed(self, abs_path: str) -> AppHost:- """Get or create an AppHost with a sandboxed venv.-- Uses double-check locking: the venv build (which can take many- seconds) runs outside the lock to avoid blocking other threads.- """- with self._lock:- worker = self._workers.get(abs_path)- if worker is not None and worker.is_alive():- return worker-- # Build sandbox venv outside lock (can take many seconds)- sandbox_dir, python = build_sandbox_venv(- abs_path, additional_deps=get_ipc_kernel_deps()- )-with self._lock:- # Re-check. Another thread may have created it while we were- # building the venv+ if self._closed:+ raise KernelStartupError("App host pool is shut down")worker = self._workers.get(abs_path)if worker is not None and worker.is_alive():- cleanup_sandbox_dir(sandbox_dir)return worker-- return self._create_locked(- abs_path, python=python, sandbox_dir=sandbox_dir+ pending = self._pending.get(abs_path)+ owner = pending is None+ if pending is None:+ pending = Future()+ self._pending[abs_path] = pending++ if not owner:+ return pending.result()++ new_worker: AppHost | None = None+ try:+ if worker is not None:+ worker.shutdown()+ plan = self._sandbox_plan(abs_path) if self._sandbox else None+ with self._lock:+ if self._closed:+ raise KernelStartupError("App host pool is shut down")+ new_worker = AppHost(+ abs_path,+ plan=plan,+ on_empty=lambda: self._remove_and_shutdown(abs_path, created),)-- def _create_locked(- self,- abs_path: str,- python: str | None = None,- sandbox_dir: str | None = None,- ) -> AppHost:- """Create a new AppHost, replacing a dead one if present.-- Must be called while holding self._lock.- """- worker = self._workers.get(abs_path)- if worker is not None and worker.is_alive():- return worker-- if worker is not None:- LOGGER.warning("App host for %s was dead, respawning", abs_path)- worker.shutdown()-- def _on_empty() -> None:- self._remove_and_shutdown(abs_path)-- worker = AppHost(- abs_path,- python=python,- sandbox_dir=sandbox_dir,- on_empty=_on_empty,- )- worker.start()- self._workers[abs_path] = worker- return worker+ created = new_worker+ new_worker.start()+ with self._lock:+ if self._closed:+ raise KernelStartupError("App host pool is shut down")+ self._workers[abs_path] = new_worker+ pending.set_result(new_worker)+ return new_worker+ except BaseException as error:+ pending.set_exception(error)+ if new_worker is not None:+ new_worker.shutdown()+ raise+ finally:+ with self._lock:+ del self._pending[abs_path]++ def _sandbox_plan(self, abs_path: str) -> ProcessPlan:+ args = ["-m", "marimo._session.app_host.main"]+ overlay = runtime_overlay()+ try:+ try:+ handle = sync_notebook(abs_path)+ except UvMissingScriptMetadataError:+ import platform++ plan = launch_isolated(+ args, overlay=overlay, python=platform.python_version()+ )+ plan.env.pop("MARIMO_SANDBOX_MODE", None)+ else:+ plan = launch(handle, args, overlay=overlay)+ plan.env["MARIMO_SANDBOX_MODE"] = "multi"+ plan.env["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"+ return plan+ except EnvironmentManagerError as error:+ raise KernelStartupError(str(error)) from errordef shutdown(self) -> None:- # Collect and clear under the lock, then shut down outside- # it. worker.shutdown() can trigger _on_empty callbacks that- # call _remove_and_shutdown, which also acquires self._lock;- # Holding the lock here would deadlock.with self._lock:+ self._closed = Trueworkers = list(self._workers.values())self._workers.clear()-+ # In-flight startups observe _closed before publishing and clean up.for worker in workers:worker.shutdown()diff --git a/marimo/_session/managers/ipc.py b/marimo/_session/managers/ipc.pyindex 6b381ff10c..a1f3746560 100644--- a/marimo/_session/managers/ipc.py+++ b/marimo/_session/managers/ipc.py@@ -8,24 +8,34 @@ via ZeroMQ channels. Each notebook gets its own sandboxed virtual environment.from __future__ import annotationsimport os+import queue+import signalimport subprocess+import sys+import threading+import time+from collections import dequefrom pathlib import Pathfrom typing import TYPE_CHECKING, cast+from uuid import uuid4from marimo import _loggers-from marimo._cli.sandbox import (- build_sandbox_venv,- cleanup_sandbox_dir,-)from marimo._config.config import VenvConfigfrom marimo._config.manager import MarimoConfigReaderfrom marimo._config.settings import GLOBAL_SETTINGS+from marimo._environments.environment import (+ Environment,+ launch,+ launch_isolated,+ sync_notebook,+)+from marimo._environments.overlay import runtime_overlay+from marimo._environments.uv import UvError, UvMissingScriptMetadataErrorfrom marimo._messaging.types import KernelMessagefrom marimo._runtime import commandsfrom marimo._session._venv import (check_python_version_compatibility,get_configured_venv_python,- get_ipc_kernel_deps,get_kernel_pythonpath,has_marimo_installed,install_marimo_into_venv,@@ -44,6 +54,7 @@ if TYPE_CHECKING:from marimo._ipc.queue_manager import QueueManager as IPCQueueManagerTypefrom marimo._ipc.types import ConnectionInfofrom marimo._runtime.commands import AppMetadata+ from marimo._runtime.virtual_file.storage import VirtualFileStorageTypefrom marimo._types.ids import CellId_tLOGGER = _loggers.marimo_logger()@@ -55,6 +66,56 @@ def _get_venv_config(config_manager: MarimoConfigReader) -> VenvConfig:return cast(VenvConfig, config.get("venv", {}))+# How long close_kernel waits for the kernel to dump its profile, and+# for a graceful exit, before killing it. Bounded: the live server+# closes sessions on the event loop, which must not stall indefinitely.+PROFILE_FLUSH_TIMEOUT: float = 10.0+GRACEFUL_EXIT_TIMEOUT: float = 5.0++# How long start_kernel waits for KERNEL_READY. Generous by default: a+# cold uv resolution of the notebook's environment can take minutes.+KERNEL_STARTUP_TIMEOUT: float = 600.0+++def _startup_timeout() -> float:+ raw = os.environ.get("MARIMO_KERNEL_STARTUP_TIMEOUT")+ if raw:+ try:+ return float(raw)+ except ValueError:+ LOGGER.warning(+ "Ignoring invalid MARIMO_KERNEL_STARTUP_TIMEOUT: %s", raw+ )+ return KERNEL_STARTUP_TIMEOUT+++def _profile_path_for(filename: str | None) -> str | None:+ """Where this kernel dumps profile statistics, if profiling is on."""+ profile_dir = GLOBAL_SETTINGS.PROFILE_DIR+ if profile_dir is None:+ return None+ basename = (+ os.path.basename(filename) + str(uuid4())+ if filename is not None+ else str(uuid4())+ )+ return os.path.join(profile_dir, basename)+++def _virtual_file_storage() -> VirtualFileStorageType | None:+ """Storage for the kernel's virtual files.++ Shared memory, so the server's /@file endpoint can read buffers the+ kernel subprocess wrote. `marimo run` does not preflight shared+ memory the way `marimo edit` does, so fall back to None (inline data+ URLs) where it is unavailable rather than failing kernel startup.+ """+ from marimo._utils.platform import check_shared_memory_available++ available, _ = check_shared_memory_available()+ return "shared_memory" if available else None++class KernelStartupError(Exception):"""Raised when kernel subprocess fails to start."""@@ -128,6 +189,27 @@ class IPCQueueManagerImpl(QueueManager):self.input_queue.put(text)+def _decode_tail(tail: deque[bytes]) -> str:+ return b"".join(tail).decode(errors="replace")+++def _parse_kernel_info(line: str) -> tuple[int | None, str | None]:+ """Parses the optional `KERNEL_INFO <pid> <executable>` line.++ Tolerates absence and shorter forms for version skew with kernels+ that predate the line.+ """+ parts = line.split(" ", 2)+ if len(parts) < 2 or parts[0] != "KERNEL_INFO":+ return None, None+ try:+ pid = int(parts[1])+ except ValueError:+ return None, None+ executable = parts[2] if len(parts) > 2 and parts[2] else None+ return pid, executable++def construct_kernel_env(base_env: dict[str, str],venv_python: str,@@ -141,8 +223,8 @@ def construct_kernel_env(Args:base_env: Starting environment (typically `os.environ.copy()`).venv_python: Path to the Python executable in the target venv.- is_ephemeral_sandbox: Whether this is an ephemeral sandbox venv- built by `build_sandbox_venv`.+ is_ephemeral_sandbox: Whether the kernel runs in a sandbox venv+ rather than a configured one.writable: Whether the kernel venv supports package installs.kernel_pythonpath: Extra PYTHONPATH entries for read-onlyconfigured venvs that don't have marimo installed.@@ -152,6 +234,12 @@ def construct_kernel_env("""env = dict(base_env)+ # Sandbox identity is per-kernel, not inherited: a configured venv+ # kernel inside a sandboxed server must not route package changes+ # through a script environment it does not run in.+ env.pop("MARIMO_SANDBOX_MODE", None)+ env.pop("MARIMO_MANAGE_SCRIPT_METADATA", None)+if kernel_pythonpath is not None:existing = env.get("PYTHONPATH", "")if existing:@@ -202,8 +290,17 @@ class IPCKernelManagerImpl(KernelManager):self._process: subprocess.Popen[bytes] | None = Noneself.kernel_task: ProcessLike | None = None- self._sandbox_dir: str | None = Noneself._venv_python: str | None = None+ self._profile_path = _profile_path_for(app_metadata.filename)+ self._script_environment: Environment | None = None+ # The kernel's own pid: a launcher such as uv may sit between the+ # manager and the kernel, so _process.pid is not the kernel.+ self._kernel_pid: int | None = None++ @property+ def script_environment(self) -> Environment | None:+ """The synchronized script environment the kernel runs in, if any."""+ return self._script_environmentdef start_kernel(self) -> None:from marimo._cli.print import echo, muted@@ -214,11 +311,12 @@ class IPCKernelManagerImpl(KernelManager):app_metadata=self.app_metadata,user_config=self.config_manager.get_config(hide_secrets=False),log_level=GLOBAL_SETTINGS.LOG_LEVEL,- profile_path=None,+ profile_path=self.profile_path,connection_info=self.connection_info,is_run_mode=self.mode == SessionMode.RUN,redirect_console_to_browser=self.redirect_console_to_browser,parent_pid=os.getpid(),+ virtual_file_storage=_virtual_file_storage(),)venv_config = _get_venv_config(self.config_manager)@@ -232,7 +330,6 @@ class IPCKernelManagerImpl(KernelManager):# Ephemeral sandboxes are always writable; configured venvs respect the# flag.writable = True- is_ephemeral_sandbox = Falsekernel_pythonpath: str | None = None# An explicitly configured venv takes precedence over an ephemeral@@ -278,41 +375,86 @@ class IPCKernelManagerImpl(KernelManager):# current runtime as a last chance effort to expose marimo# to the kernel.kernel_pythonpath = get_kernel_pythonpath()- else:- # Fall back to building ephemeral sandbox venv- # with IPC dependencies.- # NB. "Ephemeral" sandboxes (or rather tmp sandboxes built by uv)- # are always writable, and as such install marimo as a default,- # making them much easier than a configured venv we cannot manage.- is_ephemeral_sandbox = True- try:- self._sandbox_dir, venv_python = build_sandbox_venv(- self.app_metadata.filename,- additional_deps=get_ipc_kernel_deps(),- )- except Exception as e:- cleanup_sandbox_dir(self._sandbox_dir)- raise KernelStartupError(- f"Failed to build sandbox environment.\n\n{e}"- ) from e-- echo(- f"Running kernel in sandbox: {muted(venv_python)}",- err=True,+ # Store the venv python for package manager targeting+ self._venv_python = venv_python+ env = construct_kernel_env(+ base_env=os.environ.copy(),+ venv_python=venv_python,+ is_ephemeral_sandbox=False,+ writable=writable,+ kernel_pythonpath=kernel_pythonpath,)+ cmd: list[str] = [venv_python, "-m", "marimo._ipc.launch_kernel"]+ plan_launched = False+ else:+ # Synchronize the notebook's script environment; a notebook+ # without a metadata block runs ephemerally, and packages+ # installed during its session die with it.+ kernel_args_list = ["-m", "marimo._ipc.launch_kernel"]+ overlay = runtime_overlay()+ handle = None+ filename = self.app_metadata.filename+ if filename is not None:+ from marimo._environments import script_metadata++ # Best-effort: give metadata-less notebooks a block so+ # they get a real script environment instead of an+ # ephemeral one whose installs the server cannot target.+ try:+ script_metadata.ensure_marimo(filename)+ except Exception as e:+ LOGGER.warning(+ "Failed to add marimo to script metadata: %s", e+ )+ try:+ handle = sync_notebook(+ filename, on_output=lambda _line: None+ )+ except UvMissingScriptMetadataError:+ handle = None+ except UvError as e:+ raise KernelStartupError(+ f"Failed to build sandbox environment.\n\n{e}"+ ) from e- # Store the venv python for package manager targeting- self._venv_python = venv_python-- env = construct_kernel_env(- base_env=os.environ.copy(),- venv_python=venv_python,- is_ephemeral_sandbox=is_ephemeral_sandbox,- writable=writable,- kernel_pythonpath=kernel_pythonpath,- )-- cmd = [venv_python, "-m", "marimo._ipc.launch_kernel"]+ if handle is not None:+ self._venv_python = handle.python+ self._script_environment = handle+ plan = launch(+ handle,+ kernel_args_list,+ overlay=overlay,+ base_env=os.environ.copy(),+ )+ echo(+ f"Running kernel in script environment: "+ f"{muted(handle.root)}",+ err=True,+ )+ else:+ import platform++ plan = launch_isolated(+ kernel_args_list,+ overlay=overlay,+ python=platform.python_version(),+ base_env=os.environ.copy(),+ )+ echo("Running kernel in an ephemeral sandbox", err=True)++ plan_launched = True+ env = plan.env+ # Ephemeral sandboxes are always writable; the kernel manages+ # the notebook's script metadata.+ env["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"+ if handle is not None:+ # Only a kernel that runs in the script environment may+ # route package changes through it; an isolated kernel+ # installs into itself imperatively.+ env["MARIMO_SANDBOX_MODE"] = "multi"+ else:+ env.pop("MARIMO_SANDBOX_MODE", None)+ cmd = list(plan.argv)LOGGER.debug(f"Launching kernel: {' '.join(cmd)}")@@ -323,41 +465,139 @@ class IPCKernelManagerImpl(KernelManager):stdout=subprocess.PIPE,stderr=subprocess.PIPE,env=env,+ start_new_session=(+ plan.start_new_session if plan_launched else False+ ),)+ # Drain the kernel's stderr from the very start: uv resolves+ # the overlay at launch time, and its output can fill the+ # pipe before the kernel ever prints KERNEL_READY,+ # deadlocking startup. Tee to the server's stderr as the+ # kernel's console, keeping a tail for startup diagnostics.+ stderr_pipe = self._process.stderr+ stderr_tail: deque[bytes] = deque(maxlen=64)++ def drain_stderr() -> None:+ assert stderr_pipe is not None+ for line in iter(stderr_pipe.readline, b""):+ stderr_tail.append(line)+ try:+ sys.stderr.buffer.write(line)+ sys.stderr.buffer.flush()+ except Exception:+ pass+ stderr_pipe.close()++ threading.Thread(target=drain_stderr, daemon=True).start()+# Send connection info via stdinassert self._process.stdin is not Noneself._process.stdin.write(kernel_args.encode_json())self._process.stdin.flush()self._process.stdin.close()- # Wait for ready signal- assert self._process.stdout is not None- ready = self._process.stdout.readline().decode().strip()+ # Read the handshake on a thread so the wait can be bounded+ # and can notice a child that dies without printing it.+ # Plan-launched kernels run the overlay-pinned marimo, so+ # the KERNEL_INFO line is guaranteed; a configured venv may+ # run an older marimo that never prints it, and reading a+ # second line would hang its startup.+ stdout_pipe = self._process.stdout+ assert stdout_pipe is not None+ expected_lines = 2 if plan_launched else 1+ handshake: queue.Queue[str] = queue.Queue()++ def read_handshake() -> None:+ for _ in range(expected_lines):+ line = stdout_pipe.readline()+ if not line:+ return+ handshake.put(line.decode().strip())++ threading.Thread(target=read_handshake, daemon=True).start()++ deadline = time.monotonic() + _startup_timeout()+ ready = self._await_handshake_line(+ handshake, deadline, stderr_tail, cmd+ )if ready != "KERNEL_READY":- assert self._process.stderr is not None- stderr = self._process.stderr.read().decode()raise KernelStartupError(f"Kernel failed to start.\n\n"f"Command: {' '.join(cmd)}\n\n"- f"Stderr:\n{stderr}"+ f"Stderr:\n{_decode_tail(stderr_tail)}"+ )++ if plan_launched:+ info = self._await_handshake_line(+ handshake, deadline, stderr_tail, cmd)+ kernel_pid, kernel_executable = _parse_kernel_info(info)+ self._kernel_pid = kernel_pid+ if self._venv_python is None and kernel_executable is not None:+ # An ephemeral kernel's environment is only knowable+ # from the kernel itself; the server package panel+ # targets it.+ self._venv_python = kernel_executableLOGGER.debug("Kernel ready")# Create a ProcessLike wrapper for the subprocessself.kernel_task = _SubprocessWrapper(self._process)except KernelStartupError:- # Already a KernelStartupError, just cleanup and re-raise- cleanup_sandbox_dir(self._sandbox_dir)raiseexcept Exception as e:# Wrap other exceptions as KernelStartupError- cleanup_sandbox_dir(self._sandbox_dir)raise KernelStartupError(f"Failed to start kernel subprocess.\n\n{e}") from e+ def _await_handshake_line(+ self,+ handshake: queue.Queue[str],+ deadline: float,+ stderr_tail: deque[bytes],+ cmd: list[str],+ ) -> str:+ """The next handshake line, bounded by exit and deadline.++ Raises `KernelStartupError` when the child exits without+ producing it or the deadline passes; a hung child is killed so+ an unresponsive launch cannot leak a process tree.+ """+ assert self._process is not None+ while True:+ try:+ return handshake.get(timeout=0.1)+ except queue.Empty:+ pass+ if self._process.poll() is not None:+ # The reader thread may still be flushing lines the+ # child printed just before exiting.+ try:+ return handshake.get(timeout=0.5)+ except queue.Empty:+ raise KernelStartupError(+ f"Kernel exited during startup "+ f"(exit code {self._process.returncode}).\n\n"+ f"Command: {' '.join(cmd)}\n\n"+ f"Stderr:\n{_decode_tail(stderr_tail)}"+ ) from None+ if time.monotonic() > deadline:+ try:+ try_kill_process_and_group(+ _SubprocessWrapper(self._process)+ )+ except Exception as e:+ LOGGER.warning(e)+ raise KernelStartupError(+ f"Kernel did not become ready within "+ f"{_startup_timeout():.0f}s (override with "+ f"MARIMO_KERNEL_STARTUP_TIMEOUT).\n\n"+ f"Command: {' '.join(cmd)}\n\n"+ f"Stderr:\n{_decode_tail(stderr_tail)}"+ )+@propertydef pid(self) -> int | None:if self._process is None:@@ -366,8 +606,7 @@ class IPCKernelManagerImpl(KernelManager):@propertydef profile_path(self) -> str | None:- # Profiling not currently supported with IPC kernel- return None+ return self._profile_path@propertydef venv_python(self) -> str | None:@@ -385,18 +624,47 @@ class IPCKernelManagerImpl(KernelManager):if self._process.pid is not None and self.is_alive():interrupt_kernel_process(- self._process.pid,+ self._kernel_pid or self._process.pid,self.queue_manager.win32_interrupt_queue,)def close_kernel(self, *, graceful: bool = False) -> None:- del graceful # unsupported here: IPC shutdown never waits for exit.if self._process is not None:self.queue_manager.put_control_request(commands.StopKernelCommand())+ # A clean stop lets the kernel flush pending work (the+ # profile dump, cache writes) before we kill it. Unlike the+ # multiprocessing manager, every wait here is bounded.+ if self.profile_path is not None and self.is_alive():+ from marimo._cli.print import echo++ echo(+ f"\tWriting profile statistics to {self.profile_path} ..."+ )+ # The kernel dumps stats just before exiting, so a+ # completed exit means a complete file. (The+ # multiprocessing manager polls for the file instead+ # because joining its Process hangs; subprocess.wait+ # has no such problem.)+ try:+ self._process.wait(timeout=PROFILE_FLUSH_TIMEOUT)+ except subprocess.TimeoutExpired:+ passself.queue_manager.close_queues()+ if graceful and self._process.poll() is None:+ try:+ self._process.wait(timeout=GRACEFUL_EXIT_TIMEOUT)+ except subprocess.TimeoutExpired:+ passif self._process.poll() is None and self.kernel_task is not None:+ # The kernel leads its own process group; kill it first+ # so user-code subprocesses die too, then the launcher.+ if self._kernel_pid is not None and sys.platform != "win32":+ try:+ os.killpg(os.getpgid(self._kernel_pid), signal.SIGTERM)+ except (ProcessLookupError, PermissionError):+ passtry:try_kill_process_and_group(self.kernel_task)except ProcessLookupError:@@ -405,8 +673,6 @@ class IPCKernelManagerImpl(KernelManager):LOGGER.warning(e)# Always attempt cleanup, even if _process is None- cleanup_sandbox_dir(self._sandbox_dir)- self._sandbox_dir = None@propertydef kernel_connection(self) -> TypedConnection[KernelMessage]:diff --git a/marimo/_utils/subprocess.py b/marimo/_utils/subprocess.pyindex 2e7a86aaa9..d9cdd5628a 100644--- a/marimo/_utils/subprocess.py+++ b/marimo/_utils/subprocess.py@@ -383,13 +383,23 @@ def try_kill_process_and_group(process: ProcessLike) -> None:to reap the process."""pid = process.pid- if pid is None:+ if pid is None or _process_finished(process):returnif is_windows():- # TODO(akshayka): Investigate whether we need to kill an entire- # process group on Windows, and if so how ...- process.terminate()+ # A launcher such as uv may sit between us and the kernel; kill+ # the whole tree rooted at the direct child.+ import subprocess as _subprocess++ try:+ completed = _subprocess.run(+ ["taskkill", "/T", "/F", "/PID", str(pid)],+ capture_output=True,+ )+ if completed.returncode != 0:+ process.terminate()+ except Exception:+ process.terminate()returnpgid = os.getpgid(pid)@@ -414,3 +424,34 @@ def try_kill_process_and_group(process: ProcessLike) -> None:task.add_done_callback(_REAP_TASKS.discard)except RuntimeError:pass+++def kill_subprocess(+ process: subprocess.Popen[Any], *, start_new_session: bool+) -> None:+ """Kill and reap a cancelled synchronous command and its launch group.++ Use SIGKILL for an isolated group so a descendant ignoring SIGTERM+ cannot keep captured pipes open after the launcher exits.+ """+ if process.poll() is not None:+ return+ if is_windows():+ try:+ subprocess.run(+ ["taskkill", "/T", "/F", "/PID", str(process.pid)],+ capture_output=True,+ timeout=5,+ )+ except (OSError, subprocess.TimeoutExpired):+ pass+ process.kill()+ else:+ try:+ if start_new_session:+ os.killpg(process.pid, signal.SIGKILL)+ else:+ process.kill()+ except ProcessLookupError:+ pass+ process.wait()diff --git a/pyproject.toml b/pyproject.tomlindex b799341c3e..297fc02ccf 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -93,9 +93,9 @@ sql = ["sqlglot[c]>=26.8.0" # SQL cells parsing;]-# For per-notebook sandboxed kernels+# For per-notebook sandboxed kernels. pyzmq moved to the core+# dependencies; the extra remains for the uv wheel.sandbox = [- "pyzmq>=27.1.0", # IPC communication for sandbox kernels"uv>=0.9.21", # for sandbox management and local html-wasm exports]diff --git a/tests/_cli/test_cli.py b/tests/_cli/test_cli.pyindex 58166b3ea6..bc0f0ae545 100644--- a/tests/_cli/test_cli.py+++ b/tests/_cli/test_cli.py@@ -407,50 +407,6 @@ def test_cli_missing_argument_uses_compact_error() -> None:assert "Options:" not in result.output-def test_cli_edit_sandbox_missing_zmq_skips_update_check() -> None:- from click.testing import CliRunner-- from marimo._cli.cli import main-- runner = CliRunner()- captured_packages: dict[str, str | list[str]] = {}-- def _capture_install_commands(- packages: str | list[str] | tuple[str, ...],- ) -> list[str]:- captured_packages["value"] = (- packages if isinstance(packages, str) else list(packages)- )- return ["python -m pip install 'marimo[sandbox]'"]-- with (- patch(- "marimo._cli.cli.prompt_run_in_docker_container",- return_value=False,- ),- patch(- "marimo._dependencies.dependencies.DependencyManager.zmq.has",- return_value=False,- ),- patch(- "marimo._cli.errors.get_install_commands",- side_effect=_capture_install_commands,- ),- patch("marimo._cli.cli.check_for_updates") as mock_check_for_updates,- ):- result = runner.invoke(main, ["edit", "--sandbox"])-- assert result.exit_code == 1- mock_check_for_updates.assert_not_called()- assert captured_packages["value"] == "marimo[sandbox]"- assert (- "pyzmq is required when running the marimo edit server on a directory with --sandbox."- in result.output- )- assert "python -m pip install 'marimo[sandbox]'" in result.output- assert "'marimo[sandbox]' pyzmq" not in result.output--def test_cli_edit_checks_for_updates_after_preflight() -> None:from click.testing import CliRunner@@ -1388,6 +1344,7 @@ def test_cli_sandbox_edit_new_file() -> None:with patch("marimo._cli.sandbox.run_in_sandbox") as mock_run_in_sandbox:+ mock_run_in_sandbox.return_value = 0result = runner.invoke(cli_main,["edit", path, "--headless", "--no-token", "--sandbox"],@@ -1921,6 +1878,7 @@ def test_cli_with_custom_pyproject_config_no_file(tmp_path: Path) -> None:with patch("marimo._cli.sandbox.run_in_sandbox") as mock_run_in_sandbox:+ mock_run_in_sandbox.return_value = 0result = runner.invoke(cli_main,["new", "--sandbox", "--headless", "--no-token"],diff --git a/tests/_cli/test_cli_export.py b/tests/_cli/test_cli_export.pyindex 356e67aace..2d18c2c277 100644--- a/tests/_cli/test_cli_export.py+++ b/tests/_cli/test_cli_export.py@@ -209,6 +209,22 @@ def test_ruff_import_graph_ignores_successful_stderr(tmp_path: Path) -> None:assert graph == {notebook.resolve(): (module.resolve(),)}+def _supports_script_environments() -> bool:+ from marimo._environments.environment import ensure_supported_uv+ from marimo._environments.uv import UvError, is_uv_available++ if not is_uv_available():+ return False+ try:+ ensure_supported_uv()+ except UvError:+ return False+ return True+++SUPPORTS_SCRIPT_ENVS = _supports_script_environments()++class TestExportHTML:@staticmethoddef test_cli_export_html(temp_marimo_file: str) -> None:@@ -651,6 +667,9 @@ class TestExportHTML:@staticmethod@pytest.mark.skipif(not HAS_UV, reason="uv is required for sandbox tests")+ @pytest.mark.skipif(+ not SUPPORTS_SCRIPT_ENVS, reason="uv >= 0.7.21 required"+ )def test_cli_export_html_sandbox(temp_marimo_file: str) -> None:# Must use subprocess: sandbox re-invokes via uv using sys.argv[1:]p = subprocess.run(@@ -662,7 +681,7 @@ class TestExportHTML:output = p.stderr.decode()# Check for sandbox messageassert "Running in a sandbox" in output- assert "run --isolated" in output+ assert "Using script environment" in outputhtml = normalize_index_html(output)html = _normalize_html_path(html, temp_marimo_file)assert '<marimo-code hidden=""></marimo-code>' not in html@@ -1274,6 +1293,9 @@ class TestExportIpynb:not HAS_UV or not DependencyManager.nbformat.has(),reason="This test requires both uv and nbformat.",)+ @pytest.mark.skipif(+ not SUPPORTS_SCRIPT_ENVS, reason="uv >= 0.7.21 required"+ )def test_cli_export_ipynb_sandbox(temp_marimo_file: str) -> None:output_file = temp_marimo_file.replace(".py", "_sandbox.ipynb")# Must use subprocess: sandbox re-invokes via uv using sys.argv[1:]@@ -1295,7 +1317,7 @@ class TestExportIpynb:output = p.stderr.decode()# Check for sandbox messageassert "Running in a sandbox" in output- assert "run --isolated" in output+ assert "Using script environment" in output@staticmethod@pytest.mark.skipif(diff --git a/tests/_cli/test_cli_export_session.py b/tests/_cli/test_cli_export_session.pyindex 02007d3881..38aeb5b99a 100644--- a/tests/_cli/test_cli_export_session.py+++ b/tests/_cli/test_cli_export_session.py@@ -170,9 +170,9 @@ def test_export_sessions_continue_on_error_processes_remaining(marimo_path: session_module.MarimoPath,*,notebook_args: tuple[str, ...],- venv_python: str | None = None,+ sandbox: object | None = None,) -> tuple[dict[str, str], bool]:- del notebook_args, venv_python+ del notebook_args, sandboxcalled.append(marimo_path.short_name)if marimo_path.short_name == "second.py":raise click.ClickException("boom")@@ -224,9 +224,9 @@ def test_export_sessions_no_continue_on_error_stops_at_first_error(marimo_path: session_module.MarimoPath,*,notebook_args: tuple[str, ...],- venv_python: str | None = None,+ sandbox: object | None = None,) -> tuple[dict[str, str], bool]:- del notebook_args, venv_python+ del notebook_args, sandboxcalled.append(marimo_path.short_name)if marimo_path.short_name == "first.py":raise click.ClickException("first failed")diff --git a/tests/_cli/test_export_subprocess.py b/tests/_cli/test_export_subprocess.pynew file mode 100644index 0000000000..8b41b20e0d--- /dev/null+++ b/tests/_cli/test_export_subprocess.py@@ -0,0 +1,162 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++import os+import subprocess+import sys+from typing import Any+from unittest.mock import patch++import click+import pytest++from marimo._cli.export._common import SandboxTarget, run_python_subprocess+from marimo._environments.environment import Environment, ProcessPlan++[email protected]("isolated", [False, True])+def test_export_runs_the_planned_command(isolated: bool) -> None:+ handle = (+ None+ if isolated+ else Environment(sys.executable, sys.prefix, "unchanged")+ )+ module = "marimo._environments.environment"+ target = f"{module}.launch_isolated" if isolated else f"{module}.launch"+ code = (+ "import json,os,sys; print(json.dumps([os.getpid(), os.getsid(0)]))"+ if os.name != "nt"+ else "print('done')"+ )+ plan = ProcessPlan((sys.executable, "-c", code), dict(os.environ), True)+ with patch(target, return_value=plan):+ output = run_python_subprocess(+ sandbox=SandboxTarget(handle),+ script="ignored",+ payload={},+ action="export",+ )+ if os.name != "nt":+ import json++ pid, session = json.loads(output)+ assert pid == session+ else:+ assert output.strip() == "done"+++def test_export_failure_identifies_launcher_without_payload_or_credentials() -> (+ None+):+ plan = ProcessPlan(+ (+ sys.executable,+ "-c",+ "import sys; print('failed', file=sys.stderr); sys.exit(2)",+ "https://user:[email protected]",+ "private notebook",+ ),+ dict(os.environ),+ True,+ )+ with patch(+ "marimo._environments.environment.launch_isolated", return_value=plan+ ):+ with pytest.raises(click.ClickException) as error:+ run_python_subprocess(+ sandbox=SandboxTarget(None),+ script="private notebook",+ payload={"token": "secret"},+ action="export",+ )+ message = str(error.value)+ assert os.path.basename(sys.executable) in message+ assert "failed" in message+ assert "secret" not in message+ assert "private notebook" not in message++[email protected]("new_session", [False, True])+def test_export_interrupt_reaps_the_child(new_session: bool) -> None:+ children = []+ popen = subprocess.Popen++ class InterruptedProcess(subprocess.Popen):+ def communicate(self, *_args: Any, **_kwargs: Any):+ assert self.stdout.readline().strip() == "ready"+ raise KeyboardInterrupt++ def launch(*args: Any, **kwargs: Any):+ # `patch` mutates the shared subprocess module, so Windows taskkill+ # launched by `kill_subprocess` must keep using the real Popen.+ if args[0][0] == "taskkill":+ return popen(*args, **kwargs)+ child = InterruptedProcess(*args, **kwargs)+ children.append(child)+ return child++ plan = ProcessPlan(+ (+ sys.executable,+ "-c",+ "import time; print('ready', flush=True); time.sleep(30)",+ ),+ dict(os.environ),+ new_session,+ )+ with (+ patch(+ "marimo._environments.environment.launch_isolated",+ return_value=plan,+ ),+ patch(+ "marimo._cli.export._common.subprocess.Popen", side_effect=launch+ ),+ ):+ with pytest.raises(KeyboardInterrupt):+ run_python_subprocess(+ sandbox=SandboxTarget(None),+ script="",+ payload={},+ action="export",+ )+ child = children[0]+ assert child.poll() is not None+ assert child.stdout.closed+ assert child.stderr.closed++[email protected](os.name == "nt", reason="POSIX termination signals")+def test_export_sigterm_reaps_isolated_child(tmp_path) -> None:+ import signal+ import time++ ready = tmp_path / "ready"+ code = f"""+import os, sys+from marimo._cli.export._common import SandboxTarget, run_python_subprocess+from marimo._environments import environment+child = "import os,time; from pathlib import Path; Path({str(ready)!r}).write_text(str(os.getpid())); time.sleep(30)"+environment.launch_isolated = lambda *a, **kw: environment.ProcessPlan((sys.executable, '-c', child), dict(os.environ), True)+run_python_subprocess(sandbox=SandboxTarget(None), script='', payload={{}}, action='export')+"""+ parent = subprocess.Popen([sys.executable, "-c", code])+ child_pid = None+ try:+ deadline = time.monotonic() + 10+ while not ready.exists() and time.monotonic() < deadline:+ assert parent.poll() is None+ time.sleep(0.02)+ child_pid = int(ready.read_text())+ parent.send_signal(signal.SIGTERM)+ assert parent.wait(timeout=10) == 128 + signal.SIGTERM+ with pytest.raises(ProcessLookupError):+ os.kill(child_pid, 0)+ finally:+ parent.kill()+ parent.wait(timeout=5)+ if child_pid is not None:+ try:+ os.kill(child_pid, signal.SIGKILL)+ except ProcessLookupError:+ passdiff --git a/tests/_cli/test_sandbox.py b/tests/_cli/test_sandbox.pyindex d36b3c3ec0..d7cbfd5a23 100644--- a/tests/_cli/test_sandbox.py+++ b/tests/_cli/test_sandbox.py@@ -11,8 +11,6 @@ from marimo._cli.sandbox import (SandboxMode,_normalize_sandbox_dependencies,_uv_export_script_requirements_txt,- build_sandbox_venv,- cleanup_sandbox_dir,construct_uv_command,resolve_sandbox_mode,run_in_sandbox,@@ -491,19 +489,20 @@ import marimo)# Mock the prompt to return True (simulating user typing 'y')- with patch("marimo._cli.sandbox.click.confirm", return_value=True):- with patch(- "marimo._cli.sandbox.is_uv_available",- return_value=True,- ):- with patch(- "marimo._cli.sandbox.sys.stdin.isatty", return_value=True- ):- result = resolve_sandbox_mode(- sandbox=None,- name=str(script_path),- )- assert result is SandboxMode.SINGLE+ with (+ patch(+ "marimo._cli.sandbox.GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA",+ False,+ ),+ patch("marimo._cli.sandbox.click.confirm", return_value=True),+ patch("marimo._cli.sandbox.is_uv_available", return_value=True),+ patch("marimo._cli.sandbox.sys.stdin.isatty", return_value=True),+ ):+ result = resolve_sandbox_mode(+ sandbox=None,+ name=str(script_path),+ )+ assert result is SandboxMode.SINGLEdef test_resolve_sandbox_mode_explicit_single() -> None:@@ -590,128 +589,6 @@ import marimoassert uv_cmd[python_idx + 1] == platform.python_version()-def test_get_sandbox_requirements_adds_additional_deps(tmp_path: Path) -> None:- """Test that additional deps are added when not present."""- from marimo._cli.sandbox import get_sandbox_requirements-- script_path = tmp_path / "test.py"- script_path.write_text(- """# /// script-# dependencies = ["numpy"]-# ///-import marimo-"""- )-- with patch("marimo._cli.sandbox.is_editable", return_value=False):- reqs = get_sandbox_requirements(- str(script_path),- additional_deps=["pyzmq", "msgspec"],- )-- assert any("numpy" in r for r in reqs)- assert "pyzmq" in reqs- assert "msgspec" in reqs---def test_get_sandbox_requirements_no_duplicate_deps(tmp_path: Path) -> None:- """Test that additional deps aren't duplicated if already present."""- from marimo._cli.sandbox import get_sandbox_requirements-- script_path = tmp_path / "test.py"- script_path.write_text(- """# /// script-# dependencies = ["numpy", "pyzmq>=25.0"]-# ///-import marimo-"""- )-- with patch("marimo._cli.sandbox.is_editable", return_value=False):- reqs = get_sandbox_requirements(- str(script_path),- additional_deps=["pyzmq", "msgspec"],- )-- # Should have only one pyzmq entry (uv resolves versions, so it may be ==X.Y.Z)- pyzmq_entries = [r for r in reqs if "pyzmq" in r.lower()]- assert len(pyzmq_entries) == 1- assert "msgspec" in reqs---def test_get_sandbox_requirements_none_filename() -> None:- """Test get_sandbox_requirements with None filename."""- from marimo._cli.sandbox import get_sandbox_requirements-- with patch("marimo._cli.sandbox.is_editable", return_value=False):- reqs = get_sandbox_requirements(None, additional_deps=["pyzmq"])-- # Should have marimo and additional deps- assert any("marimo" in r for r in reqs)- assert "pyzmq" in reqs---def test_cleanup_sandbox_dir_removes_directory(tmp_path: Path) -> None:- """Test that cleanup_sandbox_dir removes the directory."""- from marimo._cli.sandbox import cleanup_sandbox_dir-- sandbox_dir = tmp_path / "sandbox"- sandbox_dir.mkdir()- (sandbox_dir / "file.txt").write_text("test")-- cleanup_sandbox_dir(str(sandbox_dir))-- assert not sandbox_dir.exists()---def test_cleanup_sandbox_dir_handles_none() -> None:- """Test that cleanup_sandbox_dir handles None gracefully."""- from marimo._cli.sandbox import cleanup_sandbox_dir-- cleanup_sandbox_dir(None) # Should not raise---def test_cleanup_sandbox_dir_handles_nonexistent(tmp_path: Path) -> None:- """Test that cleanup_sandbox_dir handles nonexistent directory."""- from marimo._cli.sandbox import cleanup_sandbox_dir-- nonexistent = str(tmp_path / "does_not_exist")- cleanup_sandbox_dir(nonexistent) # Should not raise--[email protected](not HAS_UV, reason="uv required")-def test_build_sandbox_venv_creates_venv(tmp_path: Path) -> None:- """Test venv is created and returns paths."""- script = tmp_path / "test.py"- script.write_text("# /// script\n# dependencies = []\n# ///\n")-- sandbox_dir, venv_python = build_sandbox_venv(str(script))- try:- assert os.path.isdir(sandbox_dir)- assert os.path.exists(venv_python)- assert "python" in venv_python- finally:- cleanup_sandbox_dir(sandbox_dir)--[email protected](not HAS_UV, reason="uv required")-def test_build_sandbox_venv_with_additional_deps(tmp_path: Path) -> None:- """Test additional deps are passed through."""- from marimo._session._venv import get_ipc_kernel_deps-- script = tmp_path / "test.py"- script.write_text("# /// script\n# dependencies = []\n# ///\n")-- sandbox_dir, venv_python = build_sandbox_venv(- str(script), additional_deps=get_ipc_kernel_deps()- )- try:- assert os.path.isdir(sandbox_dir)- assert os.path.exists(venv_python)- finally:- cleanup_sandbox_dir(sandbox_dir)--def test_resolve_local_path_line() -> None:from marimo._cli.sandbox import _resolve_local_path_line@@ -788,3 +665,143 @@ import marimo)python_idx = uv_cmd.index("--python")assert uv_cmd[python_idx + 1] == "3.12"+++def _supports_sync() -> bool:+ from marimo._environments.environment import ensure_supported_uv+ from marimo._environments.uv import UvError, is_uv_available++ if not is_uv_available():+ return False+ try:+ ensure_supported_uv()+ except UvError:+ return False+ return True+++SUPPORTS_SYNC = _supports_sync()+++def _restore_signal_handlers():+ """run_in_sandbox installs forwarding handlers; undo them."""+ import signal++ saved = {+ sig: signal.getsignal(sig)+ for name in ("SIGINT", "SIGTERM", "SIGHUP")+ if (sig := getattr(signal, name, None)) is not None+ }+ yield+ for sig, handler in saved.items():+ signal.signal(sig, handler)++[email protected](not SUPPORTS_SYNC, reason="uv >= 0.7.21 required")+ os.name == "nt", reason="signal forwarding differs on Windows"+)[email protected]("_restore_signal_handlers")+def test_run_in_sandbox_from_script_environment(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ """The provisioned path: a markdown notebook's manifest is+ synchronized and marimo launches from the script environment."""+ from marimo._cli.sandbox import run_in_sandbox++ monkeypatch.setenv("UV_CACHE_DIR", str(tmp_path.parent / "uv-cache"))++ notebook = tmp_path / "notebook.md"+ notebook.write_text(+ """---+pyproject: |+ dependencies = []+---++# Hello+""",+ encoding="utf-8",+ )++ code = run_in_sandbox(["--version"], name=str(notebook))++ assert code == 0+ # The carrier is deleted after synchronization.+ assert not list(tmp_path.glob("*.py"))++[email protected](not SUPPORTS_SYNC, reason="uv >= 0.7.21 required")+ os.name == "nt", reason="signal forwarding differs on Windows"+)[email protected]("_restore_signal_handlers")+def test_run_in_sandbox_without_a_manifest() -> None:+ """No target means no manifest: marimo runs ephemerally."""+ from marimo._cli.sandbox import run_in_sandbox++ code = run_in_sandbox(["--version"], name=None)++ assert code == 0+++def test_sandbox_exit_codes_propagate(tmp_path: Path) -> None:+ """Every sandbox entry point exits with the inner process's code."""+ from unittest.mock import patch as mock_patch++ from click.testing import CliRunner++ from marimo._cli.cli import main as cli_main++ notebook = tmp_path / "nb.py"+ notebook.write_text(+ '# /// script\n# dependencies = ["numpy"]\n# ///\n', encoding="utf-8"+ )+ runner = CliRunner()++ for command, target in (+ (+ ["edit", str(notebook), "--sandbox", "--headless", "--no-token"],+ "marimo._cli.sandbox.run_in_sandbox",+ ),+ (+ ["export", "html", str(notebook), "--sandbox"],+ "marimo._cli.export.commands.run_in_sandbox",+ ),+ ):+ with (+ mock_patch(target, return_value=3),+ mock_patch(+ "marimo._cli.sandbox.maybe_prompt_run_in_sandbox",+ return_value=True,+ ),+ ):+ result = runner.invoke(cli_main, command)+ assert result.exit_code == 3, (command, result.output)+++ ("returncode", "expected"), [(0, 0), (7, 7), (-2, 130), (-15, 143)]+)[email protected]("_restore_signal_handlers")+def test_run_in_sandbox_normalizes_child_status(+ returncode: int, expected: int+) -> None:+ from unittest.mock import MagicMock, patch++ from marimo._environments.environment import ProcessPlan++ process = MagicMock()+ process.wait.return_value = returncode+ with (+ patch("marimo._cli.sandbox.require_uv_bin"),+ patch("marimo._cli.sandbox.runtime_overlay", return_value=[]),+ patch(+ "marimo._cli.sandbox.environment.launch_isolated",+ return_value=ProcessPlan(argv=("uv",), env={}),+ ),+ patch("marimo._cli.sandbox.subprocess.Popen", return_value=process),+ ):+ assert run_in_sandbox(["--version"]) == expecteddiff --git a/tests/_environments/test_environment.py b/tests/_environments/test_environment.pynew file mode 100644index 0000000000..7a4965fc47--- /dev/null+++ b/tests/_environments/test_environment.py@@ -0,0 +1,370 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++import json+import os+import stat+import subprocess+import sys+from typing import TYPE_CHECKING++import pytest++from marimo._environments import environment+from marimo._environments.environment import (+ Environment,+ UvUnsupportedVersionError,+ ensure_supported_uv,+ launch,+ sync,+)+from marimo._environments.uv import (+ UvError,+ UvMissingScriptMetadataError,+ UvResolutionError,+ is_uv_available,+)++if TYPE_CHECKING:+ from pathlib import Path+++def _supports_sync() -> bool:+ if not is_uv_available():+ return False+ try:+ ensure_supported_uv()+ except UvError:+ return False+ return True+++SUPPORTS_SYNC = _supports_sync()++REQUIRES_PYTHON = f">={sys.version_info[0]}.{sys.version_info[1]}"++EMPTY_SCRIPT = f"""\+# /// script+# requires-python = "{REQUIRES_PYTHON}"+# dependencies = []+# ///+"""+++def test_requires_restart() -> None:+ first = Environment(+ python="/env/bin/python", root="/env", action="created"+ )+ unchanged = Environment(+ python="/env/bin/python", root="/env", action="unchanged"+ )+ updated = Environment(+ python="/env/bin/python", root="/env", action="updated"+ )+ replaced = Environment(+ python="/env/bin/python", root="/env", action="replaced"+ )+ moved = Environment(+ python="/other/bin/python", root="/other", action="unchanged"+ )++ assert not first.requires_restart(None)+ assert not unchanged.requires_restart(first)+ assert not updated.requires_restart(first)+ assert replaced.requires_restart(first)+ assert moved.requires_restart(first)+++def test_process_env_targets_the_environment() -> None:+ env = Environment(python="/env/bin/python", root="/env", action="created")+ base = {"UV_PROJECT_ENVIRONMENT": "/project", "PATH": "/usr/bin"}++ child = env.process_env(base)++ assert child["VIRTUAL_ENV"] == "/env"+ assert "UV_PROJECT_ENVIRONMENT" not in child+ # The environment's tools resolve first, as under `uv run`.+ bin_dir = os.path.join("/env", "Scripts" if os.name == "nt" else "bin")+ assert child["PATH"] == f"{bin_dir}{os.pathsep}/usr/bin"+ # The base mapping is not mutated.+ assert base["UV_PROJECT_ENVIRONMENT"] == "/project"+++ sys.platform == "win32", reason="shell stub is not executable on Windows"+)+def test_old_uv_is_rejected(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ stub = tmp_path / "uv"+ stub.write_text('#!/bin/sh\necho "uv 0.5.0 (stub)"\n')+ stub.chmod(stub.stat().st_mode | stat.S_IEXEC)+ monkeypatch.setenv("UV", str(stub))++ with pytest.raises(UvUnsupportedVersionError, match="0.5.0"):+ sync(str(tmp_path / "nb.py"))++[email protected](not SUPPORTS_SYNC, reason="uv >= 0.7.21 required")+def test_sync_creates_and_reuses_the_environment(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ # An isolated cache keeps test environments out of the user's real+ # uv cache; tmp_path is unique per run, so they would accumulate.+ monkeypatch.setenv("UV_CACHE_DIR", str(tmp_path / "uv-cache"))+ script = tmp_path / "nb.py"+ script.write_text(EMPTY_SCRIPT, encoding="utf-8")++ first = sync(str(script), cwd=str(tmp_path))+ assert first.action == "created"+ assert os.path.exists(first.python)+ assert first.python.startswith(first.root)++ again = sync(str(script), cwd=str(tmp_path))+ assert again.action == "unchanged"+ assert again.python == first.python+ assert not again.requires_restart(first)++[email protected](not SUPPORTS_SYNC, reason="uv >= 0.7.21 required")+def test_sync_requires_script_metadata(tmp_path: Path) -> None:+ script = tmp_path / "plain.py"+ script.write_text("print('hi')\n", encoding="utf-8")+ with pytest.raises(UvMissingScriptMetadataError):+ sync(str(script))++[email protected](not SUPPORTS_SYNC, reason="uv >= 0.7.21 required")+def test_resolution_failure_carries_the_solver_message(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ monkeypatch.setenv("UV_OFFLINE", "1")+ monkeypatch.setenv("UV_CACHE_DIR", str(tmp_path / "uv-cache"))+ script = tmp_path / "nb.py"+ script.write_text(+ "# /// script\n"+ f'# requires-python = "{REQUIRES_PYTHON}"\n'+ '# dependencies = ["definitely-not-a-real-pkg-xyz==99.99"]\n'+ "# ///\n",+ encoding="utf-8",+ )+ with pytest.raises(UvResolutionError) as excinfo:+ sync(str(script), cwd=str(tmp_path))+ assert "definitely-not-a-real-pkg-xyz" in excinfo.value.stderr++[email protected](not SUPPORTS_SYNC, reason="uv >= 0.7.21 required")+def test_sync_honors_index_semantics(tmp_path: Path) -> None:+ """Repro from marimo-team/marimo#10547 (requires network access).++ pip-install-test==0.0.3 exists on test.pypi.org but not on pypi.org.+ The metadata pins it to a named explicit index; delegating to+ `uv sync --script` honors the pin, where flattening the indexes into+ command-line flags could not.+ """+ script = tmp_path / "nb.py"+ script.write_text(+ "# /// script\n"+ f'# requires-python = ">={sys.version_info[0]}.{sys.version_info[1]}"\n'+ "# dependencies = [\n"+ '# "pip-install-test==0.0.3",\n'+ "# ]\n"+ "#\n"+ "# [tool.uv.sources]\n"+ '# pip-install-test = { index = "testpypi" }\n'+ "#\n"+ "# [[tool.uv.index]]\n"+ '# url = "https://pypi.org/simple/"\n'+ "# default = true\n"+ "#\n"+ "# [[tool.uv.index]]\n"+ '# name = "testpypi"\n'+ '# url = "https://test.pypi.org/simple/"\n'+ "# explicit = true\n"+ "# ///\n",+ encoding="utf-8",+ )++ result = sync(str(script), cwd=str(tmp_path))++ site_packages = _site_packages(result.root)+ assert any(+ entry.startswith("pip_install_test") for entry in site_packages+ ), site_packages+++def _site_packages(root: str) -> list[str]:+ for dirpath, dirnames, _ in os.walk(root):+ if os.path.basename(dirpath) == "site-packages":+ del dirnames[:]+ return os.listdir(dirpath)+ return []+++def test_unreadable_report_raises(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setattr(environment, "ensure_supported_uv", lambda: None)++ class Completed:+ stdout = "not json"++ monkeypatch.setattr(+ environment, "uv", lambda *_args, **_kwargs: Completed()+ )+ with pytest.raises(environment.UvSyncReportError):+ sync("nb.py")++[email protected](not SUPPORTS_SYNC, reason="uv >= 0.7.21 required")+def test_sync_accepts_a_python_override(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ monkeypatch.setenv("UV_CACHE_DIR", str(tmp_path / "uv-cache"))+ script = tmp_path / "nb.py"+ script.write_text(EMPTY_SCRIPT, encoding="utf-8")+ override = f"{sys.version_info[0]}.{sys.version_info[1]}"++ env = sync(str(script), cwd=str(tmp_path), python_override=override)++ reported = subprocess.run(+ [env.python, "-c", "import sys; print(sys.version_info[:2])"],+ capture_output=True,+ text=True,+ check=True,+ ).stdout.strip()+ assert reported == str(tuple(sys.version_info[:2]))+++ ("raw_action", "action"),+ [+ ("create", "created"),+ ("update", "updated"),+ ("replace", "replaced"),+ ("check", "unchanged"),+ ("something-new", "updated"),+ ],+)+def test_report_actions_map_to_the_handle(+ monkeypatch: pytest.MonkeyPatch, raw_action: str, action: str+) -> None:+ report = {+ "sync": {+ "environment": {+ "path": "/env",+ "python": {"path": "/env/bin/python"},+ },+ "action": raw_action,+ }+ }++ class Completed:+ stdout = json.dumps(report)++ monkeypatch.setattr(environment, "ensure_supported_uv", lambda: None)+ monkeypatch.setattr(+ environment, "uv", lambda *_args, **_kwargs: Completed()+ )++ assert sync("nb.py").action == action+++def test_launch_without_overlay_is_direct() -> None:+ env = Environment(python="/env/bin/python", root="/env", action="created")++ plan = launch(env, ["-m", "marimo"], base_env={"PATH": "/usr/bin"})++ assert plan.argv == ("/env/bin/python", "-m", "marimo")+ assert plan.env["VIRTUAL_ENV"] == "/env"+ assert not plan.start_new_session+++def test_launcher_plans_start_a_new_session() -> None:+ env = Environment(python="/env/bin/python", root="/env", action="created")++ overlay = launch(env, ["-m", "marimo"], overlay=["marimo"])+ isolated = environment.launch_isolated(+ ["-m", "marimo"], overlay=["marimo"], python="3.13"+ )++ assert overlay.start_new_session+ assert isolated.start_new_session++[email protected](not SUPPORTS_SYNC, reason="uv >= 0.7.21 required")+def test_launch_overlay_chains_without_mutating(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ """Overlay packages import alongside manifest packages, and neither+ the script environment nor the manifest records them."""+ monkeypatch.setenv("UV_CACHE_DIR", str(tmp_path / "uv-cache"))+ pkg = tmp_path / "localpkg"+ (pkg / "localpkg").mkdir(parents=True)+ (pkg / "localpkg" / "__init__.py").write_text("value = 1\n")+ (pkg / "pyproject.toml").write_text(+ '[project]\nname = "localpkg"\nversion = "0.1.0"\n'+ )+ script = tmp_path / "nb.py"+ script.write_text(+ "# /// script\n"+ f'# requires-python = "{REQUIRES_PYTHON}"\n'+ '# dependencies = ["six"]\n'+ "# ///\n",+ encoding="utf-8",+ )++ env = sync(str(script), cwd=str(tmp_path))+ plan = launch(+ env,+ ["-c", "import six, idna, localpkg; print('chained')"],+ overlay=["idna", f"-e {pkg}"],+ )++ result = subprocess.run(+ list(plan.argv), env=plan.env, capture_output=True, text=True+ )+ assert result.returncode == 0, result.stderr+ assert "chained" in result.stdout+ # The script environment itself has only the manifest's packages.+ entries = _site_packages(env.root)+ assert any(entry.startswith("six") for entry in entries)+ assert not any(entry.startswith("idna") for entry in entries)+ assert "idna" not in script.read_text()++[email protected](not SUPPORTS_SYNC, reason="uv >= 0.7.21 required")+def test_sync_streams_progress(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ """With a callback, uv's progress streams line by line while the+ JSON report stays parseable."""+ monkeypatch.setenv("UV_CACHE_DIR", str(tmp_path / "uv-cache"))+ script = tmp_path / "nb.py"+ script.write_text(EMPTY_SCRIPT, encoding="utf-8")+ lines: list[str] = []++ env = sync(str(script), cwd=str(tmp_path), on_output=lines.append)++ assert env.action == "created"+ # Content wording is uv's, not ours; presence is the contract.+ assert lines, "expected streamed diagnostics"++[email protected]("editable", [False, True])[email protected]("features", [[], ["sql", "lsp"]])+def test_runtime_overlay_preserves_extras(+ monkeypatch: pytest.MonkeyPatch, editable: bool, features: list[str]+) -> None:+ from marimo._environments import overlay+ from marimo._version import __version__++ monkeypatch.setattr(overlay, "is_editable", lambda _: editable)+ extras = "[sql,lsp]" if features else ""+ expected = (+ f"-e {overlay.marimo_dir()}{extras}"+ if editable+ else f"marimo{extras}=={__version__}"+ )+ assert overlay.runtime_overlay(features, ["idna"]) == [expected, "idna"]diff --git a/tests/_environments/test_script_metadata.py b/tests/_environments/test_script_metadata.pyindex 0a074053e0..4166bb7cfd 100644--- a/tests/_environments/test_script_metadata.py+++ b/tests/_environments/test_script_metadata.py@@ -3,16 +3,14 @@ from __future__ import annotationsimport platformimport subprocess-from typing import TYPE_CHECKING+import sys+from pathlib import Pathimport pytestfrom marimo._environments import script_metadatafrom marimo._environments.uv import UvNotFoundError, is_uv_available-if TYPE_CHECKING:- from pathlib import Path-HAS_UV = is_uv_available()BLOCK_WITH_TOOL_TABLES = """\@@ -349,3 +347,159 @@ def test_edits_accept_relative_notebook_paths(project = script_metadata.loads((notebooks / "nb.py").read_text())assert project is not Noneassert project["dependencies"] == []+++def test_materialize_python_notebook_is_itself(tmp_path: Path) -> None:+ script = tmp_path / "nb.py"+ script.write_text("# /// script\n# dependencies = []\n# ///\n")++ with script_metadata.materialized_for_environment(+ str(script)+ ) as materialized:+ assert materialized.path == str(script)+ assert materialized.directory == str(tmp_path)+ assert script.exists()+++def test_materialize_markdown_carrier_is_adjacent_and_stable(+ tmp_path: Path,+) -> None:+ """The carrier sits next to the notebook under a versioned,+ deterministic name, carries the header verbatim, and is deleted on+ exit."""+ notebook = tmp_path / "notebook.md"+ notebook.write_text(+ """---+pyproject: |+ dependencies = []++ [tool.uv.sources]+ mylib = { path = "./lib" }+---++# Hello+"""+ )++ with script_metadata.materialized_for_environment(str(notebook)) as first:+ assert first.directory == str(tmp_path)+ carrier = Path(first.path)+ assert carrier.parent == tmp_path+ assert carrier.name == ".marimo-v1-notebook.md.py"+ # The header is verbatim: relative paths are uv's to anchor.+ assert 'path = "./lib"' in carrier.read_text()+ assert not carrier.exists()++ with script_metadata.materialized_for_environment(str(notebook)) as second:+ assert second.path == first.path+++def _enter_carrier(notebook, attempting, entered):+ attempting.set()+ with script_metadata.materialized_for_environment(notebook):+ entered.set()++[email protected]("separate_process", [False, True])+def test_stable_carrier_lifetime_is_serialized(+ tmp_path: Path, separate_process: bool+) -> None:+ import multiprocessing+ import threading++ notebook = tmp_path / "notebook.md"+ notebook.write_text("---\npyproject: |\n dependencies = []\n---\n")+ context = (+ multiprocessing.get_context("spawn") if separate_process else threading+ )+ attempting = context.Event()+ entered = context.Event()+ worker_type = context.Process if separate_process else threading.Thread+ worker = worker_type(+ target=_enter_carrier, args=(str(notebook), attempting, entered)+ )+ with script_metadata.materialized_for_environment(+ str(notebook)+ ) as materialized:+ worker.start()+ assert attempting.wait(timeout=10)+ assert not entered.wait(timeout=0.2)+ assert Path(materialized.path).exists()+ worker.join(timeout=10)+ assert not worker.is_alive()+ assert entered.is_set()+ assert not Path(materialized.path).exists()+++def test_old_active_carriers_are_preserved(tmp_path: Path) -> None:+ import os+ import time++ notebook = tmp_path / "notebook.md"+ notebook.write_text("---\npyproject: |\n dependencies = []\n---\n")+ with script_metadata.materialized_for_environment(+ str(notebook)+ ) as materialized:+ carrier = Path(materialized.path)+ old = time.time() - 3600+ os.utime(carrier, (old, old))+ with script_metadata._carrier(str(notebook), "# editing"):+ assert carrier.exists()+++def test_stranded_stable_carrier_is_reclaimed(tmp_path: Path) -> None:+ notebook = tmp_path / "notebook.md"+ notebook.write_text("---\npyproject: |\n dependencies = []\n---\n")+ stranded = tmp_path / ".marimo-v1-notebook.md.py"+ stranded.write_text("stranded")+ with script_metadata.materialized_for_environment(+ str(notebook)+ ) as materialized:+ assert "dependencies = []" in Path(materialized.path).read_text()+ assert not stranded.exists()++[email protected]("suffix", [".py", ".lock"])+def test_carrier_symlinks_do_not_modify_target(+ tmp_path: Path, suffix: str+) -> None:+ notebook = tmp_path / "notebook.md"+ notebook.write_text("---\npyproject: |\n dependencies = []\n---\n")+ target = tmp_path / "precious.txt"+ target.write_text("do not touch")+ link = tmp_path / f".marimo-v1-notebook.md{suffix}"+ try:+ link.symlink_to(target)+ except OSError:+ pytest.skip("symlinks unavailable")+ with pytest.raises(script_metadata.ScriptMetadataError, match="symlink"):+ with script_metadata.materialized_for_environment(str(notebook)):+ pytest.fail("must reject the symlink")+ assert target.read_text() == "do not touch"+++ sys.platform == "win32", reason="requires POSIX permissions"+)[email protected]("stable", [False, True])+def test_readonly_notebook_directory_fails_clearly(+ tmp_path: Path, stable: bool+) -> None:+ import os++ notebook = tmp_path / "notebook.md"+ notebook.write_text("---\npyproject: |\n dependencies = []\n---\n")+ carrier = (+ script_metadata.materialized_for_environment(str(notebook))+ if stable+ else script_metadata._carrier(str(notebook), "# edit")+ )+ os.chmod(tmp_path, 0o500)+ try:+ with pytest.raises(+ script_metadata.ScriptMetadataError, match="directory writable"+ ):+ with carrier:+ pytest.fail("must preserve adjacent path semantics")+ finally:+ os.chmod(tmp_path, 0o700)diff --git a/tests/_environments/test_uv.py b/tests/_environments/test_uv.pyindex fa5e7edc7f..062b7c5e92 100644--- a/tests/_environments/test_uv.py+++ b/tests/_environments/test_uv.py@@ -1,7 +1,8 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-from typing import TYPE_CHECKING+import sys+from typing import TYPE_CHECKING, Anyimport pytest@@ -106,3 +107,148 @@ def test_resolution_failure_is_refined(tmp_path: Path) -> None:# "No solution found when resolving dependencies".with pytest.raises(UvResolutionError):uv(["lock", "--offline", "--script", str(script)])++[email protected](not HAS_UV, reason="uv required")+def test_stream_survives_a_bufferless_stderr(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ """Kernels replace sys.stderr with a redirect whose `buffer` can be+ None; streaming must keep reaching the callback regardless."""++ class Redirect:+ buffer = None++ def __init__(self) -> None:+ self.text: list[str] = []++ def write(self, data: str) -> int:+ self.text.append(data)+ return len(data)++ from marimo._environments.uv import uv_stream++ redirect = Redirect()+ monkeypatch.setattr(sys, "stderr", redirect)+ script = tmp_path / "nb.py"+ script.write_text(+ "# /// script\n"+ '# dependencies = ["definitely-not-a-real-pkg-xyz==99.99"]\n'+ "# ///\n",+ encoding="utf-8",+ )+ lines: list[str] = []++ with pytest.raises(UvResolutionError):+ uv_stream(["lock", "--offline", "--script", str(script)], lines.append)++ assert lines, "expected streamed diagnostics"+ assert any("No solution found" in line for line in lines), lines+++def test_script_edits_ignore_an_active_virtualenv(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ """An enclosing VIRTUAL_ENV must not redirect script edits or leak+ mismatch warnings into their streamed output."""+ from unittest.mock import patch as mock_patch++ from marimo._environments import script_metadata++ monkeypatch.setenv("VIRTUAL_ENV", str(tmp_path / "unrelated-venv"))+ monkeypatch.setenv("UV_PROJECT_ENVIRONMENT", "/elsewhere")+ script = tmp_path / "nb.py"+ script.write_text(+ '# /// script\n# dependencies = ["numpy"]\n# ///\n',+ encoding="utf-8",+ )++ with mock_patch.object(script_metadata, "uv") as mock_uv:+ script_metadata.remove_dependencies(str(script), ["numpy"])+ env = mock_uv.call_args.kwargs["env"]+ assert "VIRTUAL_ENV" not in env+ assert "UV_PROJECT_ENVIRONMENT" not in env++ with mock_patch.object(script_metadata, "uv_stream") as mock_stream:+ script_metadata.add_dependencies(+ str(script), ["numpy"], on_output=lambda _line: None+ )+ env = mock_stream.call_args.kwargs["env"]+ assert "VIRTUAL_ENV" not in env+ assert "UV_PROJECT_ENVIRONMENT" not in env++[email protected](not HAS_UV, reason="uv required")+def test_stream_callback_runs_in_the_calling_thread(tmp_path: Path) -> None:+ """Kernel callbacks resolve their notification stream through+ thread-local state; the callback must run where the caller runs."""+ import threading++ from marimo._environments.uv import uv_stream++ local = threading.local()+ local.stream = "kernel"+ seen: list[str | None] = []++ def on_output(_line: str) -> None:+ seen.append(getattr(local, "stream", None))++ script = tmp_path / "nb.py"+ script.write_text(+ "# /// script\n"+ '# dependencies = ["definitely-not-a-real-pkg-xyz==99.99"]\n'+ "# ///\n",+ encoding="utf-8",+ )+ with pytest.raises(UvResolutionError):+ uv_stream(["lock", "--offline", "--script", str(script)], on_output)++ assert seen, "expected streamed lines"+ assert all(value == "kernel" for value in seen), seen+++def test_stream_preserves_missing_cwd(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path+) -> None:+ from marimo._environments.uv import uv_stream++ monkeypatch.setenv("UV", sys.executable)+ with pytest.raises(FileNotFoundError):+ uv_stream(+ ["-c", "pass"], lambda _: None, cwd=str(tmp_path / "missing")+ )+++def test_stream_interrupt_reaps_child_and_closes_pipes(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ import subprocess+ from unittest.mock import patch++ from marimo._environments.uv import uv_stream++ monkeypatch.setenv("UV", sys.executable)+ children = []+ popen = subprocess.Popen++ def launch(*args: Any, **kwargs: Any):+ child = popen(*args, **kwargs)+ children.append(child)+ return child++ def interrupt(_line):+ raise KeyboardInterrupt++ with patch("marimo._environments.uv.subprocess.Popen", side_effect=launch):+ with pytest.raises(KeyboardInterrupt):+ uv_stream(+ [+ "-c",+ "import sys,time; print('ready', file=sys.stderr, flush=True); time.sleep(30)",+ ],+ interrupt,+ )+ child = children[0]+ assert child.poll() is not None+ assert child.stdout.closed+ assert child.stderr.closeddiff --git a/tests/_runtime/packages/test_package_managers.py b/tests/_runtime/packages/test_package_managers.pyindex 15c56b4bb5..88e792c9da 100644--- a/tests/_runtime/packages/test_package_managers.py+++ b/tests/_runtime/packages/test_package_managers.py@@ -1,5 +1,6 @@from __future__ import annotations+import asyncioimport osimport sysfrom typing import Any@@ -755,3 +756,160 @@ def test_pixi_list_packages_uses_utf8_encoding(mock_run: MagicMock):call_kwargs = mock_run.call_args[1]assert call_kwargs.get("encoding") == "utf-8"assert call_kwargs.get("text") is True+++class TestUvScriptMode:+ """In script mode, package changes edit the manifest and synchronize+ its script environment, streaming uv's output."""++ def test_install_edits_and_syncs(self) -> None:+ from unittest.mock import patch++ pm = UvPackageManager(script_path="nb.py")+ logs: list[str] = []++ with (+ patch.object(script_metadata, "add_dependencies") as mock_add,+ patch(+ "marimo._environments.environment.sync_notebook"+ ) as mock_sync,+ ):+ success = asyncio.run(+ pm.install("foo bar", version=None, log_callback=logs.append)+ )++ assert success+ args, kwargs = mock_add.call_args+ assert args == ("nb.py", ["foo", "bar"])+ assert kwargs["on_output"] is not None+ mock_sync.assert_called_once()+ assert mock_sync.call_args.kwargs["on_output"] is not None++ def test_install_failure_streams_solver_message(self) -> None:+ from unittest.mock import patch++ from marimo._environments.uv import UvResolutionError++ pm = UvPackageManager(script_path="nb.py")+ logs: list[str] = []+ error = UvResolutionError(+ ["uv", "add"], 1, "", "No solution found when resolving"+ )++ with patch.object(+ script_metadata, "add_dependencies", side_effect=error+ ):+ success = asyncio.run(+ pm.install("foo", version=None, log_callback=logs.append)+ )++ assert not success+ assert any("No solution found" in line for line in logs)++ def test_uninstall_edits_and_syncs(self, tmp_path: Any) -> None:+ from unittest.mock import patch++ script = tmp_path / "nb.py"+ script.write_text(+ '# /// script\n# dependencies = ["foo"]\n# ///\n',+ encoding="utf-8",+ )+ pm = UvPackageManager(script_path=str(script))++ with (+ patch.object(script_metadata, "remove_dependencies") as mock_rm,+ patch(+ "marimo._environments.environment.sync_notebook"+ ) as mock_sync,+ ):+ success = asyncio.run(pm.uninstall("foo"))++ assert success+ assert mock_rm.call_args.args == (str(script), ["foo"])+ mock_sync.assert_called_once()++ def test_uninstall_reads_markdown_frontmatter(self, tmp_path: Any) -> None:+ from unittest.mock import patch++ notebook = tmp_path / "nb.md"+ notebook.write_text(+ '---\npyproject: |\n dependencies = ["foo"]\n---\n\n# Notebook\n',+ encoding="utf-8",+ )+ pm = UvPackageManager(script_path=str(notebook))++ with (+ patch.object(script_metadata, "remove_dependencies") as mock_rm,+ patch(+ "marimo._environments.environment.sync_notebook"+ ) as mock_sync,+ ):+ success = asyncio.run(pm.uninstall("foo"))++ assert success+ assert mock_rm.call_args.args == (str(notebook), ["foo"])+ mock_sync.assert_called_once()++ def test_uninstall_rejects_undeclared_packages(+ self, tmp_path: Any+ ) -> None:+ """A transitive dependency is not the notebook's to remove."""+ from unittest.mock import patch++ script = tmp_path / "nb.py"+ script.write_text(+ '# /// script\n# dependencies = ["foo"]\n# ///\n',+ encoding="utf-8",+ )+ pm = UvPackageManager(script_path=str(script))++ with patch.object(script_metadata, "remove_dependencies") as mock_rm:+ success = asyncio.run(pm.uninstall("transitive-dep"))++ assert not success+ mock_rm.assert_not_called()++ def test_metadata_update_skips_explicit_packages(+ self, uv_calls: list[list[str]]+ ) -> None:+ """install/uninstall own explicit packages; only namespace changes+ from cell registration reach the metadata writer."""++ class MockUvPackageManager(UvPackageManager):+ def _get_version_map(self) -> VersionMap:+ return VersionMap({"pyyaml": "1.0"})++ pm = MockUvPackageManager(script_path="nb.py")++ pm.update_notebook_script_metadata(+ filepath="nb.py",+ packages_to_add=["already-handled"],+ import_namespaces_to_add=["yaml"],+ upgrade=False,+ )++ assert uv_calls == [+ ["uv", "--quiet", "add", "--script", NB_ABSPATH, "pyyaml==1.0"],+ ]++ def test_metadata_update_does_not_pin_declared_dependency(+ self, tmp_path: Any, uv_calls: list[list[str]]+ ) -> None:+ notebook = tmp_path / "nb.py"+ notebook.write_text(+ '# /// script\n# dependencies = ["pyyaml"]\n# ///\n',+ encoding="utf-8",+ )++ class MockUvPackageManager(UvPackageManager):+ def _get_version_map(self) -> VersionMap:+ raise AssertionError("declared dependencies need no lookup")++ pm = MockUvPackageManager(script_path=str(notebook))++ assert pm.update_notebook_script_metadata(+ filepath=str(notebook),+ import_namespaces_to_add=["yaml"],+ upgrade=False,+ )+ assert uv_calls == []diff --git a/tests/_runtime/packages/test_pypi_package_manager.py b/tests/_runtime/packages/test_pypi_package_manager.pyindex 050d9b1411..fc55d00908 100644--- a/tests/_runtime/packages/test_pypi_package_manager.py+++ b/tests/_runtime/packages/test_pypi_package_manager.py@@ -11,6 +11,8 @@ from pathlib import Pathfrom typing import Anyfrom unittest.mock import MagicMock, patch+import pytest+from marimo._ast import compilerfrom marimo._runtime.packages.package_manager import PackageDescriptionfrom marimo._runtime.packages.pypi_package_manager import (@@ -844,6 +846,40 @@ def test_uv_dependency_tree_uses_utf8_encoding(mock_run: MagicMock):assert call_kwargs.get("text") is True+@patch("subprocess.run")+def test_uv_dependency_tree_materializes_markdown(+ mock_run: MagicMock, tmp_path: Path+) -> None:+ notebook = tmp_path / "notebook.md"+ notebook.write_text(+ "---\n"+ "pyproject: |\n"+ ' dependencies = ["test-package"]\n'+ "---\n\n"+ "# Notebook\n",+ encoding="utf-8",+ )++ def run(command: list[str], **kwargs: Any) -> MagicMock:+ carrier = Path(command[-1])+ assert carrier.name == ".marimo-v1-notebook.md.py"+ assert 'dependencies = ["test-package"]' in carrier.read_text()+ assert kwargs["cwd"] == str(tmp_path)+ return MagicMock(+ args=command,+ returncode=0,+ stdout="test-package v1.0.0\n",+ stderr="",+ )++ mock_run.side_effect = run++ tree = UvPackageManager().dependency_tree(filename=str(notebook))++ assert tree is not None+ assert not (tmp_path / ".marimo-v1-notebook.md.py").exists()++@patch("subprocess.run")def test_uv_pip_list_uses_utf8_encoding(mock_run: MagicMock):"""Test that uv pip list uses UTF-8 encoding"""@@ -1240,3 +1276,35 @@ class TestVersionMap:# Test beautifulsoup4 (number in name)assert version_map.get_version("beautifulsoup4") == "4.12.0"assert version_map.has("beautifulsoup4") is True+++ "requirement",+ ["my_pkg[extra]", "my-pkg>=1", "my-pkg @ https://example.org/pkg.whl"],+)+async def test_script_uninstall_matches_distribution_name(+ tmp_path: Path, requirement: str+) -> None:+ notebook = tmp_path / "notebook.py"+ notebook.write_text(+ '# /// script\n# dependencies = ["my-pkg[extra]>=1"]\n# ///\n'+ )+ manager = UvPackageManager(script_path=str(notebook))+ with patch.object(+ manager, "_change_script_environment", return_value=True+ ) as change:+ assert await manager.uninstall(requirement)+ change.assert_called_once_with(str(notebook), remove=["my-pkg"])+++async def test_script_uninstall_preserves_transitive_dependency(+ tmp_path: Path,+) -> None:+ notebook = tmp_path / "notebook.py"+ notebook.write_text('# /// script\n# dependencies = ["parent"]\n# ///\n')+ manager = UvPackageManager(script_path=str(notebook))+ with patch.object(manager, "_change_script_environment") as change:+ assert not await manager.uninstall("transitive")+ change.assert_not_called()diff --git a/tests/_runtime/test_manage_script_metadata.py b/tests/_runtime/test_manage_script_metadata.pyindex d487ebc392..5a6f331661 100644--- a/tests/_runtime/test_manage_script_metadata.py+++ b/tests/_runtime/test_manage_script_metadata.py@@ -812,3 +812,49 @@ async def test_install_missing_packages_no_logs_backward_compatibility(# Should have at least installing and installed statusesassert "installed" in package_statuses# Note: The exact sequence might vary, but we should have final success+++async def test_install_logs_reach_the_stream_from_worker_threads(+ mocked_kernel: MockedKernel,+) -> None:+ """Per-line install logs bind the kernel's stream when the callback+ is created: the callback fires from worker threads, which do not+ carry the kernel's thread-local context, so a bare broadcast there+ is silently dropped."""+ import threading++ k = mocked_kernel.k+ current = k.packages_callbacks.package_manager+ assert current is not None++ fake = Mock()+ fake.name = current.name+ fake.is_manager_installed.return_value = True+ fake.attempted_to_install.return_value = False+ fake.module_to_package.side_effect = lambda module: module+ fake.package_to_module.side_effect = lambda package: package++ async def install(+ package: str,+ version: str | None = None,+ log_callback: Any = None,+ **kwargs: Any,+ ) -> bool:+ del package, version, kwargs+ worker = threading.Thread(+ target=log_callback, args=("streamed-from-a-bare-thread\n",)+ )+ worker.start()+ worker.join()+ return True++ fake.install = install+ fake.stream_install = _make_stream_install(fake)+ k.packages_callbacks.package_manager = fake++ await k.packages_callbacks.install_missing_packages(+ InstallPackagesCommand(manager=fake.name, versions={"foobar": ""})+ )++ joined = "".join(str(message) for message in mocked_kernel.stream.messages)+ assert "streamed-from-a-bare-thread" in joineddiff --git a/tests/_server/api/endpoints/test_packages.py b/tests/_server/api/endpoints/test_packages.pyindex 6f1aec110d..07f421efa4 100644--- a/tests/_server/api/endpoints/test_packages.py+++ b/tests/_server/api/endpoints/test_packages.py@@ -719,6 +719,8 @@ def test_get_package_manager_uses_ipc_venv_python() -> None:mock_kernel_manager = MagicMock()mock_kernel_manager.venv_python = "/custom/venv/python"+ mock_kernel_manager.script_environment = None+mock_session = MagicMock()mock_session._kernel_manager = mock_kernel_manager@@ -755,7 +757,46 @@ def test_get_package_manager_uses_ipc_venv_python() -> None:# Verify create_package_manager was called with python_exemock_create_pm.assert_called_once_with(- "pip", python_exe="/custom/venv/python"+ "pip", python_exe="/custom/venv/python", script_path=None+ )+++def test_get_package_manager_with_script_environment() -> None:+ """A kernel synchronized into a script environment routes package+ changes through it."""+ from marimo._server.api.endpoints.packages import _get_package_manager++ mock_kernel_manager = MagicMock()+ mock_kernel_manager.venv_python = "/env/bin/python"+ mock_kernel_manager.script_environment = object()++ mock_session = MagicMock()+ mock_session._kernel_manager = mock_kernel_manager+ mock_session.app_file_manager.filename = "/nb/notebook.py"++ mock_app_state = MagicMock()+ mock_app_state.get_current_session.return_value = mock_session+ mock_app_state.app_config_manager.package_manager = "uv"++ with (+ patch(+ "marimo._server.api.endpoints.packages.AppState",+ return_value=mock_app_state,+ ),+ patch(+ "marimo._server.api.endpoints.packages.create_package_manager"+ ) as mock_create_pm,+ patch(+ "marimo._server.api.endpoints.packages.isinstance",+ side_effect=lambda _obj, _cls: True,+ ),+ ):+ _get_package_manager(MagicMock())++ mock_create_pm.assert_called_once_with(+ "uv",+ python_exe="/env/bin/python",+ script_path="/nb/notebook.py",)@@ -788,7 +829,9 @@ def test_get_package_manager_without_ipc_session() -> None:_get_package_manager(mock_request)# Verify create_package_manager was called with python_exe=None- mock_create_pm.assert_called_once_with("uv", python_exe=None)+ mock_create_pm.assert_called_once_with(+ "uv", python_exe=None, script_path=None+ )def test_get_package_manager_no_session() -> None:@@ -815,3 +858,35 @@ def test_get_package_manager_no_session() -> None:# Verify create_package_manager was called without python_exemock_create_pm.assert_called_once_with("pip")++[email protected]("mode", ["single", None])+def test_package_manager_binding_for_inprocess_kernel(+ monkeypatch: pytest.MonkeyPatch, mode: str | None+) -> None:+ from marimo._config.settings import GLOBAL_SETTINGS+ from marimo._server.api.endpoints.packages import _get_package_manager+ from marimo._session.session import SessionImpl++ monkeypatch.setattr(GLOBAL_SETTINGS, "SANDBOX_MODE", mode)+ session = MagicMock(spec=SessionImpl)+ session._kernel_manager = MagicMock(spec=[])+ session.app_file_manager = MagicMock(filename="/nb/notebook.py")+ state = MagicMock()+ state.get_current_session.return_value = session+ state.app_config_manager.package_manager = "uv"+ with (+ patch(+ "marimo._server.api.endpoints.packages.AppState",+ return_value=state,+ ),+ patch(+ "marimo._server.api.endpoints.packages.create_package_manager"+ ) as create,+ ):+ _get_package_manager(MagicMock())+ create.assert_called_once_with(+ "uv",+ python_exe=None,+ script_path="/nb/notebook.py" if mode == "single" else None,+ )diff --git a/tests/_session/app_host/test_app_host.py b/tests/_session/app_host/test_app_host.pyindex 345385878b..a47594764e 100644--- a/tests/_session/app_host/test_app_host.py+++ b/tests/_session/app_host/test_app_host.py@@ -64,100 +64,21 @@ class TestAppHostCommands:@pytest.mark.requires("zmq")class TestAppHostOnEmpty:- def test_on_empty_fires_when_session_ids_becomes_empty(self) -> None:- """on_empty callback fires when all sessions exit."""+ def test_cleanup_fires_once_after_last_session_exits(self) -> None:import threadingfrom marimo._session.app_host.host import AppHostfired = threading.Event()-- def on_empty() -> None:- fired.set()-- app_host = AppHost("/tmp/test_app.py", on_empty=on_empty)- # Simulate a kernel being alive- app_host._session_ids.add("s1")-- # Simulate receiving a KernelExited message by calling- # discard + the callback logic directly (avoids needing- # a real subprocess with ZMQ sockets).- app_host._session_ids.discard("s1")- assert len(app_host._session_ids) == 0- # Replicate the callback logic from _stream_receiver_loop- callback = app_host._on_empty- app_host._on_empty = None- if callback is not None:- threading.Thread(target=callback, daemon=True).start()-- assert fired.wait(timeout=2), "on_empty callback was not fired"-- def test_on_empty_does_not_fire_when_kernels_remain(self) -> None:- """on_empty callback does NOT fire when kernels remain."""- import threading-- from marimo._session.app_host.host import AppHost-- fired = threading.Event()-- def on_empty() -> None:- fired.set()-- app_host = AppHost("/tmp/test_app.py", on_empty=on_empty)- app_host._session_ids.add("s1")- app_host._session_ids.add("s2")-- # Remove one — still one left- app_host._session_ids.discard("s1")- assert len(app_host._session_ids) == 1-- # Replicate the callback logic- if not app_host._session_ids:- callback = app_host._on_empty- app_host._on_empty = None- if callback is not None:- threading.Thread(target=callback, daemon=True).start()-- assert not fired.wait(timeout=0.5), (- "on_empty callback should not fire when kernels remain"- )-- def test_on_empty_fires_only_once(self) -> None:- """on_empty callback fires at most once (double-fire prevention)."""- import threading-- from marimo._session.app_host.host import AppHost-- call_count = 0- lock = threading.Lock()- done = threading.Event()-- def on_empty() -> None:- nonlocal call_count- with lock:- call_count += 1- done.set()-- app_host = AppHost("/tmp/test_app.py", on_empty=on_empty)- app_host._session_ids.add("s1")- app_host._session_ids.add("s2")-- # Simulate both kernels exiting- for sid in ["s1", "s2"]:- app_host._session_ids.discard(sid)- if not app_host._session_ids:- callback = app_host._on_empty- app_host._on_empty = None- if callback is not None:- threading.Thread(target=callback, daemon=True).start()-- assert done.wait(timeout=2)- # Give any potential second callback time to run- threading.Event().wait(timeout=0.2)- with lock:- assert call_count == 1, (- f"on_empty fired {call_count} times, expected 1"- )+ host = AppHost("/tmp/test_app.py", on_empty=fired.set)+ host._session_ids.update(("first", "second"))+ host._session_ids.remove("first")+ assert not host._fire_on_empty()+ assert not fired.is_set()+ host._session_ids.remove("second")+ assert host._fire_on_empty()+ assert fired.wait(timeout=5)+ assert not host._fire_on_empty()@pytest.mark.requires("zmq")@@ -234,72 +155,30 @@ class TestAppHost:@pytest.mark.requires("zmq")class TestAppHostSandbox:- def test_app_host_stores_sandbox_dir(self) -> None:- """AppHost stores sandbox_dir for cleanup on shutdown."""- from marimo._session.app_host.host import AppHost-- host = AppHost("/tmp/test.py", sandbox_dir="/tmp/sandbox-abc")- assert host._sandbox_dir == "/tmp/sandbox-abc"-- def test_app_host_shutdown_cleans_up_sandbox_dir(self) -> None:- """shutdown() calls cleanup_sandbox_dir when sandbox_dir is set."""- from unittest.mock import patch-- from marimo._session.app_host.host import AppHost-- host = AppHost("/tmp/test.py", sandbox_dir="/tmp/sandbox-abc")-- with patch("marimo._cli.sandbox.cleanup_sandbox_dir") as mock_cleanup:- host.shutdown()- mock_cleanup.assert_called_once_with("/tmp/sandbox-abc")-- assert host._sandbox_dir is None-- def test_app_host_shutdown_skips_cleanup_without_sandbox(self) -> None:- """shutdown() does not call cleanup when no sandbox_dir."""- from unittest.mock import patch-- from marimo._session.app_host.host import AppHost-- host = AppHost("/tmp/test.py")-- with patch("marimo._cli.sandbox.cleanup_sandbox_dir") as mock_cleanup:- host.shutdown()- mock_cleanup.assert_not_called()-- def test_pool_sandbox_flag_stored(self) -> None:- """AppHostPool stores the sandbox flag."""- from marimo._session.app_host.pool import AppHostPool-- pool = AppHostPool(sandbox=False)- assert pool._sandbox is False-- pool = AppHostPool(sandbox=True)- assert pool._sandbox is True-- def test_pool_sandbox_builds_venv_and_passes_to_host(self) -> None:- """When sandbox=True, pool builds a venv and passes python/sandbox_dir- to AppHost."""+ def test_pool_sandbox_syncs_and_passes_plan(self) -> None:+ """When sandbox=True, the pool synchronizes the notebook's script+ environment and hands AppHost a launch plan for it."""from unittest.mock import MagicMock, patch+ from marimo._environments.environment import Environmentfrom marimo._session.app_host.pool import AppHostPoolpool = AppHostPool(sandbox=True)mock_host = MagicMock()mock_host.is_alive.return_value = True+ handle = Environment(+ python="/env/bin/python", root="/env", action="created"+ )with (patch(- "marimo._session.app_host.pool.build_sandbox_venv",- return_value=(- "/tmp/sandbox-xyz",- "/tmp/sandbox-xyz/bin/python",- ),- ) as mock_build,+ "marimo._session.app_host.pool.sync_notebook",+ return_value=handle,+ ) as mock_sync,patch(- "marimo._session.app_host.pool.get_ipc_kernel_deps",- return_value=["pyzmq==26.0.0"],+ "marimo._session.app_host.pool.runtime_overlay",+ return_value=["kernel-dep==1.0"],),patch("marimo._session.app_host.pool.AppHost",@@ -308,19 +187,19 @@ class TestAppHostSandbox:):pool.get_or_create("/tmp/test_app.py")- # Verify venv was built with correct args- mock_build.assert_called_once()- _, kwargs = mock_build.call_args- assert kwargs["additional_deps"] == ["pyzmq==26.0.0"]-- # Verify AppHost received python and sandbox_dir- mock_host_cls.assert_called_once()- host_kwargs = mock_host_cls.call_args[1]- assert host_kwargs["python"] == "/tmp/sandbox-xyz/bin/python"- assert host_kwargs["sandbox_dir"] == "/tmp/sandbox-xyz"-- def test_pool_no_sandbox_skips_venv_build(self) -> None:- """When sandbox=False, pool does not build a venv."""+ mock_sync.assert_called_once()+ plan = mock_host_cls.call_args[1]["plan"]+ # The marimo runtime rides the launch overlay.+ assert "kernel-dep==1.0" in plan.argv+ assert plan.argv[-3:] == (+ "--",+ "python",+ "-m",+ ) or plan.argv[-2:] == ("-m", "marimo._session.app_host.main")+ assert plan.env["VIRTUAL_ENV"] == "/env"++ def test_pool_no_sandbox_skips_sync(self) -> None:+ """When sandbox=False, the pool does not synchronize anything."""from unittest.mock import MagicMock, patchfrom marimo._session.app_host.pool import AppHostPool@@ -332,8 +211,8 @@ class TestAppHostSandbox:with (patch(- "marimo._session.app_host.pool.build_sandbox_venv",- ) as mock_build,+ "marimo._session.app_host.pool.sync_notebook",+ ) as mock_sync,patch("marimo._session.app_host.pool.AppHost",return_value=mock_host,@@ -341,56 +220,42 @@ class TestAppHostSandbox:):pool.get_or_create("/tmp/test_app.py")- mock_build.assert_not_called()-- # AppHost should get python=None, sandbox_dir=None- host_kwargs = mock_host_cls.call_args[1]- assert host_kwargs.get("python") is None- assert host_kwargs.get("sandbox_dir") is None+ mock_sync.assert_not_called()+ assert mock_host_cls.call_args[1].get("plan") is None- def test_pool_sandbox_race_cleans_up_duplicate_venv(self) -> None:- """If another thread creates the host while we build the venv,- the duplicate venv is cleaned up."""+ def test_pool_missing_metadata_runs_ephemerally(self) -> None:+ """A notebook without a metadata block launches isolated."""from unittest.mock import MagicMock, patch+ from marimo._environments.uv import UvMissingScriptMetadataErrorfrom marimo._session.app_host.pool import AppHostPoolpool = AppHostPool(sandbox=True)- # Pre-populate pool with an alive host (simulates another thread)- existing_host = MagicMock()- existing_host.is_alive.return_value = True-- # Simulate the race: first get_or_create finds no host, drops- # the lock to build the venv, then re-acquires and finds a host- # that another thread created. We do this by injecting the host- # into pool._workers during the build_sandbox_venv call.- def build_and_inject(- filename: str,- additional_deps: list[str] | None = None, # noqa: ARG001- ) -> tuple[str, str]:- import os-- abs_path = os.path.abspath(filename)- pool._workers[abs_path] = existing_host- return ("/tmp/sandbox-dup", "/tmp/sandbox-dup/bin/python")+ mock_host = MagicMock()+ mock_host.is_alive.return_value = Truewith (patch(- "marimo._session.app_host.pool.build_sandbox_venv",- side_effect=build_and_inject,+ "marimo._session.app_host.pool.sync_notebook",+ side_effect=UvMissingScriptMetadataError(+ ["uv"], 2, "", "no PEP 723 metadata"+ ),),patch(- "marimo._session.app_host.pool.get_ipc_kernel_deps",- return_value=[],+ "marimo._session.app_host.pool.runtime_overlay",+ return_value=["marimo==0.0.0"],),patch(- "marimo._session.app_host.pool.cleanup_sandbox_dir",- ) as mock_cleanup,+ "marimo._session.app_host.pool.AppHost",+ return_value=mock_host,+ ) as mock_host_cls,):- result = pool.get_or_create("/tmp/test_app.py")- assert result is existing_host- mock_cleanup.assert_called_once_with("/tmp/sandbox-dup")+ pool.get_or_create("/tmp/test_app.py")++ plan = mock_host_cls.call_args[1]["plan"]+ assert "--isolated" in plan.argv+ assert "marimo==0.0.0" in plan.argv@pytest.mark.requires("zmq")diff --git a/tests/_session/app_host/test_pool.py b/tests/_session/app_host/test_pool.pyindex d997ed30ff..e5c02b8adc 100644--- a/tests/_session/app_host/test_pool.py+++ b/tests/_session/app_host/test_pool.py@@ -12,7 +12,7 @@ from marimo._session.app_host.pool import AppHostPool@pytest.mark.requires("zmq")class TestAppHostPoolRespawnDead:def test_respawns_dead_host(self) -> None:- """_create_locked shuts down dead host and creates a new one."""+ """A dead host is shut down before its replacement is returned."""pool = AppHostPool(sandbox=False)dead_host = MagicMock()@@ -33,3 +33,148 @@ class TestAppHostPoolRespawnDead:dead_host.shutdown.assert_called_once()assert result is new_hostassert pool._workers[abs_path] is new_host+++def test_startup_does_not_block_other_notebooks_or_duplicate_hosts() -> None:+ import threading+ from concurrent.futures import ThreadPoolExecutor, TimeoutError++ entered = threading.Event()+ release = threading.Event()+ slow = MagicMock()+ fast = MagicMock()+ pool = AppHostPool()++ def start():+ entered.set()+ assert release.wait(timeout=10)++ slow.start.side_effect = start+ with patch(+ "marimo._session.app_host.pool.AppHost", side_effect=[slow, fast]+ ) as create:+ with ThreadPoolExecutor(max_workers=3) as executor:+ first = executor.submit(pool.get_or_create, "slow.py")+ try:+ assert entered.wait(timeout=5)+ same = executor.submit(pool.get_or_create, "slow.py")+ other = executor.submit(pool.get_or_create, "fast.py")+ assert other.result(timeout=5) is fast+ with pytest.raises(TimeoutError):+ same.result(timeout=0.1)+ finally:+ release.set()+ assert first.result(timeout=5) is slow+ assert same.result(timeout=5) is slow+ assert create.call_count == 2+ pool.shutdown()+++def test_shutdown_during_startup_does_not_publish_host() -> None:+ import threading+ from concurrent.futures import ThreadPoolExecutor++ from marimo._session.managers.ipc import KernelStartupError++ entered = threading.Event()+ release = threading.Event()+ host = MagicMock()+ pool = AppHostPool()++ def start():+ entered.set()+ assert release.wait(timeout=10)++ host.start.side_effect = start+ with patch("marimo._session.app_host.pool.AppHost", return_value=host):+ with ThreadPoolExecutor() as executor:+ pending = executor.submit(pool.get_or_create, "nb.py")+ try:+ assert entered.wait(timeout=5)+ pool.shutdown()+ with pytest.raises(KernelStartupError, match="shut down"):+ pool.get_or_create("nb.py")+ finally:+ release.set()+ with pytest.raises(KernelStartupError, match="shut down"):+ pending.result(timeout=5)+ host.shutdown.assert_called_once()+ assert not pool._workers+++def test_failed_startup_is_cleaned_up_and_can_be_retried() -> None:+ failed = MagicMock()+ failed.start.side_effect = RuntimeError("startup failed")+ replacement = MagicMock()+ pool = AppHostPool()+ with patch(+ "marimo._session.app_host.pool.AppHost",+ side_effect=[failed, replacement],+ ):+ with pytest.raises(RuntimeError, match="startup failed"):+ pool.get_or_create("nb.py")+ assert pool.get_or_create("nb.py") is replacement+ failed.shutdown.assert_called_once()+ pool.shutdown()+++def test_old_host_callback_does_not_remove_replacement() -> None:+ callbacks = []++ def create(_path, *, plan, on_empty):+ del plan+ host = MagicMock()+ callbacks.append(on_empty)+ return host++ pool = AppHostPool()+ with patch("marimo._session.app_host.pool.AppHost", side_effect=create):+ first = pool.get_or_create("nb.py")+ first.is_alive.return_value = False+ replacement = pool.get_or_create("nb.py")+ callbacks[0]()+ assert pool.get_or_create("nb.py") is replacement+ replacement.shutdown.assert_not_called()+ pool.shutdown()+++def test_manifestless_host_clears_inherited_sandbox_identity(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ from marimo._environments.uv import UvMissingScriptMetadataError++ monkeypatch.setenv("MARIMO_SANDBOX_MODE", "multi")+ pool = AppHostPool(sandbox=True)+ with (+ patch(+ "marimo._session.app_host.pool.sync_notebook",+ side_effect=UvMissingScriptMetadataError(["uv"], 1, "", "missing"),+ ),+ patch(+ "marimo._session.app_host.pool.runtime_overlay", return_value=[]+ ),+ patch("marimo._session.app_host.pool.AppHost") as create,+ ):+ pool.get_or_create("nb.py")+ plan = create.call_args.kwargs["plan"]+ assert "MARIMO_SANDBOX_MODE" not in plan.env+ assert plan.env["MARIMO_MANAGE_SCRIPT_METADATA"] == "true"+ assert os.environ["MARIMO_SANDBOX_MODE"] == "multi"+ pool.shutdown()+++def test_environment_failure_is_reported_without_fallback() -> None:+ from marimo._environments.uv import UvError+ from marimo._session.managers.ipc import KernelStartupError++ pool = AppHostPool(sandbox=True)+ with (+ patch(+ "marimo._session.app_host.pool.sync_notebook",+ side_effect=UvError("solver diagnostic"),+ ),+ patch("marimo._session.app_host.pool.launch_isolated") as fallback,+ ):+ with pytest.raises(KernelStartupError, match="solver diagnostic"):+ pool.get_or_create("nb.py")+ fallback.assert_not_called()diff --git a/tests/_session/managers/test_ipc.py b/tests/_session/managers/test_ipc.pyindex 07ef5672fe..f3d733f0ca 100644--- a/tests/_session/managers/test_ipc.py+++ b/tests/_session/managers/test_ipc.py@@ -74,39 +74,6 @@ class TestIPCKernelManagerImpl:# venv_python should be None before kernel startsassert kernel_manager.venv_python is None- def test_venv_python_property_returns_stored_value(self) -> None:- """Test that venv_python property returns the stored _venv_python value."""- from unittest.mock import MagicMock-- from marimo._session.managers.ipc import (- IPCKernelManagerImpl,- IPCQueueManagerImpl,- )- from marimo._session.model import SessionMode-- # Create minimal mocks for construction- mock_ipc = MagicMock()- queue_manager = IPCQueueManagerImpl(mock_ipc)- connection_info = MagicMock()- configs: dict = {}- app_metadata = MagicMock()- config_manager = MagicMock()-- kernel_manager = IPCKernelManagerImpl(- queue_manager=queue_manager,- connection_info=connection_info,- mode=SessionMode.EDIT,- configs=configs,- app_metadata=app_metadata,- config_manager=config_manager,- )-- # Manually set the internal state (simulating what start_kernel does)- kernel_manager._venv_python = "/path/to/sandbox/venv/python"-- # venv_python property should return the stored value- assert kernel_manager.venv_python == "/path/to/sandbox/venv/python"-class TestSubprocessWrapper:def test_exitcode_uses_popen_returncode(self) -> None:@@ -145,24 +112,6 @@ class TestIPCQueueManagerImpl:# Clean upwrapper.close_queues()- def test_from_ipc_equals_direct_init(self) -> None:- """Test that from_ipc() and __init__() produce equivalent results."""- from marimo._ipc import QueueManager as IPCQueueManager- from marimo._session.managers.ipc import IPCQueueManagerImpl-- ipc_queue_manager, _ = IPCQueueManager.create()-- # Create using factory- via_factory = IPCQueueManagerImpl.from_ipc(ipc_queue_manager)- # Create using __init__ directly- via_init = IPCQueueManagerImpl(ipc_queue_manager)-- # Both should reference the same underlying IPC manager- assert via_factory._ipc is via_init._ipc-- # Clean up- via_factory.close_queues()-class TestConstructKernelEnv:"""Tests for construct_kernel_env, the pure-function that builds the@@ -198,6 +147,22 @@ class TestConstructKernelEnv:# Ephemeral sandboxes are always writable.assert env["MARIMO_MANAGE_SCRIPT_METADATA"] == "true"+ def test_inherited_sandbox_identity_is_stripped(self) -> None:+ """A configured-venv kernel inside a sandboxed server must not+ inherit script routing from the server's environment."""+ env = construct_kernel_env(+ base_env={+ **self.BASE_ENV,+ "MARIMO_SANDBOX_MODE": "multi",+ "MARIMO_MANAGE_SCRIPT_METADATA": "true",+ },+ venv_python=self.CONFIGURED_PYTHON,+ is_ephemeral_sandbox=False,+ writable=False,+ )+ assert "MARIMO_SANDBOX_MODE" not in env+ assert "MARIMO_MANAGE_SCRIPT_METADATA" not in env+# -- configured venvs --------------------------------------------------def test_configured_readonly_venv_with_pythonpath(self) -> None:@@ -244,3 +209,299 @@ class TestConstructKernelEnv:)assert "UV_PROJECT_ENVIRONMENT" in baseassert "VIRTUAL_ENV" not in base+++class TestVirtualFileStorage:+ @staticmethod+ def _kernel_args(**overrides: object) -> object:+ from marimo._ast.app_config import _AppConfig+ from marimo._config.config import DEFAULT_CONFIG+ from marimo._ipc.types import ConnectionInfo, KernelArgs+ from marimo._runtime.commands import AppMetadata++ kwargs: dict = {+ "configs": {},+ "app_metadata": AppMetadata(+ query_params={}, cli_args={}, app_config=_AppConfig()+ ),+ "user_config": DEFAULT_CONFIG,+ "log_level": 0,+ "profile_path": None,+ "connection_info": ConnectionInfo(+ control=1,+ ui_element=2,+ completion=3,+ win32_interrupt=None,+ input=4,+ stream=5,+ ),+ }+ kwargs.update(overrides)+ return KernelArgs(**kwargs)++ def test_kernel_args_roundtrip(self) -> None:+ from marimo._ipc.types import KernelArgs++ args = self._kernel_args(virtual_file_storage="shared_memory")+ decoded = KernelArgs.decode_json(args.encode_json())+ assert decoded.virtual_file_storage == "shared_memory"++ def test_payload_without_field_decodes_to_none(self) -> None:+ """A payload from an older launcher lacks the field entirely."""+ import json++ from marimo._ipc.types import KernelArgs++ payload = json.loads(self._kernel_args().encode_json())+ payload.pop("virtual_file_storage")+ decoded = KernelArgs.decode_json(json.dumps(payload).encode())+ assert decoded.virtual_file_storage is None++ def test_manager_requests_shared_memory_when_available(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ from marimo._session.managers.ipc import _virtual_file_storage+ from marimo._utils import platform++ monkeypatch.setattr(+ platform, "check_shared_memory_available", lambda: (True, "")+ )+ assert _virtual_file_storage() == "shared_memory"++ def test_manager_falls_back_to_none_without_shm(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ from marimo._session.managers.ipc import _virtual_file_storage+ from marimo._utils import platform++ monkeypatch.setattr(+ platform,+ "check_shared_memory_available",+ lambda: (False, "/dev/shm unavailable"),+ )+ assert _virtual_file_storage() is None+++def _make_manager(filename: str | None = None) -> object:+ from unittest.mock import MagicMock++ from marimo._session.managers.ipc import (+ IPCKernelManagerImpl,+ IPCQueueManagerImpl,+ )+ from marimo._session.model import SessionMode++ app_metadata = MagicMock()+ app_metadata.filename = filename+ return IPCKernelManagerImpl(+ queue_manager=IPCQueueManagerImpl(MagicMock()),+ connection_info=MagicMock(),+ mode=SessionMode.EDIT,+ configs={},+ app_metadata=app_metadata,+ config_manager=MagicMock(),+ )+++class TestProfilePath:+ def test_none_without_profile_dir(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ from marimo._config.settings import GLOBAL_SETTINGS++ monkeypatch.setattr(GLOBAL_SETTINGS, "PROFILE_DIR", None)+ assert _make_manager("nb.py").profile_path is None++ def test_derived_from_profile_dir_and_filename(+ self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path+ ) -> None:+ from marimo._config.settings import GLOBAL_SETTINGS++ monkeypatch.setattr(GLOBAL_SETTINGS, "PROFILE_DIR", str(tmp_path))+ path = _make_manager("/some/dir/nb.py").profile_path+ assert path is not None+ assert path.startswith(str(tmp_path))+ assert "nb.py" in os.path.basename(path)+++class TestCloseKernel:+ @pytest.fixture(autouse=True)+ def _disable_profiling(self, monkeypatch: pytest.MonkeyPatch) -> None:+ from marimo._config.settings import GLOBAL_SETTINGS++ monkeypatch.setattr(GLOBAL_SETTINGS, "PROFILE_DIR", None)++ def _closable_manager(self) -> object:+ from unittest.mock import MagicMock++ manager = _make_manager("nb.py")+ manager.queue_manager = MagicMock()+ process = MagicMock()+ process.poll.return_value = None+ manager._process = process+ manager.kernel_task = None+ return manager++ def test_graceful_waits_bounded_for_exit(self) -> None:+ from marimo._runtime import commands+ from marimo._session.managers.ipc import GRACEFUL_EXIT_TIMEOUT++ manager = self._closable_manager()+ manager.close_kernel(graceful=True)++ (request,), _ = manager.queue_manager.put_control_request.call_args+ assert isinstance(request, commands.StopKernelCommand)+ manager.queue_manager.close_queues.assert_called_once()+ manager._process.wait.assert_called_once_with(+ timeout=GRACEFUL_EXIT_TIMEOUT+ )++ def test_default_close_does_not_wait(self) -> None:+ manager = self._closable_manager()+ manager.close_kernel()+ manager._process.wait.assert_not_called()++ def test_profiling_close_waits_for_flush(self) -> None:+ from marimo._session.managers.ipc import PROFILE_FLUSH_TIMEOUT++ manager = self._closable_manager()+ manager._profile_path = "/tmp/profile.stats"+ manager.close_kernel()+ manager._process.wait.assert_called_once_with(+ timeout=PROFILE_FLUSH_TIMEOUT+ )+++class TestAwaitHandshakeLine:+ @staticmethod+ def _await(manager: object, handshake: object, deadline: float) -> str:+ from collections import deque++ return manager._await_handshake_line(+ handshake, deadline, deque(), ["python", "-m", "kernel"]+ )++ def test_returns_pending_line(self) -> None:+ import queue+ import subprocess+ import sys as _sys++ manager = _make_manager("nb.py")+ manager._process = subprocess.Popen(+ [_sys.executable, "-c", "import time; time.sleep(30)"]+ )+ try:+ handshake: queue.Queue[str] = queue.Queue()+ handshake.put("KERNEL_READY")+ line = self._await(+ manager, handshake, deadline=time.monotonic() + 5+ )+ assert line == "KERNEL_READY"+ finally:+ manager._process.kill()+ manager._process.wait()++ def test_child_exit_fails_fast_with_exit_code(self) -> None:+ import queue+ import subprocess+ import sys as _sys++ from marimo._session.managers.ipc import KernelStartupError++ manager = _make_manager("nb.py")+ manager._process = subprocess.Popen(+ [_sys.executable, "-c", "import sys; sys.exit(3)"]+ )+ manager._process.wait()+ with pytest.raises(KernelStartupError, match="exit code 3"):+ self._await(manager, queue.Queue(), deadline=time.monotonic() + 30)++ def test_queued_handshake_takes_precedence_over_child_exit(self) -> None:+ import queue+ import subprocess+ import sys as _sys++ manager = _make_manager("nb.py")+ manager._process = subprocess.Popen([_sys.executable, "-c", "pass"])+ manager._process.wait()+ handshake: queue.Queue[str] = queue.Queue()+ handshake.put("KERNEL_READY")+ line = self._await(manager, handshake, deadline=time.monotonic() + 5)+ assert line == "KERNEL_READY"++ def test_hung_child_times_out_and_is_killed(self) -> None:+ import queue+ import subprocess+ import sys as _sys++ from marimo._session.managers.ipc import KernelStartupError++ manager = _make_manager("nb.py")+ manager._process = subprocess.Popen(+ [_sys.executable, "-c", "import time; time.sleep(60)"]+ )+ try:+ with pytest.raises(+ KernelStartupError, match="did not become ready"+ ):+ self._await(+ manager, queue.Queue(), deadline=time.monotonic() - 1+ )+ manager._process.wait(timeout=10)+ assert manager._process.poll() is not None+ finally:+ if manager._process.poll() is None:+ manager._process.kill()+ manager._process.wait()+++class TestParseKernelInfo:+ def test_full_line(self) -> None:+ from marimo._session.managers.ipc import _parse_kernel_info++ pid, exe = _parse_kernel_info("KERNEL_INFO 1234 /env/bin/python")+ assert pid == 1234+ assert exe == "/env/bin/python"++ def test_tolerates_absence_and_junk(self) -> None:+ from marimo._session.managers.ipc import _parse_kernel_info++ assert _parse_kernel_info("") == (None, None)+ assert _parse_kernel_info("something else") == (None, None)+ assert _parse_kernel_info("KERNEL_INFO not-a-pid") == (None, None)++ def test_pid_only(self) -> None:+ from marimo._session.managers.ipc import _parse_kernel_info++ assert _parse_kernel_info("KERNEL_INFO 99") == (99, None)+++def test_launch_kernel_handshake_reports_identity() -> None:+ """The kernel prints KERNEL_READY then KERNEL_INFO <pid> <exe>, so a+ manager separated from the kernel by a launcher can target it."""+ import subprocess+ import sys as _sys++ code = (+ "from unittest.mock import patch, MagicMock\n"+ "import marimo._ipc.launch_kernel as lk\n"+ "with patch.object(\n"+ " lk.KernelArgs, 'decode_json', return_value=MagicMock()\n"+ "), patch.object(lk.QueueManager, 'connect', MagicMock()), \\\n"+ " patch.object(lk.runtime, 'launch_kernel', MagicMock()):\n"+ " lk.main()\n"+ )+ completed = subprocess.run(+ [_sys.executable, "-c", code],+ capture_output=True,+ text=True,+ stdin=subprocess.DEVNULL,+ )+ assert completed.returncode == 0, completed.stderr+ lines = completed.stdout.splitlines()+ assert lines[0] == "KERNEL_READY"+ from marimo._session.managers.ipc import _parse_kernel_info++ pid, exe = _parse_kernel_info(lines[1])+ assert pid is not None+ assert exe is not Nonediff --git a/tests/_utils/test_subprocess.py b/tests/_utils/test_subprocess.pyindex ff6946cec3..afd6d5c815 100644--- a/tests/_utils/test_subprocess.py+++ b/tests/_utils/test_subprocess.py@@ -191,3 +191,17 @@ async def test_try_kill_process_and_group_sigkills_stubborn_child(finally:with contextlib.suppress(ProcessLookupError):os.killpg(pgid, signal.SIGKILL)++[email protected]("windows", [False, True])+def test_exited_process_is_not_signalled(windows: bool) -> None:+ process = subprocess.Popen([sys.executable, "-c", "pass"])+ process.wait(timeout=10)+ with (+ patch("marimo._utils.subprocess.is_windows", return_value=windows),+ patch("marimo._utils.subprocess.subprocess.run") as taskkill,+ patch("marimo._utils.subprocess.os.getpgid", create=True) as getpgid,+ ):+ try_kill_process_and_group(cast(ProcessLike, process))+ taskkill.assert_not_called()+ getpgid.assert_not_called()diff --git a/tests/snapshots/optional-dependencies-sandbox.txt b/tests/snapshots/optional-dependencies-sandbox.txtindex 71655da139..19d8e12253 100644--- a/tests/snapshots/optional-dependencies-sandbox.txt+++ b/tests/snapshots/optional-dependencies-sandbox.txt@@ -1,2 +1 @@-pyzmq>=27.1.0uv>=0.9.21\ No newline at end of filediff --git a/tests/test_project_dependencies.py b/tests/test_project_dependencies.pyindex 83cd013a06..d01797d800 100644--- a/tests/test_project_dependencies.py+++ b/tests/test_project_dependencies.py@@ -15,6 +15,16 @@ def test_required_dependencies(pyproject_text: str) -> None:snapshot("dependencies.txt", "\n".join(deps), keep_version=True)+def test_pyzmq_is_a_required_dependency(pyproject_text: str) -> None:+ """Kernel IPC imports zmq without a runtime check; sandbox code may+ assume it is present wherever marimo is."""+ import tomlkit++ pyproject = tomlkit.loads(pyproject_text)+ deps = pyproject["project"]["dependencies"]+ assert any(str(dep).startswith("pyzmq") for dep in deps)++@pytest.mark.parametrize("extra",["sql", "sandbox", "recommended", "lsp", "mcp"],