Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Run notebook sandboxes from uv script environments (#10696)

Trevor Manz3ae4a1596208
diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.py
index 0b7fff5b33..224738e046 100644
--- a/marimo/_cli/cli.py
+++ b/marimo/_cli/cli.py
@@ -21,10 +21,7 @@ from marimo._cli.config.commands import config
from marimo._cli.convert.commands import convert
from marimo._cli.development.commands import development
from marimo._cli.envinfo import get_system_info
-from marimo._cli.errors import (
- MarimoCLIMissingDependencyError,
- MarimoCLIRuntimeError,
-)
+from marimo._cli.errors import MarimoCLIRuntimeError
from marimo._cli.export.commands import export
from marimo._cli.files.file_path import validate_name
from 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 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 the marimo edit server on a directory with --sandbox.",
- "marimo[sandbox]",
- )
-
# Enable script metadata management for sandboxed notebooks
os.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.py
index 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 contextlib
import json
+import signal
import subprocess
+import threading
+from dataclasses import dataclass
from pathlib import Path
from typing import TYPE_CHECKING, Any
@@ -12,9 +16,12 @@ from marimo._server.files.directory_scanner import DirectoryScanner
from marimo._server.workspace import flatten_files
from marimo._utils.http import HTTPException, HTTPStatus
from marimo._utils.marimo_path import MarimoPath
+from marimo._utils.subprocess import kill_subprocess
if TYPE_CHECKING:
- from collections.abc import Iterable
+ from collections.abc import Iterable, Iterator
+
+ from marimo._environments.environment import Environment
def 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 target
def 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 stdout
diff --git a/marimo/_cli/export/commands.py b/marimo/_cli/export/commands.py
index 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"],
+ )
)
- return
try:
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,
+ )
)
- return
try:
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 = output
filename = "index.html"
diff --git a/marimo/_cli/export/session.py b/marimo/_cli/export/session.py
index f0080209d4..8a017324da 100644
--- a/marimo/_cli/export/session.py
+++ b/marimo/_cli/export/session.py
@@ -11,6 +11,7 @@ import click
from marimo._cli.errors import MarimoCLIMissingDependencyError
from 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(
return
echo(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 None
else 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.py
index c076554fc6..04dc3104fe 100644
--- a/marimo/_cli/export/thumbnail.py
+++ b/marimo/_cli/export/thumbnail.py
@@ -11,6 +11,7 @@ import click
from marimo._cli.errors import MarimoCLIMissingDependencyError
from 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 None
else 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.py
index c0adb31829..7af52d34ed 100644
--- a/marimo/_cli/sandbox.py
+++ b/marimo/_cli/sandbox.py
@@ -4,7 +4,6 @@ from __future__ import annotations
import atexit
import os
import platform
-import shutil
import signal
import subprocess
import sys
@@ -19,9 +18,11 @@ from marimo import _loggers
from marimo._cli.errors import MarimoCLIMissingDependencyError
from marimo._cli.print import bold, echo, green, muted
from 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_overlay
from 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 file
dependencies = _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"] + args
if "--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.name
if write_constraint_file(constraint_path):
+ # Resolution happens in the child uv process; see below.
env["UV_CONSTRAINT"] = constraint_path
def 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 returncode
diff --git a/marimo/_config/settings.py b/marimo/_config/settings.py
index 49a6c8b30f..bcc61a7ed3 100644
--- a/marimo/_config/settings.py
+++ b/marimo/_config/settings.py
@@ -18,6 +18,9 @@ class GlobalSettings:
PROFILE_DIR: str | None = None
LOG_LEVEL: int = logging.WARNING
MANAGE_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 None
IN_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. Default
diff --git a/marimo/_environments/environment.py b/marimo/_environments/environment.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 annotations
import contextlib
+import errno
import os
import platform
import re
+import stat
import subprocess
+import sys
import tempfile
+import time
from dataclasses import dataclass
from pathlib import Path
from typing import TYPE_CHECKING, Any
from marimo import _loggers
from 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_reader
if 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:
return
def 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:
return
def 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 = 1
def _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 error
try:
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.py
index e1a92118d2..91d0ded007 100644
--- a/marimo/_environments/uv.py
+++ b/marimo/_environments/uv.py
@@ -12,12 +12,17 @@ from __future__ import annotations
import os
import shutil
import subprocess
+import sys
+import threading
from typing import TYPE_CHECKING
+from marimo import _loggers
from marimo._environments.errors import EnvironmentManagerError
if 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 env
diff --git a/marimo/_ipc/launch_kernel.py b/marimo/_ipc/launch_kernel.py
index 67bac4aaac..28e636e631 100644
--- a/marimo/_ipc/launch_kernel.py
+++ b/marimo/_ipc/launch_kernel.py
@@ -3,6 +3,7 @@
from __future__ import annotations
+import os
import sys
from 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.py
index cfb5b609ce..79e69dfc49 100644
--- a/marimo/_ipc/types.py
+++ b/marimo/_ipc/types.py
@@ -8,6 +8,7 @@ from marimo._ast.cell import CellConfig
from marimo._config.config import MarimoConfig
from marimo._messaging.msgspec_encoder import encode_json_bytes
from marimo._runtime.commands import AppMetadata
+from marimo._runtime.virtual_file.storage import VirtualFileStorageType
from marimo._types.ids import CellId_t
@@ -39,6 +40,11 @@ class KernelArgs(msgspec.Struct):
virtual_files_supported: bool = True
redirect_console_to_browser: bool = True
parent_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 = None
def encode_json(self) -> bytes:
return encode_json_bytes(self)
diff --git a/marimo/_runtime/callbacks/packages.py b/marimo/_runtime/callbacks/packages.py
index 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_notification
from 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 None
or 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.py
index 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 streaming
log_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.py
index 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.py
index 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 annotations
import json
import os
+import re
import subprocess
import sys
from functools import cached_property
@@ -15,7 +16,12 @@ if TYPE_CHECKING:
from marimo import _loggers
from marimo._dependencies.dependencies import DependencyManager
from 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.executable
LOGGER = _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)
+
@classmethod
def 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 remove
upgrade: 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.py
index 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.py
index 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 Python
python_exe: str | None = None
+ script_path: str | None = None
from marimo._session.managers.ipc import IPCKernelManagerImpl
from marimo._session.session import SessionImpl
@@ -205,9 +204,17 @@ def _get_package_manager(request: Request) -> PackageManager:
kernel_manager = session._kernel_manager
if 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.filename
return 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.py
index 2d3418dd20..01c8076490 100644
--- a/marimo/_session/_venv.py
+++ b/marimo/_session/_venv.py
@@ -14,7 +14,6 @@ from __future__ import annotations
import os
import subprocess
import sys
-from importlib.metadata import version
from pathlib import Path
from 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.py
index 6190a4031c..9f0f0755ab 100644
--- a/marimo/_session/app_host/host.py
+++ b/marimo/_session/app_host/host.py
@@ -10,6 +10,7 @@ import threading
from typing import TYPE_CHECKING, cast
from marimo import _loggers
+from marimo._environments.environment import ProcessPlan
from marimo._messaging.types import KernelMessage
from 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
+ interpreter
on_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 = plan
self._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 = None
LOGGER.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_000
try:
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.py
index 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.py
index 2972b47205..087e859f30 100644
--- a/marimo/_session/app_host/pool.py
+++ b/marimo/_session/app_host/pool.py
@@ -8,14 +8,20 @@ from __future__ import annotations
import os
import threading
+from concurrent.futures import Future
from 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 UvMissingScriptMetadataError
from marimo._session.app_host.host import AppHost
-
-LOGGER = _loggers.marimo_logger()
+from marimo._session.managers.ipc import KernelStartupError
class 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 error
def 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 = True
workers = 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.py
index 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 annotations
import os
+import queue
+import signal
import subprocess
+import sys
+import threading
+import time
+from collections import deque
from pathlib import Path
from typing import TYPE_CHECKING, cast
+from uuid import uuid4
from marimo import _loggers
-from marimo._cli.sandbox import (
- build_sandbox_venv,
- cleanup_sandbox_dir,
-)
from marimo._config.config import VenvConfig
from marimo._config.manager import MarimoConfigReader
from 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, UvMissingScriptMetadataError
from marimo._messaging.types import KernelMessage
from marimo._runtime import commands
from 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 IPCQueueManagerType
from marimo._ipc.types import ConnectionInfo
from marimo._runtime.commands import AppMetadata
+ from marimo._runtime.virtual_file.storage import VirtualFileStorageType
from marimo._types.ids import CellId_t
LOGGER = _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-only
configured 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 = None
self.kernel_task: ProcessLike | None = None
- self._sandbox_dir: str | None = None
self._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_environment
def 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 = False
kernel_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 stdin
assert self._process.stdin is not None
self._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_executable
LOGGER.debug("Kernel ready")
# Create a ProcessLike wrapper for the subprocess
self.kernel_task = _SubprocessWrapper(self._process)
except KernelStartupError:
- # Already a KernelStartupError, just cleanup and re-raise
- cleanup_sandbox_dir(self._sandbox_dir)
raise
except 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)}"
+ )
+
@property
def pid(self) -> int | None:
if self._process is None:
@@ -366,8 +606,7 @@ class IPCKernelManagerImpl(KernelManager):
@property
def profile_path(self) -> str | None:
- # Profiling not currently supported with IPC kernel
- return None
+ return self._profile_path
@property
def 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:
+ pass
self.queue_manager.close_queues()
+ if graceful and self._process.poll() is None:
+ try:
+ self._process.wait(timeout=GRACEFUL_EXIT_TIMEOUT)
+ except subprocess.TimeoutExpired:
+ pass
if 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):
+ pass
try:
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
@property
def kernel_connection(self) -> TypedConnection[KernelMessage]:
diff --git a/marimo/_utils/subprocess.py b/marimo/_utils/subprocess.py
index 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):
return
if 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()
return
pgid = 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.toml
index 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.py
index 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 = 0
result = 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 = 0
result = runner.invoke(
cli_main,
["new", "--sandbox", "--headless", "--no-token"],
diff --git a/tests/_cli/test_cli_export.py b/tests/_cli/test_cli_export.py
index 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:
@staticmethod
def 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 message
assert "Running in a sandbox" in output
- assert "run --isolated" in output
+ assert "Using script environment" in output
html = 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 message
assert "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.py
index 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, sandbox
called.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, sandbox
called.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.py
new file mode 100644
index 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:
+ pass
diff --git a/tests/_cli/test_sandbox.py b/tests/_cli/test_sandbox.py
index 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.SINGLE
def test_resolve_sandbox_mode_explicit_single() -> None:
@@ -590,128 +589,6 @@ import marimo
assert 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"]) == expected
diff --git a/tests/_environments/test_environment.py b/tests/_environments/test_environment.py
new file mode 100644
index 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.py
index 0a074053e0..4166bb7cfd 100644
--- a/tests/_environments/test_script_metadata.py
+++ b/tests/_environments/test_script_metadata.py
@@ -3,16 +3,14 @@ from __future__ import annotations
import platform
import subprocess
-from typing import TYPE_CHECKING
+import sys
+from pathlib import Path
import pytest
from marimo._environments import script_metadata
from 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 None
assert 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.py
index 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, Any
import 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.closed
diff --git a/tests/_runtime/packages/test_package_managers.py b/tests/_runtime/packages/test_package_managers.py
index 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 asyncio
import os
import sys
from 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.py
index 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 Path
from typing import Any
from unittest.mock import MagicMock, patch
+import pytest
+
from marimo._ast import compiler
from marimo._runtime.packages.package_manager import PackageDescription
from 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.py
index 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 statuses
assert "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 joined
diff --git a/tests/_server/api/endpoints/test_packages.py b/tests/_server/api/endpoints/test_packages.py
index 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_exe
mock_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_exe
mock_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.py
index 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 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)
- # 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 Environment
from marimo._session.app_host.pool import AppHostPool
pool = 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, patch
from 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 UvMissingScriptMetadataError
from marimo._session.app_host.pool import AppHostPool
pool = 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 = True
with (
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.py
index 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_host
assert 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.py
index 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 starts
assert 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 up
wrapper.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 base
assert "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 None
diff --git a/tests/_utils/test_subprocess.py b/tests/_utils/test_subprocess.py
index 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.txt
index 71655da139..19d8e12253 100644
--- a/tests/snapshots/optional-dependencies-sandbox.txt
+++ b/tests/snapshots/optional-dependencies-sandbox.txt
@@ -1,2 +1 @@
-pyzmq>=27.1.0
uv>=0.9.21
\ No newline at end of file
diff --git a/tests/test_project_dependencies.py b/tests/test_project_dependencies.py
index 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"],