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.

Unify sandbox execution and async startup (#10821)

Trevor Manzcbb66e0bb4db
diff --git a/.github/workflows/test_cli.yaml b/.github/workflows/test_cli.yaml
index 3316e1e091..1a185e0c4f 100644
--- a/.github/workflows/test_cli.yaml
+++ b/.github/workflows/test_cli.yaml
@@ -177,6 +177,8 @@ jobs:
env:
UV_FIND_LINKS: ${{ github.workspace }}
run: |
+ # Each run builds a different wheel under the same version and path.
+ uv cache clean marimo
uv venv
uv pip install --group=test-optional --group=dev marimo*.whl
uv run --no-project pytest -v tests/_cli/test_cli* -p no:xdist --maxfail=2
diff --git a/docs/guides/exporting/sessions.md b/docs/guides/exporting/sessions.md
index 1bae69c18c..46cee73aa6 100644
--- a/docs/guides/exporting/sessions.md
+++ b/docs/guides/exporting/sessions.md
@@ -57,8 +57,19 @@ Use `--no-continue-on-error` to stop at the first failure.
## Sandboxed execution
-To execute in a sandboxed environment, pass `--sandbox`:
+To execute in a sandboxed environment, install
+[uv](https://docs.astral.sh/uv/getting-started/installation/) or
+[pixi](https://pixi.prefix.dev/latest/installation/), then pass `--sandbox`:
```bash
marimo export session notebook.py --sandbox
```
+
+`--sandbox` defaults to uv. Use `--sandbox uv` or `--sandbox pixi` (equivalently,
+`--sandbox=uv` or `--sandbox=pixi`) to select
+the backend explicitly; only the selected tool needs to be installed.
+Use `--no-sandbox` to disable sandboxing and dependency prompts.
+
+Each notebook executes in a separate process using its inline dependencies,
+whether you export a single file or a directory. Up-to-date snapshots are
+skipped before checking for the backend or preparing the notebook environment.
diff --git a/docs/guides/package_management/inlining_dependencies.md b/docs/guides/package_management/inlining_dependencies.md
index 8f7955680d..a68228df79 100644
--- a/docs/guides/package_management/inlining_dependencies.md
+++ b/docs/guides/package_management/inlining_dependencies.md
@@ -30,9 +30,15 @@ When running with `--sandbox`, marimo:
1. tracks the packages and versions used by your notebook, saving
them in the notebook file;
-2. runs in an isolated virtual environment ("sandbox") that only
+2. executes the notebook in an isolated virtual environment ("sandbox") that only
contains the notebook dependencies.
+For `edit` and `new`, the editor server starts in your current Python
+environment. Each notebook gets its own sandboxed kernel when you open it,
+whether you start with a single file or a folder. The editor can therefore
+start before the notebook's dependencies are installed. Editor features such
+as language servers use packages installed alongside the server.
+
marimo's sandbox provides two key benefits. (1) Notebooks that carry their own
dependencies are easy to share — just send the `.py` file. (2) Isolating a
notebook from other installed packages prevents obscure bugs.
@@ -60,7 +66,8 @@ uv run notebook.py
If your notebook needs conda packages, use Pixi as the sandbox backend.
[Install Pixi](https://pixi.prefix.dev/latest/installation/) with support for
`pixi install --script` (available in Pixi 0.80.0). marimo checks this capability
-at startup; use `pixi self-update` if your installation predates it.
+when preparing a notebook's environment; use `pixi self-update` if your
+installation predates it.
```bash
marimo edit --sandbox=pixi notebook.py
@@ -91,8 +98,8 @@ notebook also runs standalone with `pixi run --script notebook.py`.
[Pyodide](https://pyodide.org)'s package set, which has no conda
equivalent: notebooks that rely on `[tool.pixi.dependencies]`
cannot be exported to WASM.
- - The `--sandbox` flag on `marimo export` commands always uses uv,
- so conda dependencies are not available during export.
+ - Session and thumbnail exports support `--sandbox=pixi`. Other export
+ commands still use uv, so conda dependencies are not available there.
!!! tip "Solving the notebook reproducibility crisis"
diff --git a/docs/guides/publishing/thumbnails.md b/docs/guides/publishing/thumbnails.md
index a3072ddb90..8fa032be31 100644
--- a/docs/guides/publishing/thumbnails.md
+++ b/docs/guides/publishing/thumbnails.md
@@ -65,9 +65,18 @@ By default, thumbnails are generated without executing the notebook (fast; no ou
marimo export thumbnail --execute --sandbox notebook.py
```
- !!! note "Requires uv"
+ !!! note "Choose a sandbox backend"
- `--sandbox` runs the notebook in an isolated environment and installs dependencies from inline script metadata (PEP 723). See [Inlining dependencies](../package_management/inlining_dependencies.md).
+ `--sandbox` defaults to uv. Use `--sandbox=uv` or `--sandbox=pixi` to
+ select the backend explicitly; only the selected tool needs to be
+ installed. Use `--no-sandbox` to disable sandboxing and dependency prompts.
+
+ Sandboxed execution installs dependencies from inline script metadata
+ (PEP 723). See [Inlining dependencies](../package_management/inlining_dependencies.md).
+
+ Each notebook executes in its own process using its inline dependencies.
+ Playwright is installed for the renderer without adding it to notebook
+ dependencies.
!!! note "Sandbox only applies with execution"
diff --git a/frontend/src/__mocks__/requests.ts b/frontend/src/__mocks__/requests.ts
index af55930bc3..148b19ba1c 100644
--- a/frontend/src/__mocks__/requests.ts
+++ b/frontend/src/__mocks__/requests.ts
@@ -139,6 +139,13 @@ export const MockRequestClient = {
getPackageList: vi.fn().mockResolvedValue({
packages: [],
}),
+ getSandbox: vi
+ .fn()
+ .mockResolvedValue({ backend: null, manifest: null, filename: null }),
+ updateManifest: vi
+ .fn()
+ .mockResolvedValue({ backend: null, manifest: null, filename: null }),
+ syncSandbox: vi.fn().mockResolvedValue({ success: true }),
getDependencyTree: vi.fn().mockResolvedValue({
tree: null,
context: { kind: "package-manager", name: "pip" },
diff --git a/frontend/src/components/editor/alerts/connecting-alert.tsx b/frontend/src/components/editor/alerts/connecting-alert.tsx
index 9d16eaaca0..1ce5b803db 100644
--- a/frontend/src/components/editor/alerts/connecting-alert.tsx
+++ b/frontend/src/components/editor/alerts/connecting-alert.tsx
@@ -1,76 +1,11 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { useAtomValue } from "jotai";
-import { LoadingEllipsis } from "@/components/icons/loading-ellipsis";
-import { Spinner } from "@/components/icons/spinner";
import { Button } from "@/components/ui/button";
-import { DelayMount } from "@/components/utils/delay-mount";
-import {
- isClosedAtom,
- isConnectingAtom,
- isNotStartedAtom,
-} from "@/core/network/connection";
+import { isNotStartedAtom } from "@/core/network/connection";
import { useConnectToRuntime } from "@/core/runtime/config";
-import { Banner } from "@/plugins/impl/common/error-banner";
-import { Tooltip } from "../../ui/tooltip";
import { FloatingAlert } from "./floating-alert";
-const SHORT_DELAY_MS = 1000; // 1 second
-const LONG_DELAY_MS = 5000; // 5 seconds
-
-export const ConnectingAlert: React.FC = () => {
- const isConnecting = useAtomValue(isConnectingAtom);
- const isClosed = useAtomValue(isClosedAtom);
-
- if (isConnecting) {
- const subtleNotification = (
- <Tooltip content="Connecting to a marimo runtime">
- <div className="flex items-center">
- <LoadingEllipsis size={5} className="text-yellow-500" />
- </div>
- </Tooltip>
- );
-
- const longNotification = (
- <Banner
- kind="info"
- className="flex flex-col rounded py-2 px-4 animate-in slide-in-from-top w-fit"
- >
- <div className="flex flex-col gap-4 justify-between items-start text-muted-foreground text-base">
- <div className="flex items-center gap-2">
- <Spinner className="h-4 w-4" />
- <p>Connecting to a marimo runtime ...</p>
- </div>
- </div>
- </Banner>
- );
-
- // This waits for 1 second to show the subtle notification, then shows the long notification after 5 seconds.
- return (
- <DelayMount milliseconds={SHORT_DELAY_MS}>
- <div className="m-0 flex items-center min-h-[28px] fixed top-5 left-1/2 transform -translate-x-1/2 z-200">
- <DelayMount
- milliseconds={LONG_DELAY_MS}
- fallback={subtleNotification}
- >
- {longNotification}
- </DelayMount>
- </div>
- </DelayMount>
- );
- }
-
- if (isClosed) {
- return (
- <FloatingAlert show={isClosed} kind="danger">
- <div className="flex items-center gap-2">
- <p>Failed to connect.</p>
- </div>
- </FloatingAlert>
- );
- }
-};
-
export const NotStartedConnectionAlert: React.FC = () => {
const isNotStarted = useAtomValue(isNotStartedAtom);
const connectToRuntime = useConnectToRuntime();
diff --git a/frontend/src/components/editor/alerts/connection-notice.tsx b/frontend/src/components/editor/alerts/connection-notice.tsx
new file mode 100644
index 0000000000..32da3e1fcf
--- /dev/null
+++ b/frontend/src/components/editor/alerts/connection-notice.tsx
@@ -0,0 +1,140 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useAtomValue } from "jotai";
+import { AlertCircleIcon, ArrowRightIcon } from "lucide-react";
+import { useState } from "react";
+import { Spinner } from "@/components/icons/spinner";
+import { Button } from "@/components/ui/button";
+import { hasCellsAtom } from "@/core/cells/cells";
+import type { AppConfig } from "@/core/config/config-schema";
+import { connectionAtom } from "@/core/network/connection";
+import { connectionNoticeAtom } from "@/core/network/connection-notice";
+import { WebSocketState } from "@/core/websocket/types";
+import { useDelayElapsed } from "@/hooks/useDelayElapsed";
+import { useInterval } from "@/hooks/useInterval";
+import { cn } from "@/utils/cn";
+import { SandboxErrorOutput } from "../chrome/panels/sandbox-panel";
+import { chromeAtom, useChromeActions } from "../chrome/state";
+import { VerticalLayoutWrapper } from "../renderers/vertical-layout/vertical-layout-wrapper";
+
+export const ConnectionNotice = ({
+ appConfig,
+ onRetry,
+}: {
+ appConfig: AppConfig;
+ onRetry: () => void;
+}) => {
+ const notice = useAtomValue(connectionNoticeAtom);
+ const connection = useAtomValue(connectionAtom);
+ const hasCells = useAtomValue(hasCellsAtom);
+ const chrome = useAtomValue(chromeAtom);
+ const packagesOpen =
+ (chrome.isSidebarOpen && chrome.selectedPanel === "packages") ||
+ (chrome.isDeveloperPanelOpen &&
+ chrome.selectedDeveloperPanelTab === "packages");
+ const elapsed = useDelayElapsed(notice?.pending ? 500 : 0);
+ const { openApplication } = useChromeActions();
+
+ // Reconnection uses the footer indicator while existing cells stay visible.
+ if (
+ !notice ||
+ !elapsed ||
+ (hasCells &&
+ connection.state === WebSocketState.CONNECTING &&
+ connection.phase === "reconnecting")
+ ) {
+ return null;
+ }
+
+ return (
+ <VerticalLayoutWrapper
+ appConfig={appConfig}
+ className="shrink-0 pb-0 sm:pb-0 print:hidden"
+ innerClassName="pb-0 sm:pb-0 pr-4"
+ >
+ <section
+ aria-label="Notebook startup"
+ className={cn(
+ "text-muted-foreground",
+ hasCells
+ ? "mt-4 mb-8 border rounded-lg px-5 py-5"
+ : "max-w-sm mx-auto mt-16 sm:mt-24 px-4",
+ hasCells && !notice.pending && "border-(--red-7)",
+ )}
+ >
+ <div role="status" className="flex items-center gap-2.5">
+ {notice.pending ? (
+ <Spinner className="size-4 shrink-0" aria-hidden={true} />
+ ) : (
+ <AlertCircleIcon
+ className="size-4 shrink-0 text-(--red-11)"
+ aria-hidden={true}
+ />
+ )}
+ <h2
+ className={cn(
+ "text-base",
+ notice.pending
+ ? "font-normal text-foreground"
+ : "font-medium text-(--red-11)",
+ )}
+ >
+ {notice.title}
+ </h2>
+ </div>
+ <div className="ml-6.5">
+ <p
+ className={cn(
+ "mt-3 text-sm leading-7",
+ !notice.pending && "text-foreground",
+ )}
+ >
+ {notice.description}
+ </p>
+ {!notice.sandbox && notice.error && (
+ <SandboxErrorOutput error={notice.error} />
+ )}
+ <div className="mt-5 flex flex-wrap items-center gap-x-6 gap-y-3">
+ {!packagesOpen && (notice.sandbox || notice.pending) && (
+ <Button
+ variant="text"
+ size="xs"
+ className="h-auto p-0 text-xs gap-1.5"
+ onClick={() => openApplication("packages")}
+ >
+ {notice.pending ? "View setup details" : "Open Packages"}
+ <ArrowRightIcon className="size-3" aria-hidden={true} />
+ </Button>
+ )}
+ {!notice.pending && !notice.sandbox && (
+ <Button variant="outline" size="xs" onClick={onRetry}>
+ Try again
+ </Button>
+ )}
+ {notice.pending && <StartupElapsedTime />}
+ </div>
+ </div>
+ </section>
+ </VerticalLayoutWrapper>
+ );
+};
+
+function StartupElapsedTime() {
+ const [startedAt] = useState(Date.now);
+ const [seconds, setSeconds] = useState(0);
+ useInterval(() => setSeconds(Math.floor((Date.now() - startedAt) / 1000)), {
+ delayMs: 1000,
+ whenVisible: true,
+ });
+ const duration =
+ seconds < 60
+ ? `${seconds}s`
+ : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+ return (
+ <span
+ className="text-xs text-muted-foreground/70 tabular-nums"
+ aria-live="off"
+ >
+ Elapsed {duration}
+ </span>
+ );
+}
diff --git a/frontend/src/components/editor/app-container.tsx b/frontend/src/components/editor/app-container.tsx
index 0fe0b3833d..49a5a052bd 100644
--- a/frontend/src/components/editor/app-container.tsx
+++ b/frontend/src/components/editor/app-container.tsx
@@ -4,8 +4,11 @@ import type React from "react";
import type { PropsWithChildren } from "react";
import type { AppConfig } from "@/core/config/config-schema";
import { PyodideLoader } from "@/core/wasm/PyodideLoader";
-import { isAppClosed } from "@/core/websocket/connection-utils";
-import type { ConnectionStatus } from "@/core/websocket/types";
+import {
+ type ConnectionStatus,
+ WebSocketClosedReason,
+ WebSocketState,
+} from "@/core/websocket/types";
import { cn } from "@/utils/cn";
import { DynamicFavicon } from "./dynamic-favicon";
import { StatusOverlay } from "./header/status";
@@ -44,7 +47,10 @@ export const AppContainer: React.FC<PropsWithChildren<Props>> = ({
data-connection-state={connectionState}
className={cn(
"mathjax_ignore",
- isAppClosed(connectionState) && "disconnected",
+ connection.state === WebSocketState.CLOSED &&
+ connection.code !==
+ WebSocketClosedReason.KERNEL_STARTUP_ERROR &&
+ "disconnected",
"bg-background w-full h-full text-textColor",
"flex flex-col overflow-y-auto",
width === "full" && "config-width-full",
diff --git a/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx b/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx
index c6f81cb6c9..a258d8d1b7 100644
--- a/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx
+++ b/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx
@@ -1,6 +1,13 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import { fireEvent, render, screen } from "@testing-library/react";
+import {
+ act,
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+ within,
+} from "@testing-library/react";
import { Provider } from "jotai";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { MockRequestClient } from "@/__mocks__/requests";
@@ -10,6 +17,9 @@ import type {
DependencyTreeNode,
DependencyTreeResponse,
} from "@/core/network/types";
+import { withPackageInvalidation } from "@/core/packages/package-data";
+import { useInstallPackages } from "@/core/packages/useInstallPackage";
+import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";
import { store } from "@/core/state/jotai";
import PackagesPanel from "../packages-panel";
@@ -51,16 +61,22 @@ function renderPanel(
context: DependencyTreeResponse["context"],
tree: DependencyTreeNode = emptyTree,
) {
- const getPackageList = vi.fn().mockResolvedValue({ packages: [] });
store.set(
- requestClientAtom,
- MockRequestClient.create({
- getPackageList,
- getDependencyTree: vi.fn().mockResolvedValue({ tree, context }),
- }),
+ sandboxAtom,
+ context.kind === "sandbox"
+ ? { backend: context.backend, manifest: "", filename: "notebook.py" }
+ : null,
);
+ store.set(sandboxSyncAtom, { pending: false, error: null });
+ const getPackageList = vi.fn().mockResolvedValue({ packages: [] });
+ const client = MockRequestClient.create({
+ getPackageList,
+ getDependencyTree: vi.fn().mockResolvedValue({ tree, context }),
+ });
+ store.set(requestClientAtom, client);
return {
+ client,
getPackageList,
...render(
<Provider store={store}>
@@ -141,3 +157,94 @@ describe("PackagesPanel", () => {
expect(getPackageList).toHaveBeenCalledOnce();
});
});
+
+it("refreshes an open panel when a package is installed elsewhere, after installation succeeds", async () => {
+ const { promise, resolve } = Promise.withResolvers<{ success: boolean }>();
+ const client = MockRequestClient.create({
+ addPackage: vi.fn(() => promise),
+ getDependencyTree: vi
+ .fn()
+ .mockResolvedValueOnce({
+ tree: emptyTree,
+ context: { kind: "sandbox", backend: "uv" },
+ })
+ .mockResolvedValue({
+ tree: populatedTree,
+ context: { kind: "sandbox", backend: "uv" },
+ }),
+ });
+ store.set(sandboxAtom, {
+ backend: "uv",
+ manifest: "",
+ filename: "notebook.py",
+ });
+ store.set(sandboxSyncAtom, { pending: false, error: null });
+ store.set(requestClientAtom, withPackageInvalidation(client));
+ function InstallElsewhere() {
+ const { handleInstallPackages } = useInstallPackages();
+ return (
+ <button onClick={() => handleInstallPackages(["polars"])}>
+ Install from another panel
+ </button>
+ );
+ }
+ render(
+ <Provider store={store}>
+ <TooltipProvider>
+ <PackagesPanel />
+ <InstallElsewhere />
+ </TooltipProvider>
+ </Provider>,
+ );
+ await screen.findByPlaceholderText("Add packages to uv sandbox...");
+ fireEvent.click(
+ screen.getByRole("button", { name: "Install from another panel" }),
+ );
+ expect(client.getDependencyTree).toHaveBeenCalledTimes(1);
+ await act(async () => resolve({ success: true }));
+ await waitFor(() =>
+ expect(client.getDependencyTree).toHaveBeenCalledTimes(2),
+ );
+ expect(await screen.findByText("polars")).toBeInTheDocument();
+});
+
+it.each(["uv", "pixi", "list"] as const)(
+ "allows upgrading marimo but not removing it in the %s view",
+ async (view) => {
+ const tree = {
+ ...populatedTree,
+ dependencies: [
+ ...populatedTree.dependencies,
+ { name: "marimo", version: "0.24.0", tags: [], dependencies: [] },
+ ],
+ };
+ const { client, getPackageList } = renderPanel(
+ view === "list"
+ ? { kind: "package-manager", name: "pip" }
+ : { kind: "sandbox", backend: view },
+ tree,
+ );
+ getPackageList.mockResolvedValue({ packages: tree.dependencies });
+ vi.mocked(client.addPackage).mockResolvedValue({ success: true });
+ if (view === "list") {
+ fireEvent.click(await screen.findByRole("button", { name: "List" }));
+ }
+ const role = view === "list" ? "row" : "treeitem";
+ const marimo = within(await screen.findByRole(role, { name: /marimo/ }));
+ expect(marimo.getByText(/0\.24\.0/)).toBeInTheDocument();
+ expect(
+ marimo.queryByRole("button", { name: "Remove" }),
+ ).not.toBeInTheDocument();
+ const polars = within(screen.getByRole(role, { name: /polars/ }));
+ expect(polars.getByRole("button", { name: "Remove" })).toBeInTheDocument();
+ fireEvent.click(marimo.getByRole("button", { name: "Upgrade" }));
+ await waitFor(() =>
+ expect(client.addPackage).toHaveBeenCalledWith({
+ package: "marimo",
+ upgrade: true,
+ group: undefined,
+ }),
+ );
+ expect(client.removePackage).not.toHaveBeenCalled();
+ },
+);
diff --git a/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx b/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx
new file mode 100644
index 0000000000..1b8592bb59
--- /dev/null
+++ b/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx
@@ -0,0 +1,165 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+// @vitest-environment jsdom
+import {
+ act,
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+ within,
+} from "@testing-library/react";
+import { Provider } from "jotai";
+import { beforeEach, expect, it, vi } from "vitest";
+import { MockRequestClient } from "@/__mocks__/requests";
+import { AppConfigSchema } from "@/core/config/config-schema";
+import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import { kernelStartupErrorAtom } from "@/core/errors/state";
+import { connectionAtom } from "@/core/network/connection";
+import { requestClientAtom } from "@/core/network/requests";
+import {
+ sandboxActionsAtom,
+ sandboxAtom,
+ sandboxSyncAtom,
+} from "@/core/packages/sandbox-state";
+import { filenameAtom } from "@/core/saving/file-state";
+import { store } from "@/core/state/jotai";
+import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";
+import { chromeAtom } from "../../state";
+import PackagesPanel from "../packages-panel";
+import { SandboxController } from "../sandbox-controller";
+
+vi.mock("@/plugins/impl/code/LazyAnyLanguageCodeMirror", () => ({
+ LazyAnyLanguageCodeMirror: ({
+ value,
+ onChange,
+ editable,
+ }: {
+ value: string;
+ onChange: (value: string) => void;
+ editable: boolean;
+ }) => (
+ <textarea
+ aria-label="Notebook manifest"
+ value={value}
+ readOnly={!editable}
+ onChange={(event) => onChange(event.target.value)}
+ />
+ ),
+}));
+
+const manifest =
+ 'dependencies = ["numpy==0.0.0"]\n\n[tool.custom]\nlabel = "experiment"\n';
+const failed = {
+ state: WebSocketState.CLOSED,
+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ phase: "preparing-environment",
+ reason: "Kernel startup failed",
+} as const;
+beforeEach(() => {
+ store.set(sandboxAtom, { backend: "uv", manifest, filename: "notebook.py" });
+ store.set(sandboxSyncAtom, { pending: false, error: null });
+ store.set(sandboxActionsAtom, null);
+ store.set(connectionAtom, failed);
+ store.set(kernelStartupErrorAtom, "resolver output\n no solution");
+ store.set(filenameAtom, "notebook.py");
+ store.set(chromeAtom, {
+ selectedPanel: "packages",
+ isSidebarOpen: false,
+ isDeveloperPanelOpen: false,
+ selectedDeveloperPanelTab: "errors",
+ });
+});
+function mount(
+ client: ReturnType<typeof MockRequestClient.create>,
+ reconnect = vi.fn(async () => {}),
+) {
+ store.set(requestClientAtom, client);
+ return render(
+ <Provider store={store}>
+ <TooltipProvider>
+ <SandboxController onReconnect={reconnect} />
+ <ConnectionNotice
+ appConfig={AppConfigSchema.parse({})}
+ onRetry={reconnect}
+ />
+ <PackagesPanel />
+ </TooltipProvider>
+ </Provider>,
+ );
+}
+function requests() {
+ return MockRequestClient.create({
+ getSandbox: vi.fn(async () => ({
+ backend: "uv",
+ manifest,
+ filename: "notebook.py",
+ })),
+ updateManifest: vi.fn(async ({ contents }) => ({
+ backend: "uv",
+ manifest: contents,
+ filename: "notebook.py",
+ })),
+ syncSandbox: vi.fn(async () => ({ success: true, reconnect: true })),
+ });
+}
+
+it("keeps a whole-manifest repair open through failure and closes only after sync succeeds", async () => {
+ const client = requests();
+ const { promise: saved, resolve: finishSave } = Promise.withResolvers<void>();
+ vi.mocked(client.updateManifest).mockImplementation(async ({ contents }) => {
+ await saved;
+ return { backend: "uv", manifest: contents, filename: "notebook.py" };
+ });
+ const reconnect = vi.fn(async () => {
+ store.set(kernelStartupErrorAtom, null);
+ store.set(connectionAtom, {
+ state: WebSocketState.CONNECTING,
+ phase: "preparing-environment",
+ });
+ });
+ mount(client, reconnect);
+ fireEvent.click(await screen.findByRole("button", { name: "Open Packages" }));
+ expect(store.get(chromeAtom).isSidebarOpen).toBe(true);
+ expect(screen.getByLabelText("Error details")).toHaveTextContent(
+ "resolver output",
+ );
+ fireEvent.click(screen.getByRole("button", { name: "Edit manifest…" }));
+ const editor = await screen.findByRole("textbox", {
+ name: "Notebook manifest",
+ });
+ const replacement =
+ '# A completely different manifest\n[tool.custom]\nlabel = "updated"\n';
+ fireEvent.change(editor, { target: { value: replacement } });
+ fireEvent.click(screen.getByRole("button", { name: "Save & sync" }));
+ expect(screen.getByRole("dialog")).toBeInTheDocument();
+ expect(reconnect).not.toHaveBeenCalled();
+ await act(async () => finishSave());
+ await waitFor(() => expect(reconnect).toHaveBeenCalledTimes(1));
+ expect(client.updateManifest).toHaveBeenCalledWith({
+ fileKey: "notebook.py",
+ previous: manifest,
+ contents: replacement,
+ });
+ expect(screen.getByRole("dialog")).toBeInTheDocument();
+ act(() => {
+ store.set(connectionAtom, failed);
+ store.set(kernelStartupErrorAtom, "another resolver failure");
+ });
+ const dialog = within(screen.getByRole("dialog"));
+ expect(await dialog.findByLabelText("Error details")).toHaveTextContent(
+ "another resolver failure",
+ );
+ expect(
+ dialog.getByRole("textbox", { name: "Notebook manifest" }),
+ ).toHaveValue(replacement);
+ await waitFor(() =>
+ expect(dialog.getByRole("button", { name: "Sync" })).toBeEnabled(),
+ );
+ fireEvent.click(dialog.getByRole("button", { name: "Sync" }));
+ await waitFor(() => expect(reconnect).toHaveBeenCalledTimes(2));
+ act(() => store.set(connectionAtom, { state: WebSocketState.OPEN }));
+ await waitFor(() =>
+ expect(screen.queryByRole("dialog")).not.toBeInTheDocument(),
+ );
+});
diff --git a/frontend/src/components/editor/chrome/panels/packages-panel.tsx b/frontend/src/components/editor/chrome/panels/packages-panel.tsx
index 9f3b03e9ff..15a1b14e0b 100644
--- a/frontend/src/components/editor/chrome/panels/packages-panel.tsx
+++ b/frontend/src/components/editor/chrome/panels/packages-panel.tsx
@@ -7,6 +7,7 @@ import {
HelpCircleIcon,
} from "lucide-react";
import React from "react";
+import { connectionNoticeAtom } from "@/core/network/connection-notice";
import { useOpenSettingsToTab } from "@/components/app-config/state";
import { Spinner } from "@/components/icons/spinner";
import { SearchInput } from "@/components/ui/input";
@@ -20,25 +21,22 @@ import {
} from "@/components/ui/table";
import { Tooltip } from "@/components/ui/tooltip";
import { toast } from "@/components/ui/use-toast";
-import { useResolvedMarimoConfig } from "@/core/config/config";
-import { useRequestClient } from "@/core/network/requests";
+import { isConnectedAtom } from "@/core/network/connection";
import type {
DependencyTreeNode,
DependencyTreeResponse,
} from "@/core/network/types";
+import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";
import { stripPackageManagerPrefix } from "@/core/packages/package-input-utils";
-import {
- showPackageRestartToast,
- showRemovePackageToast,
- showUpgradePackageToast,
-} from "@/core/packages/toast-components";
+import { usePackageAction } from "@/core/packages/usePackageAction";
+import { usePackageDependencies } from "@/core/packages/usePackageDependencies";
import { useInstallPackages } from "@/core/packages/useInstallPackage";
import { isWasm } from "@/core/wasm/utils";
-import { useAsyncData } from "@/hooks/useAsyncData";
import { ErrorBanner } from "@/plugins/impl/common/error-banner";
import { cn } from "@/utils/cn";
import { copyToClipboard } from "@/utils/copy";
import { Events } from "@/utils/events";
+import { SandboxFooter, SandboxStartupPanel } from "./sandbox-panel";
import { PanelEmptyState } from "./empty-state";
import { PACKAGES_INPUT_ID, packagesToInstallAtom } from "./packages-utils";
@@ -71,36 +69,44 @@ const PackageActionButton: React.FC<{
};
const PackagesPanel: React.FC = () => {
- const [config] = useResolvedMarimoConfig();
- const packageManager = config.package_management.manager;
- const { getDependencyTree, getPackageList } = useRequestClient();
+ const sandbox = useAtomValue(sandboxAtom);
+ const connected = useAtomValue(isConnectedAtom);
+ const notice = useAtomValue(connectionNoticeAtom);
+ const operation = useAtomValue(sandboxSyncAtom);
+ if (sandbox?.backend) {
+ return (
+ <div className="flex flex-col flex-1 min-h-0 overflow-hidden">
+ {notice && (!operation.pending || !connected) ? (
+ <SandboxStartupPanel />
+ ) : (
+ <PackageContents />
+ )}
+ <SandboxFooter />
+ </div>
+ );
+ }
+ if (notice) {
+ return (
+ <div className="p-4 text-sm text-muted-foreground">
+ <div className="flex items-center gap-2">
+ {notice.pending && <Spinner className="size-3" />}
+ {notice.title}
+ </div>
+ {notice.error && (
+ <pre className="mt-3 text-xs whitespace-pre-wrap break-words max-h-52 overflow-auto">
+ {notice.error}
+ </pre>
+ )}
+ </div>
+ );
+ }
+ return <PackageContents />;
+};
+const PackageContents: React.FC = () => {
+ const { pending: syncing } = useAtomValue(sandboxSyncAtom);
const [userViewMode, setUserViewMode] = React.useState<ViewMode | null>(null);
- const {
- data: dependencies,
- error,
- refetch,
- isPending,
- } = useAsyncData(async () => {
- // A sandbox's list and tree both inspect the same environment. Wait for
- // the context before issuing the list request so sandboxes do that work
- // only once; non-sandbox managers still need both views.
- const dependencyTreeResponse = await getDependencyTree();
- if (dependencyTreeResponse.context.kind === "sandbox") {
- return {
- list: [],
- context: dependencyTreeResponse.context,
- tree: dependencyTreeResponse.tree,
- };
- }
-
- const listPackagesResponse = await getPackageList();
- return {
- list: listPackagesResponse.packages,
- context: dependencyTreeResponse.context,
- tree: dependencyTreeResponse.tree,
- };
- }, [packageManager]);
+ const { data: dependencies, error, isPending } = usePackageDependencies();
// Only show on the first load
if (isPending) {
@@ -122,58 +128,49 @@ const PackagesPanel: React.FC = () => {
const viewMode = isSandbox
? "tree"
: resolveViewMode(userViewMode, isTreeSupported);
- const scopeLabel = sandboxBackend
- ? `${sandboxBackend} sandbox`
- : name && name !== "<root>"
- ? "project"
- : "environment";
- const scopeTitle = sandboxBackend
- ? `Dependencies are managed by the ${sandboxBackend} sandbox selected when marimo started.`
- : scopeLabel;
+ const scopeLabel = name && name !== "<root>" ? "project" : "environment";
return (
<div className="flex-1 flex flex-col overflow-hidden">
- <InstallPackageForm context={dependencies.context} onSuccess={refetch} />
- {(isTreeSupported || isSandbox) && (
+ <fieldset disabled={syncing} className="contents">
+ <InstallPackageForm context={dependencies.context} />
+ </fieldset>
+ {isTreeSupported && !isSandbox && (
<div className="flex items-center justify-between px-2 py-1 border-b">
- {isTreeSupported && !isSandbox ? (
- <div className="flex gap-1">
- <button
- type="button"
- className={cn(
- "px-2 py-1 text-xs rounded",
- viewMode === "list"
- ? "bg-accent text-accent-foreground"
- : "text-muted-foreground hover:text-foreground",
- )}
- onClick={() => setUserViewMode("list")}
- >
- List
- </button>
- <button
- type="button"
- className={cn(
- "px-2 py-1 text-xs rounded",
- viewMode === "tree"
- ? "bg-accent text-accent-foreground"
- : "text-muted-foreground hover:text-foreground",
- )}
- onClick={() => setUserViewMode("tree")}
- >
- Tree
- </button>
- </div>
- ) : (
- <div />
- )}
+ <div className="flex gap-1">
+ <button
+ type="button"
+ className={cn(
+ "px-2 py-1 text-xs rounded",
+ viewMode === "list"
+ ? "bg-accent text-accent-foreground"
+ : "text-muted-foreground hover:text-foreground",
+ )}
+ onClick={() => setUserViewMode("list")}
+ >
+ List
+ </button>
+ <button
+ type="button"
+ className={cn(
+ "px-2 py-1 text-xs rounded",
+ viewMode === "tree"
+ ? "bg-accent text-accent-foreground"
+ : "text-muted-foreground hover:text-foreground",
+ )}
+ onClick={() => setUserViewMode("tree")}
+ >
+ Tree
+ </button>
+ </div>
<div className="flex items-center gap-2">
<div
className="items-center border px-2 py-0.5 text-xs transition-colors focus:outline-hidden focus:ring-2 focus:ring-ring focus:ring-offset-2 text-foreground rounded-sm text-ellipsis block overflow-hidden max-w-fit font-medium"
- title={scopeTitle}
+ title={scopeLabel}
>
{scopeLabel}
</div>
- {name && !isSandbox && (
+ {name && (
<span className="text-xs text-muted-foreground">
{name}
{version && ` v${version}`}
@@ -183,13 +180,12 @@ const PackagesPanel: React.FC = () => {
</div>
)}
{viewMode === "list" ? (
- <PackagesList packages={dependencies.list} onSuccess={refetch} />
+ <PackagesList packages={dependencies.list} />
) : (
<DependencyTree
tree={dependencies.tree}
error={error}
sandboxBackend={sandboxBackend}
- onSuccess={refetch}
/>
)}
</div>
@@ -200,8 +196,7 @@ export default PackagesPanel;
const InstallPackageForm: React.FC<{
context: PackageInstallationContext;
- onSuccess: () => void;
-}> = ({ onSuccess, context }) => {
+}> = ({ context }) => {
const [input, setInput] = React.useState("");
const { handleClick: openSettings } = useOpenSettingsToTab();
const isSandbox = context.kind === "sandbox";
@@ -222,7 +217,6 @@ const InstallPackageForm: React.FC<{
const { loading, handleInstallPackages } = useInstallPackages();
const onSuccessInstallPackages = () => {
- onSuccess();
setInput("");
};
@@ -363,9 +357,8 @@ const InstallPackageForm: React.FC<{
};
const PackagesList: React.FC<{
- onSuccess: () => void;
packages: { name: string; version: string }[];
-}> = ({ onSuccess, packages }) => {
+}> = ({ packages }) => {
// Sort case-insensitively so packages are strictly alphabetical
// regardless of capitalization (package managers sort inconsistently).
const sortedPackages = React.useMemo(
@@ -410,8 +403,8 @@ const PackagesList: React.FC<{
<TableCell>{item.name}</TableCell>
<TableCell>{item.version}</TableCell>
<TableCell className="flex justify-end">
- <UpgradeButton packageName={item.name} onSuccess={onSuccess} />
- <RemoveButton packageName={item.name} onSuccess={onSuccess} />
+ <UpgradeButton packageName={item.name} />
+ <RemoveButton packageName={item.name} />
</TableCell>
</TableRow>
))}
@@ -423,40 +416,14 @@ const PackagesList: React.FC<{
const UpgradeButton: React.FC<{
packageName: string;
tags?: { kind: string; value: string }[];
- onSuccess: () => void;
-}> = ({ packageName, tags, onSuccess }) => {
- const [loading, setLoading] = React.useState(false);
- const { addPackage } = useRequestClient();
-
- // Hide upgrade button in WASM
+}> = ({ packageName, tags }) => {
+ const { loading, run } = usePackageAction("upgrade", packageName, tags);
if (isWasm()) {
return null;
}
- const handleUpgradePackage = async () => {
- try {
- setLoading(true);
- const group = tags?.find((tag) => tag.kind === "group")?.value;
- const response = await addPackage({
- package: packageName,
- upgrade: true,
- group,
- });
- if (response.restartRequired) {
- showPackageRestartToast();
- } else if (response.success) {
- onSuccess();
- showUpgradePackageToast(packageName);
- } else {
- showUpgradePackageToast(packageName, response.error);
- }
- } finally {
- setLoading(false);
- }
- };
-
return (
- <PackageActionButton onClick={handleUpgradePackage} loading={loading}>
+ <PackageActionButton onClick={run} loading={loading}>
Upgrade
</PackageActionButton>
);
@@ -465,34 +432,14 @@ const UpgradeButton: React.FC<{
const RemoveButton: React.FC<{
packageName: string;
tags?: { kind: string; value: string }[];
- onSuccess: () => void;
-}> = ({ packageName, tags, onSuccess }) => {
- const [loading, setLoading] = React.useState(false);
- const { removePackage } = useRequestClient();
-
- const handleRemovePackage = async () => {
- try {
- setLoading(true);
- const group = tags?.find((tag) => tag.kind === "group")?.value;
- const response = await removePackage({
- package: packageName,
- group,
- });
- if (response.restartRequired) {
- showPackageRestartToast();
- } else if (response.success) {
- onSuccess();
- showRemovePackageToast(packageName);
- } else {
- showRemovePackageToast(packageName, response.error);
- }
- } finally {
- setLoading(false);
- }
- };
+}> = ({ packageName, tags }) => {
+ const { loading, run } = usePackageAction("remove", packageName, tags);
+ if (packageName.toLowerCase() === "marimo") {
+ return null;
+ }
return (
- <PackageActionButton onClick={handleRemovePackage} loading={loading}>
+ <PackageActionButton onClick={run} loading={loading}>
Remove
</PackageActionButton>
);
@@ -502,8 +449,7 @@ const DependencyTree: React.FC<{
tree: DependencyTreeNode | null;
error?: Error | null;
sandboxBackend: "uv" | "pixi" | null;
- onSuccess: () => void;
-}> = ({ tree, error, sandboxBackend, onSuccess }) => {
+}> = ({ tree, error, sandboxBackend }) => {
const [expandedNodes, setExpandedNodes] = React.useState<Set<string>>(
new Set(),
);
@@ -570,7 +516,6 @@ const DependencyTree: React.FC<{
isTopLevel={true}
expandedNodes={expandedNodes}
onToggle={toggleNode}
- onSuccess={onSuccess}
/>
</div>
))}
@@ -586,16 +531,7 @@ const DependencyTreeNode: React.FC<{
isTopLevel?: boolean;
expandedNodes: Set<string>;
onToggle: (nodeId: string) => void;
- onSuccess: () => void;
-}> = ({
- nodeId,
- node,
- level,
- isTopLevel = false,
- expandedNodes,
- onToggle,
- onSuccess,
-}) => {
+}> = ({ nodeId, node, level, isTopLevel = false, expandedNodes, onToggle }) => {
const hasChildren = node.dependencies.length > 0;
const isExpanded = expandedNodes.has(nodeId);
const indent = isTopLevel ? 0 : 16 + level * 16; // Top-level uses CSS padding, children use calculated indent
@@ -709,17 +645,9 @@ const DependencyTreeNode: React.FC<{
{/* Actions for top-level packages */}
{isTopLevel && (
<div className="flex gap-1 invisible group-hover:visible">
- <UpgradeButton
- packageName={node.name}
- tags={node.tags}
- onSuccess={onSuccess}
- />
+ <UpgradeButton packageName={node.name} tags={node.tags} />
- <RemoveButton
- packageName={node.name}
- tags={node.tags}
- onSuccess={onSuccess}
- />
+ <RemoveButton packageName={node.name} tags={node.tags} />
</div>
)}
</div>
@@ -736,7 +664,6 @@ const DependencyTreeNode: React.FC<{
isTopLevel={false}
expandedNodes={expandedNodes}
onToggle={onToggle}
- onSuccess={onSuccess}
/>
))}
</div>
diff --git a/frontend/src/components/editor/chrome/panels/sandbox-controller.tsx b/frontend/src/components/editor/chrome/panels/sandbox-controller.tsx
new file mode 100644
index 0000000000..632ad232ae
--- /dev/null
+++ b/frontend/src/components/editor/chrome/panels/sandbox-controller.tsx
@@ -0,0 +1,106 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { Suspense } from "react";
+import { Spinner } from "@/components/icons/spinner";
+import { Button } from "@/components/ui/button";
+import {
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from "@/components/ui/dialog";
+import { useSandboxController } from "@/core/packages/useSandboxController";
+import { LazyAnyLanguageCodeMirror } from "@/plugins/impl/code/LazyAnyLanguageCodeMirror";
+import { useTheme } from "@/theme/useTheme";
+import { Paths } from "@/utils/paths";
+import { SandboxErrorOutput } from "./sandbox-panel";
+
+export function SandboxController({
+ onReconnect,
+}: {
+ onReconnect: () => Promise<void>;
+}) {
+ const {
+ filename,
+ open,
+ setOpen,
+ draft,
+ setDraft,
+ dirty,
+ loading,
+ saving,
+ pending,
+ error,
+ diagnostic,
+ conflict,
+ loadManifest,
+ saveAndSync,
+ } = useSandboxController(onReconnect);
+ const { theme } = useTheme();
+ return (
+ <Dialog open={open} onOpenChange={setOpen}>
+ <DialogContent className="sm:max-w-xl grid-cols-1 max-h-[80vh] overflow-auto">
+ <DialogHeader>
+ <DialogTitle>Edit manifest</DialogTitle>
+ <DialogDescription className="font-mono text-xs">
+ {Paths.basename(filename ?? "Untitled notebook")} · script metadata
+ </DialogDescription>
+ </DialogHeader>
+ {draft !== null && !loading ? (
+ <Suspense fallback={<Spinner />}>
+ <LazyAnyLanguageCodeMirror
+ language="toml"
+ theme={theme}
+ value={draft}
+ onChange={setDraft}
+ editable={!pending}
+ height="260px"
+ basicSetup={{ lineNumbers: false, foldGutter: false }}
+ className="border rounded overflow-hidden"
+ aria-label="Notebook manifest"
+ />
+ </Suspense>
+ ) : (
+ !error && <Spinner />
+ )}
+ {diagnostic && <SandboxErrorOutput error={diagnostic} />}
+ {conflict && (
+ <Button variant="text" size="sm" onClick={loadManifest}>
+ Discard draft and reload manifest
+ </Button>
+ )}
+ <DialogFooter className="items-center sm:justify-between gap-3">
+ <span className="text-xs text-muted-foreground mr-auto">
+ {loading
+ ? "Loading…"
+ : dirty
+ ? "Unsaved changes"
+ : draft !== null
+ ? "Saved"
+ : ""}
+ </span>
+ <Button variant="text" size="sm" onClick={() => setOpen(false)}>
+ Close
+ </Button>
+ <Button
+ size="sm"
+ disabled={draft === null || pending}
+ onClick={saveAndSync}
+ >
+ {pending && <Spinner className="size-3 mr-2" />}
+ {loading
+ ? "Loading…"
+ : saving
+ ? "Saving…"
+ : pending
+ ? "Syncing…"
+ : dirty
+ ? "Save & sync"
+ : "Sync"}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ );
+}
diff --git a/frontend/src/components/editor/chrome/panels/sandbox-panel.tsx b/frontend/src/components/editor/chrome/panels/sandbox-panel.tsx
new file mode 100644
index 0000000000..07e14f5e2c
--- /dev/null
+++ b/frontend/src/components/editor/chrome/panels/sandbox-panel.tsx
@@ -0,0 +1,173 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useAtomValue } from "jotai";
+import {
+ AlertCircleIcon,
+ ChevronUpIcon,
+ FileCodeIcon,
+ RefreshCwIcon,
+} from "lucide-react";
+import { connectionNoticeAtom } from "@/core/network/connection-notice";
+import { Spinner } from "@/components/icons/spinner";
+import { Button } from "@/components/ui/button";
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { Tooltip } from "@/components/ui/tooltip";
+import { isConnectedAtom } from "@/core/network/connection";
+import {
+ sandboxActionsAtom,
+ sandboxAtom,
+ sandboxSyncAtom,
+} from "@/core/packages/sandbox-state";
+import { cn } from "@/utils/cn";
+
+export function SandboxErrorOutput({ error }: { error: string }) {
+ return (
+ <pre
+ tabIndex={0}
+ aria-label="Error details"
+ className="mt-3 p-3 rounded border bg-muted/30 text-xs text-muted-foreground whitespace-pre min-w-0 max-w-full max-h-52 overflow-auto"
+ >
+ {error}
+ </pre>
+ );
+}
+
+export function SandboxStartupPanel() {
+ const notice = useAtomValue(connectionNoticeAtom);
+ const sandbox = useAtomValue(sandboxAtom);
+ const actions = useAtomValue(sandboxActionsAtom);
+ if (!notice) {
+ return null;
+ }
+ return (
+ <div className="flex-1 min-h-0 overflow-auto p-4 text-sm">
+ <div
+ className={cn(
+ "flex items-center gap-2",
+ notice.pending
+ ? "text-muted-foreground"
+ : "font-medium text-(--red-11)",
+ )}
+ >
+ {notice.pending ? (
+ <Spinner className="size-4 shrink-0" aria-hidden={true} />
+ ) : (
+ <AlertCircleIcon className="size-4 shrink-0" aria-hidden={true} />
+ )}
+ <h2>{notice.title}</h2>
+ </div>
+ {!notice.pending && (
+ <>
+ <p className="mt-2 text-foreground">{notice.description}</p>
+ {notice.error && <SandboxErrorOutput error={notice.error} />}
+ <div className="flex items-center gap-2 mt-3">
+ <Button
+ variant="outline"
+ size="xs"
+ disabled={!actions || sandbox?.manifest == null}
+ onClick={() => actions?.editManifest()}
+ >
+ Edit manifest…
+ </Button>
+ <Button
+ variant="text"
+ size="xs"
+ disabled={!actions}
+ onClick={() => actions?.sync()}
+ >
+ Retry sync
+ </Button>
+ </div>
+ {sandbox?.manifest == null && (
+ <p className="mt-3 text-xs text-muted-foreground">
+ A manifest will be available once this new notebook starts.
+ </p>
+ )}
+ </>
+ )}
+ </div>
+ );
+}
+
+export function SandboxFooter() {
+ const sandbox = useAtomValue(sandboxAtom);
+ const connected = useAtomValue(isConnectedAtom);
+ const actions = useAtomValue(sandboxActionsAtom);
+ const operation = useAtomValue(sandboxSyncAtom);
+ const notice = useAtomValue(connectionNoticeAtom);
+ if (!sandbox?.backend) {
+ return null;
+ }
+ const pending = operation.pending || notice?.pending;
+ const status = operation.pending
+ ? "Syncing sandbox…"
+ : (notice?.title ?? (connected ? "Sandbox ready" : "Sandbox not started"));
+ return (
+ <div className="border-t p-1.5 shrink-0">
+ <DropdownMenu>
+ <Tooltip content={status}>
+ <DropdownMenuTrigger asChild={true}>
+ <button
+ type="button"
+ className="flex items-center gap-2 w-full px-2 py-1.5 rounded text-xs text-muted-foreground hover:bg-accent data-[state=open]:bg-accent"
+ aria-label={`${sandbox.backend} sandbox actions`}
+ >
+ <span
+ role="status"
+ aria-label={status}
+ className={cn(
+ "size-1.5 shrink-0 rounded-full",
+ pending
+ ? "bg-amber-500 motion-safe:animate-pulse"
+ : notice
+ ? "bg-(--red-9)"
+ : connected
+ ? "bg-emerald-500"
+ : "bg-muted-foreground",
+ )}
+ />
+ <span>{sandbox.backend} sandbox</span>
+ <span className="ml-auto">
+ {pending
+ ? operation.pending
+ ? "Syncing…"
+ : notice?.title
+ : ""}
+ </span>
+ <ChevronUpIcon className="size-3" />
+ </button>
+ </DropdownMenuTrigger>
+ </Tooltip>
+ <DropdownMenuContent
+ side="top"
+ align="start"
+ className="w-52"
+ sideOffset={8}
+ >
+ <DropdownMenuItem
+ disabled={pending || !actions}
+ onSelect={() => {
+ void actions?.sync();
+ }}
+ >
+ <RefreshCwIcon className="size-3.5 mr-2" />
+ Sync
+ </DropdownMenuItem>
+ <DropdownMenuItem
+ disabled={!actions || sandbox.manifest === null}
+ onSelect={() => {
+ void actions?.editManifest();
+ }}
+ >
+ <FileCodeIcon className="size-3.5 mr-2" />
+ Edit manifest…
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ </div>
+ );
+}
diff --git a/frontend/src/components/editor/chrome/wrapper/footer-items/backend-status.tsx b/frontend/src/components/editor/chrome/wrapper/footer-items/backend-status.tsx
index d2f79264f8..ff0b17fafa 100644
--- a/frontend/src/components/editor/chrome/wrapper/footer-items/backend-status.tsx
+++ b/frontend/src/components/editor/chrome/wrapper/footer-items/backend-status.tsx
@@ -42,7 +42,9 @@ export const BackendConnectionStatus: React.FC = () => {
const { isFetching, error, data, refetch } = useAsyncData(async () => {
// If the connection is not connected, return
if (!isAppConnected(connection)) {
- setConnectionStatus("disconnected");
+ setConnectionStatus(
+ isAppConnecting(connection) ? "connecting" : "disconnected",
+ );
return;
}
diff --git a/frontend/src/components/editor/header/__tests__/status.test.tsx b/frontend/src/components/editor/header/__tests__/status.test.tsx
index 84d90c9709..ad8acd215b 100644
--- a/frontend/src/components/editor/header/__tests__/status.test.tsx
+++ b/frontend/src/components/editor/header/__tests__/status.test.tsx
@@ -66,24 +66,12 @@ describe("StatusOverlay disconnect indicator", () => {
expect((button as HTMLButtonElement).disabled).toBe(true);
});
- it.each([
- [
- WebSocketClosedReason.KERNEL_STARTUP_ERROR,
- "Failed to start kernel sandbox",
- ],
- ])(
- "renders a disabled button for non-recoverable close reason %s",
- (code, reason) => {
- const onReconnect = vi.fn();
- const { getByTestId } = renderOverlay(
- { state: WebSocketState.CLOSED, code, reason },
- onReconnect,
- );
-
- const button = getByTestId("disconnected-indicator") as HTMLButtonElement;
- expect(button.disabled).toBe(true);
- fireEvent.click(button);
- expect(onReconnect).not.toHaveBeenCalled();
- },
- );
+ it("leaves editor startup failures to the inline notice", () => {
+ const { queryByTestId } = renderOverlay({
+ state: WebSocketState.CLOSED,
+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ reason: "Failed to start kernel sandbox",
+ });
+ expect(queryByTestId("disconnected-indicator")).not.toBeInTheDocument();
+ });
});
diff --git a/frontend/src/components/editor/header/status.tsx b/frontend/src/components/editor/header/status.tsx
index 56e1cbe62e..1471bd01c2 100644
--- a/frontend/src/components/editor/header/status.tsx
+++ b/frontend/src/components/editor/header/status.tsx
@@ -20,10 +20,12 @@ export const StatusOverlay: React.FC<{
onReconnect?: () => void;
}> = ({ connection, isRunning, onReconnect }) => {
const { mode } = useAtomValue(viewStateAtom);
- const isClosed = connection.state === WebSocketState.CLOSED;
+ const isClosed =
+ connection.state === WebSocketState.CLOSED &&
+ (mode === "read" ||
+ connection.code !== WebSocketClosedReason.KERNEL_STARTUP_ERROR);
const isOpen = connection.state === WebSocketState.OPEN;
- // Only KERNEL_DISCONNECTED is recoverable by a retry. KERNEL_STARTUP_ERROR
- // would deterministically fail the same way.
+ // Editor startup failures have their own recovery UI.
const canReconnect =
isClosed && connection.code === WebSocketClosedReason.KERNEL_DISCONNECTED;
diff --git a/frontend/src/components/editor/renderers/cell-array.tsx b/frontend/src/components/editor/renderers/cell-array.tsx
index 843deda29d..1badb7cb4b 100644
--- a/frontend/src/components/editor/renderers/cell-array.tsx
+++ b/frontend/src/components/editor/renderers/cell-array.tsx
@@ -43,10 +43,7 @@ import type { AppMode } from "../../../core/mode";
import { useHotkey } from "../../../hooks/useHotkey";
import { type Theme, useTheme } from "../../../theme/useTheme";
import { AddCellWithAI } from "../ai/add-cell-with-ai";
-import {
- ConnectingAlert,
- NotStartedConnectionAlert,
-} from "../alerts/connecting-alert";
+import { NotStartedConnectionAlert } from "../alerts/connecting-alert";
import { FloatingOutline } from "../chrome/panels/outline/floating-outline";
import { useChromeActions } from "../chrome/state";
import { Column } from "../columns/cell-column";
@@ -140,7 +137,6 @@ const CellArrayInternal: React.FC<CellArrayProps> = ({
<PackageAlert />
<StartupLogsAlert />
<StdinBlockingAlert />
- <ConnectingAlert />
<NotebookBanner width={appConfig.width} />
{/* Only show if not cells, otherwise running a single cell will start the connection */}
{cellIds.idLength === 0 && <NotStartedConnectionAlert />}
diff --git a/frontend/src/core/MarimoApp.tsx b/frontend/src/core/MarimoApp.tsx
index cdd6edd936..235dc09936 100644
--- a/frontend/src/core/MarimoApp.tsx
+++ b/frontend/src/core/MarimoApp.tsx
@@ -12,7 +12,6 @@ import { getInitialAppMode } from "@/core/mode";
import { CssVariables } from "@/theme/ThemeProvider";
import { reactLazyWithPreload } from "@/utils/lazy";
import { ErrorBoundary } from "../components/editor/boundary/ErrorBoundary";
-import { KernelStartupErrorModal } from "../components/editor/KernelStartupErrorModal";
import { TracebackModalContainer } from "../components/editor/TracebackModalContainer";
import { ModalProvider } from "../components/modal/ImperativeModal";
import { Toaster } from "../components/ui/toaster";
@@ -105,7 +104,6 @@ const Providers = memo(({ children }: PropsWithChildren) => {
{children}
<Toaster />
<TailwindIndicator />
- <KernelStartupErrorModal />
<TracebackModalContainer />
</ModalProvider>
</LocaleProvider>
diff --git a/frontend/src/core/edit-app.tsx b/frontend/src/core/edit-app.tsx
index ee06beb066..9c8c48cb07 100644
--- a/frontend/src/core/edit-app.tsx
+++ b/frontend/src/core/edit-app.tsx
@@ -9,7 +9,8 @@ import { useAtomValue, useSetAtom } from "jotai";
import { useEffect } from "react";
import { NotStartedConnectionAlert } from "@/components/editor/alerts/connecting-alert";
import { Controls } from "@/components/editor/controls/Controls";
-import { AppHeader } from "@/components/editor/header/app-header";
+import { SandboxController } from "@/components/editor/chrome/panels/sandbox-controller";
+import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";
import { FilenameForm } from "@/components/editor/header/filename-form";
import { MultiCellActionToolbar } from "@/components/editor/navigation/multi-cell-action-toolbar";
import { ViewerBanner } from "@/components/editor/viewer-banner";
@@ -158,6 +159,7 @@ export const EditApp: React.FC<AppProps> = ({
return (
<>
+ <SandboxController onReconnect={reconnect} />
<AppContainer
connection={connection}
isRunning={isRunning}
@@ -165,10 +167,9 @@ export const EditApp: React.FC<AppProps> = ({
onReconnect={reconnect}
>
<ViewerBanner />
- <AppHeader
- connection={connection}
+ <div
className={cn(
- "pt-4 sm:pt-12 pb-2 mb-4 print:hidden z-50",
+ "pt-4 sm:pt-12 pb-6 print:hidden z-50",
// Keep the header sticky when scrolling horizontally, for column mode
"sticky left-0",
)}
@@ -178,7 +179,9 @@ export const EditApp: React.FC<AppProps> = ({
<FilenameForm filename={filename} />
</div>
)}
- </AppHeader>
+ </div>
+
+ <ConnectionNotice appConfig={appConfig} onRetry={reconnect} />
{/* Don't render until we have a single cell. NotStartedConnectionAlert
still covers the "no remote runtime started" prompt. */}
diff --git a/frontend/src/core/errors/state.ts b/frontend/src/core/errors/state.ts
index 13c001d715..334b198291 100644
--- a/frontend/src/core/errors/state.ts
+++ b/frontend/src/core/errors/state.ts
@@ -7,8 +7,7 @@ import { generateUUID } from "@/utils/uuid";
import type { Banner } from "../kernel/messages";
/**
- * Atom for storing kernel startup error message.
- * When set to a non-null value, shows a modal with the error details.
+ * Full startup diagnostics, retained until a new connection attempt or readiness.
*/
export const kernelStartupErrorAtom = atom<string | null>(null);
diff --git a/frontend/src/core/islands/bootstrap.ts b/frontend/src/core/islands/bootstrap.ts
index 81c2620c3d..70c07d30d5 100644
--- a/frontend/src/core/islands/bootstrap.ts
+++ b/frontend/src/core/islands/bootstrap.ts
@@ -201,6 +201,7 @@ function handleMessage(
case "storage-download-ready":
case "secret-keys-result":
case "startup-logs":
+ case "startup-progress":
case "interrupted":
case "reconnected":
case "cache-cleared":
diff --git a/frontend/src/core/islands/bridge.ts b/frontend/src/core/islands/bridge.ts
index 6830a8b2be..c3f48cc750 100644
--- a/frontend/src/core/islands/bridge.ts
+++ b/frontend/src/core/islands/bridge.ts
@@ -370,6 +370,9 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {
addPackage = throwNotImplemented;
removePackage = throwNotImplemented;
getPackageList = throwNotImplemented;
+ getSandbox = throwNotImplemented;
+ updateManifest = throwNotImplemented;
+ syncSandbox = throwNotImplemented;
getDependencyTree = throwNotImplemented;
getRecentFiles = throwNotImplemented;
getWorkspaceFiles = throwNotImplemented;
diff --git a/frontend/src/core/network/connection-notice.ts b/frontend/src/core/network/connection-notice.ts
new file mode 100644
index 0000000000..7061ef398a
--- /dev/null
+++ b/frontend/src/core/network/connection-notice.ts
@@ -0,0 +1,84 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { atom } from "jotai";
+import { kernelStartupErrorAtom } from "@/core/errors/state";
+import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";
+import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";
+import { connectionAtom } from "./connection";
+
+export const connectionNoticeAtom = atom((get) => {
+ const connection = get(connectionAtom);
+ const backend = get(sandboxAtom)?.backend;
+ const sandbox = Boolean(backend);
+ const sync = get(sandboxSyncAtom);
+ if (
+ sandbox &&
+ (sync.pending || sync.error) &&
+ connection.state === WebSocketState.OPEN
+ ) {
+ return {
+ sandbox,
+ title: sync.pending ? "Syncing sandbox…" : "Sandbox sync failed",
+ description: sync.pending
+ ? "Applying the saved manifest to this notebook’s environment."
+ : "Review the error details, then try again.",
+ pending: sync.pending,
+ error: sync.error,
+ };
+ }
+ if (connection.state === WebSocketState.CONNECTING) {
+ const messages = {
+ "preparing-environment": {
+ title: backend
+ ? `Preparing ${backend} sandbox…`
+ : "Preparing environment…",
+ description:
+ "Getting this notebook’s Python environment ready. The first start can take a few minutes.",
+ },
+ "starting-kernel": {
+ title: "Starting notebook…",
+ description:
+ "The environment is prepared. Waiting for the Python kernel to connect to this notebook.",
+ },
+ reconnecting: {
+ title: "Reconnecting…",
+ description:
+ "The connection was interrupted. Your notebook and existing outputs stay visible while the kernel reconnects.",
+ },
+ };
+ return {
+ sandbox,
+ ...(connection.phase
+ ? messages[connection.phase]
+ : {
+ title: "Connecting…",
+ description: "Waiting for the notebook’s kernel to connect.",
+ }),
+ pending: true,
+ error: null,
+ };
+ }
+ if (connection.state === WebSocketState.CLOSED) {
+ const startupFailed =
+ connection.code === WebSocketClosedReason.KERNEL_STARTUP_ERROR;
+ const environmentFailed =
+ startupFailed && connection.phase === "preparing-environment";
+ return {
+ sandbox,
+ title: environmentFailed
+ ? "Sandbox setup failed"
+ : startupFailed
+ ? "Kernel failed to start"
+ : connection.reason,
+ description: environmentFailed
+ ? "The notebook can’t run yet."
+ : startupFailed
+ ? "The Python kernel could not start. Check the error details, then try again."
+ : "The connection to the notebook’s kernel was lost.",
+ pending: false,
+ error: startupFailed
+ ? (get(kernelStartupErrorAtom) ?? connection.reason)
+ : null,
+ };
+ }
+ return null;
+});
diff --git a/frontend/src/core/network/requests-lazy.ts b/frontend/src/core/network/requests-lazy.ts
index 8a30594d18..25ac2c2d64 100644
--- a/frontend/src/core/network/requests-lazy.ts
+++ b/frontend/src/core/network/requests-lazy.ts
@@ -93,6 +93,9 @@ const ACTIONS: Record<keyof AllRequests, Action> = {
saveUserConfig: "throwError",
sendShutdown: "throwError",
getPackageList: "throwError",
+ getSandbox: "serverOnly",
+ updateManifest: "serverOnly",
+ syncSandbox: "serverOnly",
getDependencyTree: "throwError",
addPackage: "throwError",
removePackage: "throwError",
diff --git a/frontend/src/core/network/requests-network.ts b/frontend/src/core/network/requests-network.ts
index 47de80a1de..3a17562b1c 100644
--- a/frontend/src/core/network/requests-network.ts
+++ b/frontend/src/core/network/requests-network.ts
@@ -532,6 +532,18 @@ export function createNetworkRequests(): EditRequests & RunRequests {
})
.then(handleResponseReturnNull);
},
+ getSandbox: (request) =>
+ getClient()
+ .POST("/api/packages/sandbox", { body: request, params: getParams() })
+ .then(handleResponse),
+ updateManifest: (request) =>
+ getClient()
+ .POST("/api/packages/manifest", { body: request, params: getParams() })
+ .then(handleResponse),
+ syncSandbox: (request) =>
+ getClient()
+ .POST("/api/packages/sync", { body: request, params: getParams() })
+ .then(handleResponse),
addPackage: (request) => {
return getClient()
.POST("/api/packages/add", {
diff --git a/frontend/src/core/network/requests-static.ts b/frontend/src/core/network/requests-static.ts
index 901f08d268..6cf6350232 100644
--- a/frontend/src/core/network/requests-static.ts
+++ b/frontend/src/core/network/requests-static.ts
@@ -98,6 +98,9 @@ export function createStaticRequests(): EditRequests & RunRequests {
addPackage: throwNotInEditMode,
removePackage: throwNotInEditMode,
getPackageList: throwNotInEditMode,
+ getSandbox: throwNotInEditMode,
+ updateManifest: throwNotInEditMode,
+ syncSandbox: throwNotInEditMode,
getDependencyTree: throwNotInEditMode,
listSecretKeys: throwNotInEditMode,
writeSecret: throwNotInEditMode,
diff --git a/frontend/src/core/network/requests-toasting.tsx b/frontend/src/core/network/requests-toasting.tsx
index c9397269cf..f686da15bc 100644
--- a/frontend/src/core/network/requests-toasting.tsx
+++ b/frontend/src/core/network/requests-toasting.tsx
@@ -79,6 +79,9 @@ export function createErrorToastingRequests(
addPackage: "Failed to add package",
removePackage: "Failed to remove package",
getPackageList: "Failed to get package list",
+ getSandbox: "",
+ updateManifest: "",
+ syncSandbox: "",
getDependencyTree: "Failed to get dependency tree",
listSecretKeys: "Failed to fetch secrets",
writeSecret: "Failed to write secret",
diff --git a/frontend/src/core/network/resolve.ts b/frontend/src/core/network/resolve.ts
index 2a62903e74..9c0d26c3db 100644
--- a/frontend/src/core/network/resolve.ts
+++ b/frontend/src/core/network/resolve.ts
@@ -1,4 +1,5 @@
/* Copyright 2026 Marimo. All rights reserved. */
+import { withPackageInvalidation } from "../packages/package-data";
import { getRuntimeManager } from "../runtime/config";
import { isStaticNotebook } from "../static/static-state";
import { PyodideBridge } from "../wasm/bridge";
@@ -20,5 +21,5 @@ export function resolveRequestClient(): EditRequests & RunRequests {
getRuntimeManager(),
);
}
- return createErrorToastingRequests(base);
+ return withPackageInvalidation(createErrorToastingRequests(base));
}
diff --git a/frontend/src/core/network/types.ts b/frontend/src/core/network/types.ts
index 4cb233d666..78208f0c1c 100644
--- a/frontend/src/core/network/types.ts
+++ b/frontend/src/core/network/types.ts
@@ -69,6 +69,10 @@ export type ListPackagesResponse = schemas["ListPackagesResponse"];
export type DependencyTreeResponse = schemas["DependencyTreeResponse"];
export type DependencyTreeNode = schemas["DependencyTreeNode"];
+export type SandboxRequest = schemas["SandboxRequest"];
+export type SandboxResponse = schemas["SandboxResponse"];
+export type UpdateManifestRequest = schemas["UpdateManifestRequest"];
+export type SyncSandboxResponse = schemas["SyncSandboxResponse"];
export type PackageOperationResponse = schemas["PackageOperationResponse"];
export type InstantiateNotebookRequest = schemas["InstantiateNotebookRequest"];
export type MarimoConfig = schemas["MarimoConfig"];
@@ -246,6 +250,9 @@ export interface EditRequests {
autoExportAsMarkdown: (request: AutoExportAsMarkdownRequest) => Promise<null>;
autoExportAsIPYNB: (request: AutoExportAsIPYNBRequest) => Promise<null>;
updateCellOutputs: (request: UpdateCellOutputsRequest) => Promise<null>;
+ getSandbox: (request: SandboxRequest) => Promise<SandboxResponse>;
+ updateManifest: (request: UpdateManifestRequest) => Promise<SandboxResponse>;
+ syncSandbox: (request: SandboxRequest) => Promise<SyncSandboxResponse>;
// Package requests
getPackageList: () => Promise<ListPackagesResponse>;
getDependencyTree: () => Promise<DependencyTreeResponse>;
diff --git a/frontend/src/core/packages/__tests__/usePackageAction.test.tsx b/frontend/src/core/packages/__tests__/usePackageAction.test.tsx
new file mode 100644
index 0000000000..8bb41da40d
--- /dev/null
+++ b/frontend/src/core/packages/__tests__/usePackageAction.test.tsx
@@ -0,0 +1,129 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, renderHook } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MockRequestClient } from "@/__mocks__/requests";
+import { toast } from "@/components/ui/use-toast";
+import { requestClientAtom } from "@/core/network/requests";
+import type { PackageOperationResponse } from "@/core/network/types";
+import { usePackageAction } from "../usePackageAction";
+
+vi.mock("@/components/ui/use-toast", () => ({ toast: vi.fn() }));
+
+function setup(action: "upgrade" | "remove") {
+ const client = MockRequestClient.create();
+ const store = createStore();
+ store.set(requestClientAtom, client);
+ return {
+ request: vi.mocked(
+ action === "upgrade" ? client.addPackage : client.removePackage,
+ ),
+ ...renderHook(
+ () =>
+ usePackageAction(action, "numpy", [{ kind: "group", value: "dev" }]),
+ {
+ wrapper: ({ children }) => (
+ <Provider store={store}>{children}</Provider>
+ ),
+ },
+ ),
+ };
+}
+
+describe("usePackageAction", () => {
+ beforeEach(() => vi.clearAllMocks());
+
+ it.each([
+ { action: "upgrade", title: "Package upgraded", upgrade: true },
+ { action: "remove", title: "Package removed" },
+ ] as const)(
+ "preserves dependency groups and prevents duplicate $action requests",
+ async ({ action, title, ...options }) => {
+ const { result, request } = setup(action);
+ const { promise, resolve } =
+ Promise.withResolvers<PackageOperationResponse>();
+ request.mockReturnValue(promise);
+ let pending: Promise<void>;
+ act(() => {
+ pending = result.current.run();
+ });
+ expect(result.current.loading).toBe(true);
+ await act(async () => {
+ await result.current.run();
+ });
+ expect(request).toHaveBeenCalledExactlyOnceWith({
+ package: "numpy",
+ group: "dev",
+ ...options,
+ });
+ await act(async () => {
+ resolve({ success: true });
+ await pending;
+ });
+ expect(result.current.loading).toBe(false);
+ expect(toast).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({ title }),
+ );
+ },
+ );
+
+ it("reports saved changes requiring a restart without claiming success", async () => {
+ const { result, request } = setup("upgrade");
+ request.mockResolvedValue({ success: false, restartRequired: true });
+ await act(async () => {
+ await result.current.run();
+ });
+ expect(toast).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({
+ title: "Changes saved — restart required",
+ }),
+ );
+ });
+
+ it.each([
+ {
+ response: { success: false, error: "resolver failed" },
+ description: "resolver failed",
+ },
+ { response: { success: false }, description: expect.any(String) },
+ ])(
+ "reports failed responses as errors: $response",
+ async ({ response, description }) => {
+ const { result, request } = setup("remove");
+ request.mockResolvedValue(response);
+ await act(async () => {
+ await result.current.run();
+ });
+ expect(toast).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({
+ title: "Failed to remove package",
+ description,
+ variant: "danger",
+ }),
+ );
+ },
+ );
+
+ it("reports request errors and allows a retry", async () => {
+ const { result, request } = setup("remove");
+ request.mockRejectedValueOnce(new Error("offline"));
+ await act(async () => {
+ await result.current.run();
+ });
+ expect(toast).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({
+ title: "Failed to remove package",
+ description: "offline",
+ variant: "danger",
+ }),
+ );
+ expect(result.current.loading).toBe(false);
+ request.mockResolvedValue({ success: true });
+ await act(async () => {
+ await result.current.run();
+ });
+ expect(toast).toHaveBeenLastCalledWith(
+ expect.objectContaining({ title: "Package removed" }),
+ );
+ });
+});
diff --git a/frontend/src/core/packages/__tests__/useSandboxController.test.tsx b/frontend/src/core/packages/__tests__/useSandboxController.test.tsx
new file mode 100644
index 0000000000..7343e85119
--- /dev/null
+++ b/frontend/src/core/packages/__tests__/useSandboxController.test.tsx
@@ -0,0 +1,165 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { Provider } from "jotai";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MockRequestClient } from "@/__mocks__/requests";
+import { kernelStartupErrorAtom } from "@/core/errors/state";
+import { connectionAtom } from "@/core/network/connection";
+import { requestClientAtom } from "@/core/network/requests";
+import type {
+ SandboxResponse,
+ SyncSandboxResponse,
+} from "@/core/network/types";
+import { filenameAtom } from "@/core/saving/file-state";
+import { store } from "@/core/state/jotai";
+import { WebSocketState } from "@/core/websocket/types";
+import { HTTPError } from "@/utils/errors";
+import { packageDataVersionAtom } from "../package-data";
+import {
+ sandboxActionsAtom,
+ sandboxAtom,
+ sandboxSyncAtom,
+} from "../sandbox-state";
+import { useSandboxController } from "../useSandboxController";
+
+vi.mock("../toast-components", () => ({
+ showPackageRestartToast: vi.fn(),
+ showSandboxSyncToast: vi.fn(),
+}));
+
+const manifest = 'dependencies = ["numpy"]';
+const sandbox: SandboxResponse = {
+ backend: "uv",
+ manifest,
+ filename: "notebook.py",
+};
+
+beforeEach(() => {
+ store.set(sandboxAtom, null);
+ store.set(sandboxSyncAtom, { pending: false, error: null });
+ store.set(sandboxActionsAtom, null);
+ store.set(connectionAtom, { state: WebSocketState.OPEN });
+ store.set(kernelStartupErrorAtom, null);
+ store.set(filenameAtom, "notebook.py");
+ store.set(packageDataVersionAtom, 0);
+});
+
+function setup() {
+ const client = MockRequestClient.create({
+ getSandbox: vi.fn().mockResolvedValue(sandbox),
+ updateManifest: vi.fn(async ({ contents }) => ({
+ ...sandbox,
+ manifest: contents,
+ })),
+ syncSandbox: vi.fn().mockResolvedValue({ success: true, reconnect: false }),
+ });
+ store.set(requestClientAtom, client);
+ const reconnect = vi.fn<() => Promise<void>>().mockResolvedValue(undefined);
+ return {
+ client,
+ reconnect,
+ ...renderHook(() => useSandboxController(reconnect), {
+ wrapper: ({ children }) => <Provider store={store}>{children}</Provider>,
+ }),
+ };
+}
+
+describe("useSandboxController", () => {
+ it("keeps a conflicting draft across closing and only discards it on explicit reload", async () => {
+ const { result, client } = setup();
+ vi.mocked(client.updateManifest).mockRejectedValue(
+ new HTTPError(409, "Conflict", { detail: "Manifest changed on disk" }),
+ );
+ await act(async () => {
+ await store.get(sandboxActionsAtom)?.editManifest();
+ });
+ act(() => result.current.setDraft("dependencies = []"));
+ await act(async () => {
+ await result.current.saveAndSync();
+ });
+ expect(client.updateManifest).toHaveBeenCalledExactlyOnceWith({
+ fileKey: "notebook.py",
+ previous: manifest,
+ contents: "dependencies = []",
+ });
+ expect(result.current).toMatchObject({
+ open: true,
+ draft: "dependencies = []",
+ dirty: true,
+ conflict: true,
+ diagnostic: "Manifest changed on disk",
+ pending: false,
+ });
+ expect(client.syncSandbox).not.toHaveBeenCalled();
+ act(() => result.current.setOpen(false));
+ await act(async () => {
+ await store.get(sandboxActionsAtom)?.editManifest();
+ });
+ expect(result.current.draft).toBe("dependencies = []");
+ await act(async () => {
+ await result.current.loadManifest();
+ });
+ expect(result.current).toMatchObject({
+ draft: manifest,
+ dirty: false,
+ conflict: false,
+ diagnostic: null,
+ });
+ });
+
+ it("shares sync progress across callers and refreshes packages without reconnecting", async () => {
+ const { client, reconnect } = setup();
+ const { promise, resolve } = Promise.withResolvers<SyncSandboxResponse>();
+ vi.mocked(client.syncSandbox).mockReturnValue(promise);
+ const actions = store.get(sandboxActionsAtom)!;
+ let pending: Promise<boolean>;
+ act(() => {
+ pending = actions.sync();
+ });
+ expect(store.get(sandboxSyncAtom)).toEqual({ pending: true, error: null });
+ await act(async () => {
+ expect(await actions.sync()).toBe(false);
+ });
+ expect(client.syncSandbox).toHaveBeenCalledTimes(1);
+ await act(async () => {
+ resolve({ success: true, reconnect: false });
+ expect(await pending).toBe(true);
+ });
+ expect(store.get(sandboxSyncAtom)).toEqual({ pending: false, error: null });
+ expect(store.get(packageDataVersionAtom)).toBe(1);
+ expect(reconnect).not.toHaveBeenCalled();
+ });
+
+ it("reports sync failure and clears it when retrying", async () => {
+ const { client } = setup();
+ const actions = store.get(sandboxActionsAtom)!;
+ vi.mocked(client.syncSandbox).mockRejectedValueOnce(new Error("offline"));
+ await act(async () => {
+ expect(await actions.sync()).toBe(false);
+ });
+ expect(store.get(sandboxSyncAtom)).toEqual({
+ pending: false,
+ error: "offline",
+ });
+ await act(async () => {
+ expect(await actions.sync()).toBe(true);
+ });
+ expect(store.get(sandboxSyncAtom)).toEqual({ pending: false, error: null });
+ });
+
+ it("ignores stale metadata after a filename change and unregisters actions on unmount", async () => {
+ const { client, unmount } = setup();
+ await waitFor(() => expect(store.get(sandboxAtom)).toEqual(sandbox));
+ const { promise, resolve } = Promise.withResolvers<SandboxResponse>();
+ vi.mocked(client.getSandbox).mockReturnValueOnce(promise);
+ act(() => store.set(filenameAtom, "old.py"));
+ const current = { ...sandbox, filename: "current.py" };
+ vi.mocked(client.getSandbox).mockResolvedValue(current);
+ act(() => store.set(filenameAtom, "current.py"));
+ await waitFor(() => expect(store.get(sandboxAtom)).toEqual(current));
+ await act(async () => resolve({ ...sandbox, filename: "old.py" }));
+ expect(store.get(sandboxAtom)).toEqual(current);
+ unmount();
+ expect(store.get(sandboxActionsAtom)).toBeNull();
+ });
+});
diff --git a/frontend/src/core/packages/package-data.ts b/frontend/src/core/packages/package-data.ts
new file mode 100644
index 0000000000..1bdb655509
--- /dev/null
+++ b/frontend/src/core/packages/package-data.ts
@@ -0,0 +1,35 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { atom } from "jotai";
+import type {
+ EditRequests,
+ PackageOperationResponse,
+ RunRequests,
+} from "@/core/network/types";
+import { store } from "@/core/state/jotai";
+
+export const packageDataVersionAtom = atom(0);
+export function invalidatePackageData() {
+ store.set(packageDataVersionAtom, (version) => version + 1);
+}
+
+/** Refresh package consumers regardless of which UI initiated a mutation. */
+export function withPackageInvalidation(
+ client: EditRequests & RunRequests,
+): EditRequests & RunRequests {
+ function invalidateAfter<Request, Response extends PackageOperationResponse>(
+ request: (body: Request) => Promise<Response>,
+ ) {
+ return async (body: Request) => {
+ const result = await request(body);
+ if (result.success || result.restartRequired) {
+ invalidatePackageData();
+ }
+ return result;
+ };
+ }
+ return {
+ ...client,
+ addPackage: invalidateAfter(client.addPackage),
+ removePackage: invalidateAfter(client.removePackage),
+ };
+}
diff --git a/frontend/src/core/packages/sandbox-state.ts b/frontend/src/core/packages/sandbox-state.ts
new file mode 100644
index 0000000000..dbf66d26e5
--- /dev/null
+++ b/frontend/src/core/packages/sandbox-state.ts
@@ -0,0 +1,15 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { atom } from "jotai";
+import type { SandboxResponse } from "@/core/network/types";
+
+export const sandboxAtom = atom<SandboxResponse | null>(null);
+export const sandboxSyncAtom = atom<{ pending: boolean; error: string | null }>(
+ {
+ pending: false,
+ error: null,
+ },
+);
+export const sandboxActionsAtom = atom<{
+ sync: () => Promise<boolean>;
+ editManifest: () => Promise<void>;
+} | null>(null);
diff --git a/frontend/src/core/packages/toast-components.tsx b/frontend/src/core/packages/toast-components.tsx
index 04bf76f252..a8ff6c7023 100644
--- a/frontend/src/core/packages/toast-components.tsx
+++ b/frontend/src/core/packages/toast-components.tsx
@@ -29,6 +29,17 @@ export const showPackageRestartToast = () => {
});
};
+export const showSandboxSyncToast = () => {
+ toast({
+ title: "Sandbox environment synced",
+ description: (
+ <div className="text-xs text-muted-foreground">
+ Some Python packages may require a kernel restart to see changes.
+ </div>
+ ),
+ });
+};
+
export const showAddPackageToast = (
packageName: string | string[],
error?: string | null,
diff --git a/frontend/src/core/packages/useInstallPackage.ts b/frontend/src/core/packages/useInstallPackage.ts
index 9d25188c27..28ff085ff8 100644
--- a/frontend/src/core/packages/useInstallPackage.ts
+++ b/frontend/src/core/packages/useInstallPackage.ts
@@ -37,10 +37,10 @@ export function useInstallPackages(): {
showPackageRestartToast();
} else if (response.success) {
showAddPackageToast(packages);
+ onSuccess?.();
} else {
showAddPackageToast(packages, response.error);
}
- onSuccess?.();
} catch (error) {
Logger.error(error);
} finally {
diff --git a/frontend/src/core/packages/usePackageAction.ts b/frontend/src/core/packages/usePackageAction.ts
new file mode 100644
index 0000000000..7f6c49b453
--- /dev/null
+++ b/frontend/src/core/packages/usePackageAction.ts
@@ -0,0 +1,51 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useRef, useState } from "react";
+import useEvent from "react-use-event-hook";
+import { useRequestClient } from "@/core/network/requests";
+import type { DependencyTreeNode } from "@/core/network/types";
+import { prettyError } from "@/utils/errors";
+import {
+ showPackageRestartToast,
+ showRemovePackageToast,
+ showUpgradePackageToast,
+} from "./toast-components";
+
+/** Shared mutation lifecycle for package actions in both list and tree views. */
+export function usePackageAction(
+ action: "upgrade" | "remove",
+ packageName: string,
+ tags?: DependencyTreeNode["tags"],
+) {
+ const { addPackage, removePackage } = useRequestClient();
+ const [loading, setLoading] = useState(false);
+ const inFlight = useRef(false);
+ const run = useEvent(async () => {
+ if (inFlight.current) {
+ return;
+ }
+ inFlight.current = true;
+ setLoading(true);
+ const showResult =
+ action === "upgrade" ? showUpgradePackageToast : showRemovePackageToast;
+ try {
+ const group = tags?.find((tag) => tag.kind === "group")?.value;
+ const request = { package: packageName, group };
+ const response = await (action === "upgrade"
+ ? addPackage({ ...request, upgrade: true })
+ : removePackage(request));
+ if (response.restartRequired) {
+ showPackageRestartToast();
+ } else if (response.success) {
+ showResult(packageName);
+ } else {
+ showResult(packageName, response.error || "Package operation failed.");
+ }
+ } catch (error) {
+ showResult(packageName, prettyError(error));
+ } finally {
+ inFlight.current = false;
+ setLoading(false);
+ }
+ });
+ return { loading, run };
+}
diff --git a/frontend/src/core/packages/usePackageDependencies.ts b/frontend/src/core/packages/usePackageDependencies.ts
new file mode 100644
index 0000000000..60b240e550
--- /dev/null
+++ b/frontend/src/core/packages/usePackageDependencies.ts
@@ -0,0 +1,22 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useAtomValue } from "jotai";
+import { useResolvedMarimoConfig } from "@/core/config/config";
+import { useRequestClient } from "@/core/network/requests";
+import { useAsyncData } from "@/hooks/useAsyncData";
+import { packageDataVersionAtom } from "./package-data";
+
+/** Load the available package views and refresh them after package mutations. */
+export function usePackageDependencies() {
+ const packageDataVersion = useAtomValue(packageDataVersionAtom);
+ const [config] = useResolvedMarimoConfig();
+ const packageManager = config.package_management.manager;
+ const { getDependencyTree, getPackageList } = useRequestClient();
+
+ return useAsyncData(async () => {
+ const { context, tree } = await getDependencyTree();
+ // Both sandbox endpoints inspect the same environment; only fetch it once.
+ const list =
+ context.kind === "sandbox" ? [] : (await getPackageList()).packages;
+ return { list, context, tree };
+ }, [getDependencyTree, getPackageList, packageManager, packageDataVersion]);
+}
diff --git a/frontend/src/core/packages/useSandboxController.ts b/frontend/src/core/packages/useSandboxController.ts
new file mode 100644
index 0000000000..059cbc8e1d
--- /dev/null
+++ b/frontend/src/core/packages/useSandboxController.ts
@@ -0,0 +1,188 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useAtom, useAtomValue, useSetAtom } from "jotai";
+import { useEffect, useRef, useState } from "react";
+import useEvent from "react-use-event-hook";
+import { kernelStartupErrorAtom } from "@/core/errors/state";
+import { connectionAtom } from "@/core/network/connection";
+import { useRequestClient } from "@/core/network/requests";
+import { useFilename } from "@/core/saving/filename";
+import { waitFor } from "@/core/state/jotai";
+import { isWasm } from "@/core/wasm/utils";
+import { WebSocketState } from "@/core/websocket/types";
+import { HTTPError, prettyError } from "@/utils/errors";
+import { invalidatePackageData } from "./package-data";
+import {
+ sandboxActionsAtom,
+ sandboxAtom,
+ sandboxSyncAtom,
+} from "./sandbox-state";
+import {
+ showPackageRestartToast,
+ showSandboxSyncToast,
+} from "./toast-components";
+
+/** Mount once with the editor so manifest drafts survive closing Packages. */
+export function useSandboxController(onReconnect: () => Promise<void>) {
+ const requests = useRequestClient();
+ const filename = useFilename();
+ const connection = useAtomValue(connectionAtom);
+ const startupError = useAtomValue(kernelStartupErrorAtom);
+ const setSandbox = useSetAtom(sandboxAtom);
+ const [operation, setOperation] = useAtom(sandboxSyncAtom);
+ const setActions = useSetAtom(sandboxActionsAtom);
+ const [open, setOpen] = useState(false);
+ const [document, setDocument] = useState<{
+ original: string;
+ draft: string;
+ } | null>(null);
+ const [error, setError] = useState<string | null>(null);
+ const [saving, setSaving] = useState(false);
+ const [loading, setLoading] = useState(false);
+ const [conflict, setConflict] = useState(false);
+ const inFlight = useRef(false);
+ const dirty = document !== null && document.original !== document.draft;
+
+ useEffect(() => {
+ if (isWasm()) {
+ return;
+ }
+ let cancelled = false;
+ requests
+ .getSandbox({ fileKey: filename })
+ .then((value) => {
+ if (!cancelled) {
+ setSandbox(value);
+ }
+ })
+ .catch(() => {
+ /* A connection error is already shown by the editor. */
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [requests, filename, connection.state, setSandbox]);
+
+ const sync = useEvent(async () => {
+ if (inFlight.current || connection.state === WebSocketState.CONNECTING) {
+ return false;
+ }
+ inFlight.current = true;
+ setOperation((value) => ({ ...value, pending: true, error: null }));
+ try {
+ const result = await requests.syncSandbox({ fileKey: filename });
+ if (result.restartRequired) {
+ showPackageRestartToast();
+ }
+ if (!result.success) {
+ throw new Error(result.error ?? "Sandbox sync failed.");
+ }
+ if (result.reconnect) {
+ await onReconnect();
+ const status = await waitFor(
+ connectionAtom,
+ (value) =>
+ value.state === WebSocketState.OPEN ||
+ value.state === WebSocketState.CLOSED,
+ );
+ if (status.state === WebSocketState.CLOSED) {
+ return false;
+ }
+ }
+ if (!result.reconnect) {
+ invalidatePackageData();
+ }
+ showSandboxSyncToast();
+ return true;
+ } catch (cause) {
+ setOperation((value) => ({ ...value, error: prettyError(cause) }));
+ return false;
+ } finally {
+ inFlight.current = false;
+ setOperation((value) => ({ ...value, pending: false }));
+ }
+ });
+
+ const loadManifest = useEvent(async () => {
+ setLoading(true);
+ setError(null);
+ setConflict(false);
+ try {
+ const result = await requests.getSandbox({ fileKey: filename });
+ setSandbox(result);
+ if (result.manifest === null) {
+ throw new Error("No notebook manifest is available yet.");
+ }
+ setDocument({ original: result.manifest, draft: result.manifest });
+ } catch (cause) {
+ setError(prettyError(cause));
+ } finally {
+ setLoading(false);
+ }
+ });
+
+ const editManifest = useEvent(async () => {
+ setOpen(true);
+ if (!dirty) {
+ await loadManifest();
+ }
+ });
+
+ useEffect(() => {
+ setActions({ sync, editManifest });
+ return () => {
+ setActions(null);
+ };
+ }, [sync, editManifest, setActions]);
+
+ const saveAndSync = async () => {
+ if (!document || loading || saving || operation.pending) {
+ return;
+ }
+ setSaving(true);
+ setError(null);
+ try {
+ if (dirty) {
+ const result = await requests.updateManifest({
+ fileKey: filename,
+ contents: document.draft,
+ previous: document.original,
+ });
+ setSandbox(result);
+ if (result.manifest !== null) {
+ setDocument({ original: result.manifest, draft: result.manifest });
+ }
+ }
+ if (await sync()) {
+ setOpen(false);
+ }
+ } catch (cause) {
+ setError(prettyError(cause));
+ setConflict(cause instanceof HTTPError && cause.status === 409);
+ } finally {
+ setSaving(false);
+ }
+ };
+ const pending =
+ saving ||
+ loading ||
+ operation.pending ||
+ connection.state === WebSocketState.CONNECTING;
+ const diagnostic = error ?? operation.error ?? startupError;
+ return {
+ filename,
+ open,
+ setOpen,
+ draft: document?.draft ?? null,
+ setDraft: (draft: string) =>
+ setDocument((value) => value && { ...value, draft }),
+ dirty,
+ loading,
+ saving,
+ pending,
+ error,
+ diagnostic,
+ conflict,
+ loadManifest,
+ saveAndSync,
+ };
+}
diff --git a/frontend/src/core/run-app.tsx b/frontend/src/core/run-app.tsx
index 8786ab48dc..14dd778dc2 100644
--- a/frontend/src/core/run-app.tsx
+++ b/frontend/src/core/run-app.tsx
@@ -3,6 +3,7 @@
import { atom, useAtomValue } from "jotai";
import { ArrowLeftIcon } from "lucide-react";
import { useEffect } from "react";
+import { KernelStartupErrorModal } from "@/components/editor/KernelStartupErrorModal";
import { AppContainer } from "@/components/editor/app-container";
import { AppHeader } from "@/components/editor/header/app-header";
import { ProgressiveBoundary } from "@/components/lifecycle/ProgressiveBoundary";
@@ -78,6 +79,7 @@ export const RunApp: React.FC<AppProps> = ({ appConfig, hideHeader }) => {
width={appConfig.width}
onReconnect={reconnect}
>
+ <KernelStartupErrorModal />
<AppHeader
connection={connection}
className={hideHeader ? "hidden" : "sm:pt-8"}
diff --git a/frontend/src/core/wasm/bridge.ts b/frontend/src/core/wasm/bridge.ts
index 0d375ae20a..d272006c55 100644
--- a/frontend/src/core/wasm/bridge.ts
+++ b/frontend/src/core/wasm/bridge.ts
@@ -640,6 +640,17 @@ export class PyodideBridge implements RunRequests, EditRequests {
return response;
};
+ getSandbox: EditRequests["getSandbox"] = async () => ({
+ backend: null,
+ manifest: null,
+ filename: null,
+ });
+ updateManifest: EditRequests["updateManifest"] = async () => {
+ throw new Error("Sandboxes are not supported in WebAssembly");
+ };
+ syncSandbox: EditRequests["syncSandbox"] = async () => {
+ throw new Error("Sandboxes are not supported in WebAssembly");
+ };
getDependencyTree: EditRequests["getDependencyTree"] = async () => {
// WASM doesn't support dependency trees yet
return {
diff --git a/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx b/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx
index 368fa97c50..523deb3f90 100644
--- a/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx
+++ b/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx
@@ -1,11 +1,25 @@
/* Copyright 2026 Marimo. All rights reserved. */
// @vitest-environment jsdom
-import { act, renderHook } from "@testing-library/react";
+import {
+ act,
+ fireEvent,
+ render,
+ renderHook,
+ screen,
+} from "@testing-library/react";
import { createStore, Provider as JotaiProvider } from "jotai";
import type React from "react";
import { ErrorBoundary } from "react-error-boundary";
-import { beforeEach, describe, expect, it, type Mock, vi } from "vitest";
+import {
+ afterEach,
+ beforeEach,
+ describe,
+ expect,
+ it,
+ type Mock,
+ vi,
+} from "vitest";
vi.mock("@/core/websocket/useWebSocket", async () => {
const actual =
@@ -26,6 +40,13 @@ vi.mock("@/core/runtime/config", async () => {
};
});
+import { MockNotebook } from "@/__mocks__/notebook";
+import { cellId } from "@/__tests__/branded";
+import { notebookAtom } from "@/core/cells/cells";
+import { AppConfigSchema } from "@/core/config/config-schema";
+import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";
+import { kernelStartupErrorAtom } from "@/core/errors/state";
+import type { NotificationPayload } from "@/core/kernel/messages";
import { useRuntimeManager } from "@/core/runtime/config";
import { initialRunCompletedAtom } from "../../kernel/state";
import { connectionAtom } from "../../network/connection";
@@ -188,3 +209,192 @@ describe("useMarimoKernelConnection messages", () => {
expect(store.get(initialRunCompletedAtom)).toBe(true);
});
});
+
+it.each(["kernel-ready", "reconnected"])(
+ "waits for %s before marking the session connected",
+ async (op) => {
+ const store = createStore();
+ store.set(connectionAtom, { state: WebSocketState.CONNECTING });
+ vi.mocked(useConnectionTransport).mockClear();
+ vi.mocked(useConnectionTransport).mockReturnValue(
+ makeTransport(WebSocket.OPEN),
+ );
+ vi.mocked(useRuntimeManager).mockReturnValue(
+ makeRuntimeManager() as unknown as ReturnType<typeof useRuntimeManager>,
+ );
+ renderConnectionHook(store);
+ const options = vi.mocked(useConnectionTransport).mock.calls.at(-1)![0];
+
+ await act(async () => {
+ await options.onOpen(new Event("open"));
+ });
+ expect(store.get(connectionAtom).state).toBe(WebSocketState.CONNECTING);
+
+ act(() => {
+ options.onMessage(
+ new MessageEvent("message", {
+ data: JSON.stringify({
+ op,
+ data: {
+ op,
+ cell_ids: [],
+ codes: [],
+ names: [],
+ configs: [],
+ layout: null,
+ resumed: true,
+ ui_values: {},
+ last_executed_code: {},
+ last_execution_time: {},
+ app_config: { width: "normal" },
+ kiosk: false,
+ capabilities: { terminal: false },
+ auto_instantiated: false,
+ consumer_capabilities: { edit: true, interact: true },
+ },
+ }),
+ }),
+ );
+ });
+ expect(store.get(connectionAtom).state).toBe(WebSocketState.OPEN);
+ },
+);
+
+describe("connection notice", () => {
+ beforeEach(() => vi.useFakeTimers());
+ afterEach(() => vi.useRealTimers());
+
+ function renderNotice() {
+ const store = createStore();
+ store.set(connectionAtom, { state: WebSocketState.CONNECTING });
+ const transport = makeTransport(WebSocket.OPEN);
+ vi.mocked(useConnectionTransport).mockReturnValue(transport);
+ vi.mocked(useRuntimeManager).mockReturnValue(
+ makeRuntimeManager() as unknown as ReturnType<typeof useRuntimeManager>,
+ );
+ const Connection = () => {
+ const { reconnect } = useMarimoKernelConnection({
+ sessionId: "test-session" as SessionId,
+ autoInstantiate: false,
+ setCells: () => {},
+ });
+ return (
+ <ConnectionNotice
+ appConfig={AppConfigSchema.parse({})}
+ onRetry={reconnect}
+ />
+ );
+ };
+ render(
+ <JotaiProvider store={store}>
+ <ErrorBoundary fallback={null}>
+ <Connection />
+ </ErrorBoundary>
+ </JotaiProvider>,
+ );
+ const options = vi.mocked(useConnectionTransport).mock.calls.at(-1)![0];
+ const send = (data: NotificationPayload["data"]) =>
+ act(() => {
+ options.onMessage(
+ new MessageEvent("message", {
+ data: JSON.stringify({ op: data.op, data }),
+ }),
+ );
+ });
+ return { store, transport, options, send };
+ }
+
+ it("keeps elapsed time across startup phases and leaves reconnection to the footer once cells are available", () => {
+ const { store, options, send } = renderNotice();
+ send({ op: "startup-progress", phase: "preparing-environment" });
+ expect(
+ screen.queryByRole("region", { name: "Notebook startup" }),
+ ).not.toBeInTheDocument();
+ act(() => vi.advanceTimersByTime(500));
+ expect(screen.getByRole("status")).toHaveTextContent(
+ "Preparing environment",
+ );
+ act(() => vi.advanceTimersByTime(35_000));
+ expect(screen.getByText("Elapsed 35s")).toBeInTheDocument();
+ act(() =>
+ store.set(
+ notebookAtom,
+ MockNotebook.notebookState({
+ cellData: { [cellId("test")]: { code: "answer = 42" } },
+ }),
+ ),
+ );
+ send({ op: "startup-progress", phase: "starting-kernel" });
+ expect(screen.getByRole("status")).toHaveTextContent("Starting notebook");
+ expect(screen.getByText("Elapsed 35s")).toBeInTheDocument();
+ send({ op: "reconnected" });
+ expect(
+ screen.queryByRole("region", { name: "Notebook startup" }),
+ ).not.toBeInTheDocument();
+ act(() => options.onClose(new CloseEvent("close")));
+ act(() => vi.advanceTimersByTime(500));
+ expect(store.get(connectionAtom)).toEqual({
+ state: WebSocketState.CONNECTING,
+ phase: "reconnecting",
+ });
+ expect(
+ screen.queryByRole("region", { name: "Notebook startup" }),
+ ).not.toBeInTheDocument();
+ });
+
+ it("does not flash a notice when startup finishes within the delay", () => {
+ const { send } = renderNotice();
+ send({ op: "startup-progress", phase: "preparing-environment" });
+ act(() => vi.advanceTimersByTime(200));
+ send({ op: "startup-progress", phase: "starting-kernel" });
+ act(() => vi.advanceTimersByTime(200));
+ expect(
+ screen.queryByRole("region", { name: "Notebook startup" }),
+ ).not.toBeInTheDocument();
+ send({ op: "reconnected" });
+ act(() => vi.advanceTimersByTime(500));
+ expect(
+ screen.queryByRole("region", { name: "Notebook startup" }),
+ ).not.toBeInTheDocument();
+ });
+
+ it.each([
+ ["preparing-environment", "Sandbox setup failed"],
+ ["starting-kernel", "Kernel failed to start"],
+ ] as const)(
+ "keeps a %s failure available until the user retries",
+ async (phase, title) => {
+ const { store, transport, options, send } = renderNotice();
+ send({ op: "startup-progress", phase });
+ const error = "A full diagnostic\nwith <stderr> details";
+ send({ op: "kernel-startup-error", error });
+ transport.readyState = WebSocket.CLOSED;
+ act(() =>
+ options.onClose(
+ new CloseEvent("close", { reason: "MARIMO_KERNEL_STARTUP_ERROR" }),
+ ),
+ );
+ expect(screen.getByRole("status")).toHaveTextContent(title);
+ act(() => vi.advanceTimersByTime(30_000));
+ expect(screen.getByRole("status")).toHaveTextContent(title);
+ expect(screen.getByLabelText("Error details")).toHaveTextContent(error, {
+ normalizeWhitespace: false,
+ });
+ expect(transport.reconnect).not.toHaveBeenCalled();
+ await act(async () =>
+ fireEvent.click(screen.getByRole("button", { name: "Try again" })),
+ );
+ expect(transport.reconnect).toHaveBeenCalledOnce();
+ expect(store.get(kernelStartupErrorAtom)).toBeNull();
+ expect(
+ screen.queryByRole("button", { name: "Try again" }),
+ ).not.toBeInTheDocument();
+ send({ op: "startup-progress", phase: "preparing-environment" });
+ act(() => vi.advanceTimersByTime(500));
+ expect(screen.getByRole("status")).toHaveTextContent(
+ "Preparing environment",
+ );
+ expect(screen.getByText("Elapsed 0s")).toBeInTheDocument();
+ },
+ );
+});
diff --git a/frontend/src/core/websocket/types.ts b/frontend/src/core/websocket/types.ts
index 1bb4af0530..5cd37223e2 100644
--- a/frontend/src/core/websocket/types.ts
+++ b/frontend/src/core/websocket/types.ts
@@ -1,5 +1,11 @@
/* Copyright 2026 Marimo. All rights reserved. */
+import type { NotificationMessageData } from "../kernel/messages";
+
+type ConnectionPhase =
+ | NotificationMessageData<"startup-progress">["phase"]
+ | "reconnecting";
+
// TODO: rename to ConnectionState
export const WebSocketState = {
NOT_STARTED: "NOT_STARTED",
@@ -28,10 +34,14 @@ export type ConnectionStatus =
* Human-readable reason for closing the connection.
*/
reason: string;
+ phase?: ConnectionPhase;
+ }
+ | {
+ state: typeof WebSocketState.CONNECTING;
+ phase?: ConnectionPhase;
}
| {
state:
- | typeof WebSocketState.CONNECTING
| typeof WebSocketState.OPEN
| typeof WebSocketState.CLOSING
| typeof WebSocketState.NOT_STARTED;
diff --git a/frontend/src/core/websocket/useMarimoKernelConnection.tsx b/frontend/src/core/websocket/useMarimoKernelConnection.tsx
index 36b638f7ec..8f4e8a3f5c 100644
--- a/frontend/src/core/websocket/useMarimoKernelConnection.tsx
+++ b/frontend/src/core/websocket/useMarimoKernelConnection.tsx
@@ -1,5 +1,6 @@
/* Copyright 2026 Marimo. All rights reserved. */
+import { invalidatePackageData } from "@/core/packages/package-data";
import { useAtom, useAtomValue, useSetAtom } from "jotai";
import { useRef } from "react";
import { useErrorBoundary } from "react-error-boundary";
@@ -240,7 +241,15 @@ export function useMarimoKernelConnection(opts: {
case "reload":
reloadSafe();
return;
+ case "startup-progress":
+ setConnection({
+ state: WebSocketState.CONNECTING,
+ phase: msg.data.phase,
+ });
+ return;
case "kernel-ready": {
+ setKernelStartupError(null);
+ setConnection({ state: WebSocketState.OPEN });
setInitialRunCompleted(
Boolean(msg.data.resumed || msg.data.auto_instantiated),
);
@@ -363,6 +372,16 @@ export function useMarimoKernelConnection(opts: {
});
return;
case "installing-package-alert":
+ if (
+ msg.data.source !== "server" &&
+ msg.data.log_status !== "append" &&
+ msg.data.log_status !== "start" &&
+ Object.values(msg.data.packages).some(
+ (status) => status === "installed" || status === "restart-required",
+ )
+ ) {
+ invalidatePackageData();
+ }
addPackageAlert({
...msg.data,
kind: "installing",
@@ -439,6 +458,8 @@ export function useMarimoKernelConnection(opts: {
return;
case "reconnected":
+ setKernelStartupError(null);
+ setConnection({ state: WebSocketState.OPEN });
return;
case "focus-cell":
@@ -482,6 +503,7 @@ export function useMarimoKernelConnection(opts: {
return;
}
shouldTryReconnecting.current = true;
+ setKernelStartupError(null);
setConnection({ state: WebSocketState.CONNECTING });
const healthy = await runtimeManager.reconcileFromHealth();
if (!healthy) {
@@ -513,17 +535,11 @@ export function useMarimoKernelConnection(opts: {
headers: () => runtimeManager.headers(),
/**
- * Open callback. Set the connection status to open.
+ * The transport is open; kernel-ready establishes session readiness.
*/
onOpen: async () => {
// If we are open, we can reset our reconnecting flag.
shouldTryReconnecting.current = true;
-
- // DO NOT COMMIT THIS UNCOMMENTED
- // Uncomment to emulate a slow connection
- // await new Promise((resolve) => setTimeout(resolve, 10_000));
-
- setConnection({ state: WebSocketState.OPEN });
},
/**
@@ -565,7 +581,26 @@ export function useMarimoKernelConnection(opts: {
onClose: (e) => {
Logger.warn("WebSocket closed", e.code, e.reason);
const decision = classifyCloseEvent(e);
- setConnection(decision.status);
+ setConnection((previous) => {
+ const status = decision.status;
+ if (
+ status.state === WebSocketState.CLOSED &&
+ status.code === WebSocketClosedReason.KERNEL_STARTUP_ERROR &&
+ (previous.state === WebSocketState.CONNECTING ||
+ previous.state === WebSocketState.CLOSED)
+ ) {
+ return { ...status, phase: previous.phase };
+ }
+ if (
+ status.state === WebSocketState.CONNECTING &&
+ (previous.state === WebSocketState.OPEN ||
+ (previous.state === WebSocketState.CONNECTING &&
+ previous.phase === "reconnecting"))
+ ) {
+ return { ...status, phase: "reconnecting" };
+ }
+ return status;
+ });
if (decision.kind === "terminal" && decision.closeTransport) {
ws.close(); // close to prevent reconnecting
return;
diff --git a/frontend/src/stories/sandbox.stories.tsx b/frontend/src/stories/sandbox.stories.tsx
new file mode 100644
index 0000000000..d13f596837
--- /dev/null
+++ b/frontend/src/stories/sandbox.stories.tsx
@@ -0,0 +1,308 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { createStore, Provider, useAtomValue } from "jotai";
+import { useEffect, useRef, useState } from "react";
+import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";
+import {
+ SandboxFooter,
+ SandboxStartupPanel,
+} from "@/components/editor/chrome/panels/sandbox-panel";
+import { SandboxController } from "@/components/editor/chrome/panels/sandbox-controller";
+import { chromeAtom } from "@/components/editor/chrome/state";
+import { Cell } from "@/components/editor/notebook-cell";
+import { VerticalLayoutWrapper } from "@/components/editor/renderers/vertical-layout/vertical-layout-wrapper";
+import {
+ createNotebookActions,
+ notebookAtom,
+ notebookReducer,
+} from "@/core/cells/cells";
+import { userConfigAtom } from "@/core/config/config";
+import {
+ AppConfigSchema,
+ defaultUserConfig,
+} from "@/core/config/config-schema";
+import { kernelStartupErrorAtom } from "@/core/errors/state";
+import { connectionAtom } from "@/core/network/connection";
+import { requestClientAtom } from "@/core/network/requests";
+import { createStaticRequests } from "@/core/network/requests-static";
+import {
+ sandboxActionsAtom,
+ sandboxAtom,
+ sandboxSyncAtom,
+} from "@/core/packages/sandbox-state";
+import { filenameAtom } from "@/core/saving/file-state";
+import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";
+import { HTTPError } from "@/utils/errors";
+
+const manifest = `requires-python = ">=3.13"
+dependencies = ["marimo", "polars", "rich==999.0.0"]
+
+[tool.uv]
+index-url = "https://pypi.org/simple"
+
+[tool.notebook]
+description = "Explore bike trips"
+`;
+const resolutionError = `No solution found when resolving dependencies:
+ Because there is no version of rich==999.0.0 and your script depends
+ on rich==999.0.0, your script's requirements are unsatisfiable.`;
+
+interface Props {
+ surface: "notebook" | "packages" | "manifest";
+ phase:
+ | "preparing"
+ | "starting"
+ | "failed"
+ | "ready"
+ | "syncing"
+ | "sync-failed";
+ existingCells: boolean;
+ backend: "uv" | "pixi";
+ saveResult: "success" | "failure" | "stale";
+ theme: "light" | "dark";
+}
+
+function OpenManifest() {
+ const actions = useAtomValue(sandboxActionsAtom);
+ const opened = useRef(false);
+ useEffect(() => {
+ if (actions && !opened.current) {
+ opened.current = true;
+ void actions.editManifest();
+ }
+ }, [actions]);
+ return null;
+}
+
+function SandboxStory(props: Props) {
+ const [store] = useState(() => {
+ const state = createStore();
+ let currentManifest =
+ props.phase === "failed"
+ ? manifest
+ : manifest.replace("rich==999.0.0", "rich>=13.0.0");
+ const config = defaultUserConfig();
+ state.set(userConfigAtom, {
+ ...config,
+ display: { ...config.display, theme: props.theme },
+ });
+ state.set(filenameAtom, "bike_trips.py");
+ state.set(sandboxAtom, {
+ backend: props.backend,
+ manifest: currentManifest,
+ filename: "bike_trips.py",
+ });
+ state.set(chromeAtom, {
+ selectedPanel: "packages",
+ isSidebarOpen: props.surface !== "notebook",
+ isDeveloperPanelOpen: false,
+ selectedDeveloperPanelTab: "errors",
+ });
+ state.set(
+ connectionAtom,
+ props.phase === "preparing" || props.phase === "starting"
+ ? {
+ state: WebSocketState.CONNECTING,
+ phase:
+ props.phase === "preparing"
+ ? "preparing-environment"
+ : "starting-kernel",
+ }
+ : props.phase === "failed"
+ ? {
+ state: WebSocketState.CLOSED,
+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ reason: "Kernel startup failed",
+ phase: "preparing-environment",
+ }
+ : { state: WebSocketState.OPEN },
+ );
+ state.set(
+ kernelStartupErrorAtom,
+ props.phase === "failed" ? resolutionError : null,
+ );
+ state.set(sandboxSyncAtom, {
+ pending: props.phase === "syncing",
+ error: props.phase === "sync-failed" ? resolutionError : null,
+ });
+ if (props.existingCells) {
+ const actions = createNotebookActions((action) =>
+ state.set(notebookAtom, (value) => notebookReducer(value, action)),
+ );
+ actions.createNewCell({
+ cellId: "__end__",
+ before: false,
+ code: 'import polars as pl\n\ntrips = pl.read_csv("bike_trips.csv")\ntrips.head()',
+ autoFocus: false,
+ });
+ }
+ state.set(requestClientAtom, {
+ ...createStaticRequests(),
+ getSandbox: async () => ({
+ backend: props.backend,
+ manifest: currentManifest,
+ filename: "bike_trips.py",
+ }),
+ updateManifest: async ({ contents }) => {
+ if (props.saveResult === "stale") {
+ throw new HTTPError(
+ 409,
+ "The manifest changed on disk. Reopen it before saving.",
+ );
+ }
+ currentManifest = contents;
+ return {
+ backend: props.backend,
+ manifest: currentManifest,
+ filename: "bike_trips.py",
+ };
+ },
+ syncSandbox: async () => {
+ await new Promise((resolve) => setTimeout(resolve, 2000));
+ if (props.saveResult === "failure") {
+ return {
+ success: false,
+ error:
+ "Failed to download rich from https://pypi.org/simple/rich/\n Request failed after 3 retries: connection timed out",
+ restartRequired: false,
+ reconnect: false,
+ };
+ }
+ state.set(connectionAtom, { state: WebSocketState.OPEN });
+ state.set(kernelStartupErrorAtom, null);
+ return {
+ success: true,
+ error: null,
+ restartRequired: false,
+ reconnect: false,
+ };
+ },
+ });
+ return state;
+ });
+ const appConfig = AppConfigSchema.parse({ width: "full" });
+ const reconnect = async () => {
+ store.set(connectionAtom, { state: WebSocketState.OPEN });
+ };
+ return (
+ <Provider store={store}>
+ <SandboxController onReconnect={reconnect} />
+ {props.surface === "manifest" && <OpenManifest />}
+ <div
+ data-testid="sandbox-story"
+ className="bg-background text-foreground"
+ style={{
+ width: props.surface === "notebook" ? 820 : 400,
+ }}
+ >
+ {props.surface === "notebook" && (
+ <>
+ <ConnectionNotice appConfig={appConfig} onRetry={reconnect} />
+ {store.get(notebookAtom).cellIds.inOrderIds.map((cellId) => (
+ <VerticalLayoutWrapper key={cellId} appConfig={appConfig}>
+ <Cell
+ cellId={cellId}
+ theme={props.theme}
+ mode="edit"
+ showPlaceholder={false}
+ canDelete={true}
+ isCollapsed={false}
+ collapseCount={0}
+ canMoveX={false}
+ userConfig={store.get(userConfigAtom)}
+ />
+ </VerticalLayoutWrapper>
+ ))}
+ </>
+ )}
+ {props.surface === "packages" &&
+ (props.phase === "failed" ||
+ props.phase === "sync-failed" ||
+ props.phase === "preparing" ? (
+ <SandboxStartupPanel />
+ ) : (
+ <SandboxFooter />
+ ))}
+ </div>
+ </Provider>
+ );
+}
+
+const meta = {
+ title: "Sandbox/States",
+ component: SandboxStory,
+ parameters: { layout: "centered" },
+ args: {
+ surface: "notebook",
+ phase: "preparing",
+ existingCells: true,
+ backend: "uv",
+ saveResult: "success",
+ theme: "light",
+ },
+ render: (args, context) => (
+ <SandboxStory
+ key={JSON.stringify([args, context.globals.theme])}
+ {...args}
+ theme={context.globals.theme === "dark" ? "dark" : "light"}
+ />
+ ),
+} satisfies Meta<typeof SandboxStory>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const ExistingNotebookPreparing: Story = {
+ name: "Startup notice / preparing",
+};
+export const EmptyNotebookPreparing: Story = {
+ name: "Empty notebook / preparing",
+ args: { existingCells: false },
+};
+export const StartingKernel: Story = {
+ name: "Startup notice / starting kernel",
+ args: { phase: "starting" },
+};
+export const ExistingNotebookFailed: Story = {
+ name: "Startup notice / failed",
+ args: { phase: "failed" },
+};
+export const EmptyNotebookFailed: Story = {
+ name: "Empty notebook / failed",
+ args: { phase: "failed", existingCells: false },
+};
+export const PackagesPreparing: Story = {
+ name: "Setup details / preparing",
+ args: { surface: "packages" },
+};
+export const PackagesFailed: Story = {
+ name: "Setup details / failed",
+ args: { surface: "packages", phase: "failed" },
+};
+export const PackagesReady: Story = {
+ name: "Status row / ready",
+ args: { surface: "packages", phase: "ready" },
+};
+export const PackagesSyncing: Story = {
+ name: "Status row / syncing",
+ args: { surface: "packages", phase: "syncing" },
+};
+export const PackagesSyncFailed: Story = {
+ name: "Setup details / sync failed",
+ args: { surface: "packages", phase: "sync-failed" },
+};
+export const PixiPackagesReady: Story = {
+ name: "Status row / pixi",
+ args: { surface: "packages", phase: "ready", backend: "pixi" },
+};
+export const ManifestEditor: Story = {
+ name: "Manifest / edit",
+ args: { surface: "manifest", phase: "failed" },
+};
+export const ManifestSyncFails: Story = {
+ name: "Manifest / failed save",
+ args: { surface: "manifest", phase: "failed", saveResult: "failure" },
+};
+export const ManifestChangedOnDisk: Story = {
+ name: "Manifest / changed on disk",
+ args: { surface: "manifest", phase: "failed", saveResult: "stale" },
+};
diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.py
index a37e99881d..84bae8a51b 100644
--- a/marimo/_cli/cli.py
+++ b/marimo/_cli/cli.py
@@ -26,7 +26,7 @@ from marimo._cli.errors import (
)
from marimo._cli.export.commands import export
from marimo._cli.files.file_path import validate_name
-from marimo._cli.help_formatter import ColoredCommand, ColoredGroup, RunCommand
+from marimo._cli.help_formatter import ColoredGroup, SandboxCommand
from marimo._cli.pair.commands import pair
from marimo._cli.parse_args import parse_args
from marimo._cli.parser_ux import show_compact_usage_error
@@ -283,36 +283,7 @@ class _OptionalValueOption(click.Option):
self.flag_value = opt_flag_value
-def _normalize_sandbox_args(args: list[str]) -> list[str]:
- """Give a bare `--sandbox` its backwards-compatible uv value.
-
- Click options cannot reliably accept both an optional value and a
- following positional argument. Normalize the bare spelling before Click
- parses it. Explicit backends use `--sandbox=pixi`; following paths named
- `uv` or `pixi` and arguments after `--` remain positional arguments.
- """
- normalized = list(args)
- try:
- limit = normalized.index("--")
- except ValueError:
- limit = len(normalized)
- for index, token in enumerate(normalized[:limit]):
- if token == "--sandbox":
- normalized[index] = "--sandbox=uv"
- return normalized
-
-
-class _SandboxCommand(ColoredCommand):
- def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
- return super().parse_args(ctx, _normalize_sandbox_args(args))
-
-
-class _SandboxRunCommand(RunCommand):
- def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
- return super().parse_args(ctx, _normalize_sandbox_args(args))
-
-
[email protected](cls=_SandboxCommand, help=edit_help_msg)
[email protected](cls=SandboxCommand, help=edit_help_msg)
@click.option(
"-p",
"--port",
@@ -505,8 +476,9 @@ def edit(
name: str | None,
args: tuple[str, ...],
) -> None:
- from marimo._cli.sandbox import SandboxMode, resolve_sandbox
+ from marimo._cli.sandbox import ensure_server_environment, resolve_sandbox
+ stdin_notebook = None
pass_on_stdin = token_password_file == "-"
# We support unix-style piping, e.g. cat notebook.py | marimo edit
if (
@@ -519,6 +491,7 @@ def edit(
"notebook.py", "py", stdin_contents, temp_dir
)
name = path.absolute_name
+ stdin_notebook = name
if prompt_run_in_docker_container(name, trusted=trusted):
from marimo._cli.run_docker import run_in_docker
@@ -568,33 +541,10 @@ def edit(
# We check this after name validation, because this will convert
# URLs into local file paths
- # Resolve sandbox mode: None, SandboxMode.SINGLE, or SandboxMode.MULTI
- sandbox_mode, sandbox_backend = resolve_sandbox(
+ sandbox_backend = resolve_sandbox(
sandbox=sandbox, no_sandbox=no_sandbox, name=name
)
-
- # Single-file sandbox: the server runs from the script environment
- if sandbox_mode is SandboxMode.SINGLE:
- from marimo._cli.sandbox import run_in_sandbox
-
- sys.exit(
- run_in_sandbox(
- sys.argv[1:],
- name=name,
- extras=["lsp"],
- backend=sandbox_backend,
- )
- )
-
- # Multi-file sandbox: use IPC kernels with per-notebook sandboxed venvs
- if sandbox_mode is SandboxMode.MULTI:
- # 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"
- os.environ["MARIMO_SANDBOX_BACKEND"] = sandbox_backend
- GLOBAL_SETTINGS.SANDBOX_BACKEND = sandbox_backend
+ ensure_server_environment(sandbox_backend, stdin_notebook=stdin_notebook)
# Check shared memory availability early (required for edit mode to
# communicate between the server process and kernel subprocess)
@@ -654,7 +604,7 @@ def edit(
server_startup_command=server_startup_command,
asset_url=asset_url,
timeout=timeout,
- sandbox_mode=sandbox_mode,
+ sandbox=sandbox_backend,
startup_tip=choose_startup_tip(click.get_current_context()),
)
@@ -693,7 +643,7 @@ new_help_msg = "\n".join(
)
[email protected](cls=_SandboxCommand, help=new_help_msg)
[email protected](cls=SandboxCommand, help=new_help_msg)
@click.option(
"-p",
"--port",
@@ -788,18 +738,10 @@ def new(
timeout: float | None,
prompt: str | None,
) -> None:
- if sandbox and not no_sandbox:
- from marimo._cli.sandbox import backend_from_flag, run_in_sandbox
+ from marimo._cli.sandbox import ensure_server_environment, resolve_sandbox
- # TODO: consider adding recommended as well
- sys.exit(
- run_in_sandbox(
- sys.argv[1:],
- name=None,
- extras=["lsp"],
- backend=backend_from_flag(sandbox),
- )
- )
+ sandbox_backend = resolve_sandbox(sandbox, no_sandbox, name=None)
+ ensure_server_environment(sandbox_backend)
workspace: NotebookWorkspace | None = None
@@ -877,6 +819,7 @@ def new(
redirect_console_to_browser=True,
ttl_seconds=None,
timeout=timeout,
+ sandbox=sandbox_backend,
startup_tip=choose_startup_tip(click.get_current_context()),
)
@@ -1008,7 +951,7 @@ def _create_run_workspace(
@main.command(
- cls=_SandboxRunCommand,
+ cls=SandboxCommand,
help="""Run a notebook as an app in read-only mode.
If NAME is a url, the notebook will be downloaded to a temporary file.
@@ -1206,8 +1149,6 @@ def run(
args: tuple[str, ...],
) -> None:
from marimo._cli.sandbox import (
- SandboxMode,
- backend_from_flag,
resolve_sandbox,
run_in_sandbox,
)
@@ -1285,31 +1226,17 @@ def run(
# We check this after name validation, because this will convert
# URLs into local file paths
- if is_multi:
- # Gallery mode: use MULTI sandbox (IPC kernels) or None
- sandbox_mode = (
- SandboxMode.MULTI if sandbox and not no_sandbox else None
- )
- sandbox_backend = backend_from_flag(sandbox)
- else:
- sandbox_mode, sandbox_backend = resolve_sandbox(
- sandbox=sandbox, no_sandbox=no_sandbox, name=validated_paths[0]
- )
- if sandbox_mode is SandboxMode.SINGLE:
- sys.exit(
- run_in_sandbox(
- sys.argv[1:],
- name=validated_paths[0],
- backend=sandbox_backend,
- )
+ sandbox_backend = resolve_sandbox(
+ sandbox, no_sandbox, None if is_multi else validated_paths[0]
+ )
+ if sandbox_backend and not is_multi:
+ sys.exit(
+ run_in_sandbox(
+ sys.argv[1:],
+ name=validated_paths[0],
+ backend=sandbox_backend,
)
-
- # Multi-file sandbox: use IPC kernels with per-notebook sandboxed venvs
- if sandbox_mode is SandboxMode.MULTI:
- # Kernel launches read the backend from the global; without
- # this, `marimo run --sandbox=pixi` would launch uv kernels.
- os.environ["MARIMO_SANDBOX_BACKEND"] = sandbox_backend
- GLOBAL_SETTINGS.SANDBOX_BACKEND = sandbox_backend
+ )
workspace = _create_run_workspace(validated_paths, watch=watch)
@@ -1340,7 +1267,7 @@ def run(
redirect_console_to_browser=redirect_console_to_browser,
server_startup_command=server_startup_command,
asset_url=asset_url,
- sandbox_mode=sandbox_mode,
+ sandbox=sandbox_backend,
startup_tip=choose_startup_tip(click.get_current_context()),
show_tracebacks=show_tracebacks,
execute_opengraph_generators=execute_opengraph_generators,
diff --git a/marimo/_cli/development/commands.py b/marimo/_cli/development/commands.py
index 3af1014882..adab26d3d8 100644
--- a/marimo/_cli/development/commands.py
+++ b/marimo/_cli/development/commands.py
@@ -391,6 +391,10 @@ def _generate_server_api_schema() -> dict[str, Any]:
packages.PackageOperationResponse,
packages.RemovePackageRequest,
packages.DependencyTreeResponse,
+ packages.SandboxRequest,
+ packages.SandboxResponse,
+ packages.UpdateManifestRequest,
+ packages.SyncSandboxResponse,
lsp.LspHealthResponse,
lsp.LspRestartRequest,
lsp.LspRestartResponse,
diff --git a/marimo/_cli/export/_common.py b/marimo/_cli/export/_common.py
index ff57efea9e..b9b8bf074e 100644
--- a/marimo/_cli/export/_common.py
+++ b/marimo/_cli/export/_common.py
@@ -4,28 +4,22 @@ 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
import click
+from marimo._environments.process import run_command
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, Iterator
- from marimo._environments.environment import Environment
-
-
-def is_multi_target(paths: list[Path]) -> bool:
- return len(paths) > 1 or any(path.is_dir() for path in paths)
+ from marimo._environments.sandbox import Backend
def collect_notebooks(paths: Iterable[Path]) -> list[MarimoPath]:
@@ -52,46 +46,6 @@ 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._targets: dict[str, SandboxTarget] = {}
-
- def get_target(self, notebook_path: str) -> SandboxTarget:
- from marimo._environments.backends import sync_notebook
- from marimo._environments.uv import UvMissingScriptMetadataError
-
- key = str(Path(notebook_path).resolve())
- existing = self._targets.get(key)
- if existing is not None:
- return existing
-
- try:
- target = SandboxTarget(
- environment=sync_notebook(key, backend="uv")
- )
- except UvMissingScriptMetadataError:
- target = SandboxTarget(environment=None)
- self._targets[key] = target
- return target
-
- def close(self) -> None:
- # uv owns the environments; there is nothing to remove.
- self._targets.clear()
-
-
@contextlib.contextmanager
def _export_termination_signals() -> Iterator[None]:
"""Let termination unwind the runner so its isolated child is reaped."""
@@ -115,39 +69,40 @@ def _export_termination_signals() -> Iterator[None]:
signal.signal(signum, handler)
-def run_python_subprocess(
+async def run_python_subprocess(
*,
- sandbox: SandboxTarget,
+ notebook_path: str,
+ backend: Backend,
script: str,
payload: dict[str, Any],
action: str,
) -> str:
- from marimo._environments.backends import launch_fallback
- from marimo._environments.environment import launch
+ from marimo._environments.backends import (
+ launch,
+ launch_fallback,
+ sync_notebook_async,
+ )
+ from marimo._environments.errors import MissingScriptMetadataError
from marimo._environments.overlay import runtime_overlay
args = ["-c", script, json.dumps(payload)]
- if sandbox.environment is not None:
- plan = launch(sandbox.environment, args, overlay=runtime_overlay())
- else:
- plan = launch_fallback(args)
- 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,
- ):
+ with _export_termination_signals():
try:
- stdout, stderr = process.communicate()
- except BaseException:
- kill_subprocess(process, start_new_session=plan.start_new_session)
- raise
- if process.returncode != 0:
+ environment = await sync_notebook_async(
+ str(Path(notebook_path).resolve()), # noqa: ASYNC240
+ backend=backend,
+ )
+ except MissingScriptMetadataError:
+ plan = launch_fallback(args)
+ else:
+ plan = launch(
+ environment, args, backend=backend, overlay=runtime_overlay()
+ )
+ completed = await run_command(
+ plan.argv,
+ env=plan.env,
+ )
+ if completed.returncode != 0:
# Identify the real launcher without exposing requirement URLs,
# credentials, notebook code, or the serialized request payload.
launcher = Path(plan.argv[0]).name
@@ -155,6 +110,6 @@ def run_python_subprocess(
raise click.ClickException(
f"Failed to {action} in sandbox.\n\n"
f"Command:\n\n {command}\n\n"
- f"Stderr:\n\n{stderr.strip()}"
+ f"Stderr:\n\n{completed.stderr.strip()}"
)
- return stdout
+ return completed.stdout
diff --git a/marimo/_cli/export/session.py b/marimo/_cli/export/session.py
index 8a017324da..1c1eccf79f 100644
--- a/marimo/_cli/export/session.py
+++ b/marimo/_cli/export/session.py
@@ -1,25 +1,20 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-import asyncio
import json
-import sys
from pathlib import Path
from typing import TYPE_CHECKING, Any, cast
import click
-from marimo._cli.errors import MarimoCLIMissingDependencyError
from marimo._cli.export._common import (
- SandboxTarget,
- SandboxVenvPool,
collect_notebooks,
- is_multi_target,
run_python_subprocess,
)
+from marimo._cli.help_formatter import SandboxCommand
from marimo._cli.parse_args import parse_args
from marimo._cli.print import echo, green, red, yellow
-from marimo._dependencies.dependencies import DependencyManager
+from marimo._cli.sandbox import resolve_sandbox
from marimo._export._session_cache import (
is_session_snapshot_stale,
serialize_session_snapshot,
@@ -37,37 +32,22 @@ from marimo._session.state.serialize import get_session_cache_file
from marimo._utils.marimo_path import MarimoPath
if TYPE_CHECKING:
- from marimo._cli.sandbox import SandboxMode
+ from marimo._environments.sandbox import Backend
+
_sandbox_message = (
- "Run the command in an isolated virtual environment using "
- "`uv run --isolated`. Requires `uv`."
+ "Execute each notebook in an isolated environment with its inline "
+ "dependencies. Use --sandbox (uv), --sandbox=uv, or --sandbox=pixi."
)
-def _resolve_session_sandbox_mode(
- *,
- sandbox: bool | None,
- path_targets: list[Path],
- first_target: str,
-) -> SandboxMode | None:
- from marimo._cli.sandbox import SandboxMode, resolve_sandbox_mode
-
- if is_multi_target(path_targets):
- if sandbox is None:
- return None
- return SandboxMode.MULTI if sandbox else None
-
- return resolve_sandbox_mode(sandbox=sandbox, name=first_target)
-
-
async def _export_session_snapshot(
marimo_path: MarimoPath,
*,
notebook_args: tuple[str, ...],
- sandbox: SandboxTarget | None = None,
+ sandbox: Backend | None = None,
) -> tuple[NotebookSessionV1, bool]:
- if sandbox is None:
+ if not sandbox:
cli_args = parse_args(notebook_args) if notebook_args else {}
file_manager = load_notebook(marimo_path.absolute_name)
@@ -94,15 +74,12 @@ async def _export_session_snapshot(
"path": marimo_path.absolute_name,
"args": list(notebook_args),
}
- return await asyncio.to_thread(
- _export_session_snapshot_in_subprocess,
- sandbox,
- payload,
- )
+ return await _export_session_snapshot_in_subprocess(payload, sandbox)
-def _export_session_snapshot_in_subprocess(
- sandbox: SandboxTarget, payload: dict[str, Any]
+async def _export_session_snapshot_in_subprocess(
+ payload: dict[str, Any],
+ backend: Backend,
) -> tuple[NotebookSessionV1, bool]:
script = r"""
import asyncio
@@ -155,8 +132,9 @@ sys.stdout.write(
)
"""
- output = run_python_subprocess(
- sandbox=sandbox,
+ output = await run_python_subprocess(
+ notebook_path=payload["path"],
+ backend=backend,
script=script,
payload=payload,
action="export session",
@@ -185,18 +163,12 @@ async def _export_session_for_notebook(
*,
force_overwrite: bool,
notebook_args: tuple[str, ...],
- sandbox_pool: SandboxVenvPool | None,
+ sandbox: Backend | None,
) -> None:
- output = get_session_cache_file(notebook.path)
if _maybe_skip_fresh_snapshot(notebook, force_overwrite=force_overwrite):
return
echo(f"Running {notebook.short_name}...")
- sandbox = (
- sandbox_pool.get_target(str(notebook.path))
- if sandbox_pool is not None
- else None
- )
session_snapshot, did_error = await _export_session_snapshot(
notebook,
@@ -239,41 +211,23 @@ async def _export_sessions(
force_overwrite: bool,
notebook_args: tuple[str, ...],
continue_on_error: bool,
- sandbox_mode: SandboxMode | None,
+ sandbox: Backend | None,
) -> None:
- from marimo._cli.sandbox import SandboxMode
-
failures: list[tuple[MarimoPath, Exception]] = []
- use_per_notebook_sandbox = sandbox_mode is SandboxMode.MULTI
-
- if use_per_notebook_sandbox and not DependencyManager.which("uv"):
- raise MarimoCLIMissingDependencyError(
- "uv is required for --sandbox session export.",
- "uv",
- additional_tip="Install uv from https://github.com/astral-sh/uv",
- )
- sandbox_pool: SandboxVenvPool | None = (
- SandboxVenvPool() if use_per_notebook_sandbox else None
- )
-
- try:
- for notebook in notebooks:
- try:
- await _export_session_for_notebook(
- notebook,
- force_overwrite=force_overwrite,
- notebook_args=notebook_args,
- sandbox_pool=sandbox_pool,
- )
- except Exception as error:
- failures.append((notebook, error))
- echo(red("error") + f": {notebook.short_name}: {error}")
- if not continue_on_error:
- raise
- finally:
- if sandbox_pool is not None:
- sandbox_pool.close()
+ for notebook in notebooks:
+ try:
+ await _export_session_for_notebook(
+ notebook,
+ force_overwrite=force_overwrite,
+ notebook_args=notebook_args,
+ sandbox=sandbox,
+ )
+ except Exception as error:
+ failures.append((notebook, error))
+ echo(red("error") + f": {notebook.short_name}: {error}")
+ if not continue_on_error:
+ raise
if failures:
raise click.ClickException(
@@ -283,6 +237,7 @@ async def _export_sessions(
@click.command(
"session",
+ cls=SandboxCommand,
help=(
"Execute a notebook or directory of notebooks and export session snapshots."
),
@@ -294,12 +249,17 @@ async def _export_sessions(
),
)
@click.option(
- "--sandbox/--no-sandbox",
- is_flag=True,
+ "--sandbox",
default=None,
- type=bool,
+ type=click.Choice(["uv", "pixi"]),
help=_sandbox_message,
)
+ "--no-sandbox",
+ is_flag=True,
+ default=False,
+ help="Never run in a sandbox, and never prompt to.",
+)
@click.option(
"--force-overwrite/--no-force-overwrite",
default=False,
@@ -316,7 +276,8 @@ async def _export_sessions(
@click.argument("args", nargs=-1, type=click.UNPROCESSED)
def session(
name: Path,
- sandbox: bool | None,
+ sandbox: str | None,
+ no_sandbox: bool,
force_overwrite: bool,
continue_on_error: bool,
args: tuple[str, ...],
@@ -327,28 +288,12 @@ def session(
if not notebooks:
raise click.ClickException("No marimo notebooks found.")
- sandbox_mode = _resolve_session_sandbox_mode(
- sandbox=sandbox,
- path_targets=path_targets,
- first_target=str(name),
- )
-
- from marimo._cli.sandbox import SandboxMode, run_in_sandbox
-
- if sandbox_mode is SandboxMode.SINGLE:
- notebook = notebooks[0]
- if _maybe_skip_fresh_snapshot(
- notebook, force_overwrite=force_overwrite
- ):
- return
- sys.exit(run_in_sandbox(sys.argv[1:], name=str(name)))
-
asyncio_run(
_export_sessions(
notebooks=notebooks,
force_overwrite=force_overwrite,
notebook_args=args,
continue_on_error=continue_on_error,
- sandbox_mode=sandbox_mode,
+ sandbox=resolve_sandbox(sandbox, no_sandbox, str(name)),
)
)
diff --git a/marimo/_cli/export/thumbnail.py b/marimo/_cli/export/thumbnail.py
index a33d349843..4eddeb6ccb 100644
--- a/marimo/_cli/export/thumbnail.py
+++ b/marimo/_cli/export/thumbnail.py
@@ -1,7 +1,6 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-import asyncio
import os
import sys
from pathlib import Path
@@ -11,17 +10,23 @@ import click
from marimo._cli.errors import MarimoCLIMissingDependencyError
from marimo._cli.export._common import (
- SandboxTarget,
- SandboxVenvPool,
collect_notebooks,
- is_multi_target,
run_python_subprocess,
)
from marimo._cli.export.output import STDERR
+from marimo._cli.help_formatter import SandboxCommand
from marimo._cli.install_hints import get_playwright_chromium_setup_commands
from marimo._cli.parse_args import parse_args
from marimo._cli.print import echo, green, red, yellow
+from marimo._cli.sandbox import (
+ _strip_sandbox_args,
+ _wait_on_plan,
+ require_sandbox_backend,
+ resolve_sandbox,
+)
from marimo._dependencies.dependencies import DependencyManager
+from marimo._environments.backends import launch_isolated
+from marimo._environments.overlay import runtime_overlay
from marimo._export._html_asset_server import HtmlAssetServer
from marimo._export.file import export_html
from marimo._export.requests import (
@@ -34,88 +39,17 @@ from marimo._utils.marimo_path import MarimoPath
from marimo._utils.paths import marimo_package_path, maybe_make_dirs
if TYPE_CHECKING:
- from marimo._cli.sandbox import SandboxMode
+ from marimo._environments.sandbox import Backend
_sandbox_message = (
"Render notebooks in an isolated environment, with dependencies tracked "
"via PEP 723 inline metadata. If already declared, dependencies will "
- "install automatically. Requires uv. Only applies when --execute is used."
+ "install automatically. Use --sandbox (uv), --sandbox=uv, or "
+ "--sandbox=pixi. Only applies when --execute is used."
)
_READINESS_WAIT_TIMEOUT_MS = 30_000
_sandbox_bootstrapped_env = "MARIMO_THUMBNAIL_SANDBOX_BOOTSTRAPPED"
-_sandbox_mode_env = "MARIMO_THUMBNAIL_SANDBOX_MODE"
-_thumbnail_sandbox_deps = ["playwright"]
-
-
-def _split_paths_and_args(
- name: str, args: tuple[str, ...]
-) -> tuple[list[str], tuple[str, ...]]:
- paths = [name]
- for index, arg in enumerate(args):
- if arg == "--":
- return paths, args[index + 1 :]
- paths.append(arg)
- return paths, ()
-
-
-def _sandbox_mode_from_env() -> SandboxMode | None:
- from marimo._cli.sandbox import SandboxMode
-
- if os.environ.get(_sandbox_bootstrapped_env) != "1":
- return None
-
- mode = os.environ.get(_sandbox_mode_env)
- if mode == SandboxMode.SINGLE.value:
- return SandboxMode.SINGLE
- if mode == SandboxMode.MULTI.value:
- return SandboxMode.MULTI
- return None
-
-
-def _resolve_thumbnail_sandbox_mode(
- *,
- execute: bool,
- sandbox: bool | None,
- path_targets: list[Path],
- first_target: str,
-) -> SandboxMode | None:
- from marimo._cli.sandbox import SandboxMode, resolve_sandbox_mode
-
- if not execute:
- return None
-
- env_mode = _sandbox_mode_from_env()
- if env_mode is not None:
- return env_mode
-
- if is_multi_target(path_targets):
- if sandbox is None:
- return None
- return SandboxMode.MULTI if sandbox else None
-
- return resolve_sandbox_mode(sandbox=sandbox, name=first_target)
-
-
-def _bootstrap_thumbnail_sandbox(
- *,
- args: list[str],
- name: str,
- sandbox_mode: SandboxMode,
-) -> None:
- from marimo._cli.sandbox import run_in_sandbox
-
- sys.exit(
- run_in_sandbox(
- args,
- name=name,
- command_deps=_thumbnail_sandbox_deps,
- extra_env={
- _sandbox_bootstrapped_env: "1",
- _sandbox_mode_env: sandbox_mode.value,
- },
- )
- )
async def _render_html(
@@ -125,7 +59,7 @@ async def _render_html(
include_code: bool,
args: tuple[str, ...],
asset_url: str | None = None,
- sandbox: SandboxTarget | None = None,
+ sandbox: Backend | None = None,
) -> str:
if not execute:
result = await export_html(
@@ -140,7 +74,7 @@ async def _render_html(
)
return result.text
- if sandbox is None:
+ if not sandbox:
cli_args = parse_args(args) if args else {}
result = await export_html(
HTMLFileExportRequest(
@@ -167,15 +101,11 @@ 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,
- sandbox,
- payload,
- )
+ return await _render_html_in_subprocess(payload, sandbox)
-def _render_html_in_subprocess(
- sandbox: SandboxTarget, payload: dict[str, Any]
+async def _render_html_in_subprocess(
+ payload: dict[str, Any], backend: Backend
) -> str:
"""Render a notebook to HTML in a separate Python process."""
script = r"""
@@ -218,8 +148,9 @@ result = asyncio.run(
sys.stdout.write(result.text)
"""
- return run_python_subprocess(
- sandbox=sandbox,
+ return await run_python_subprocess(
+ notebook_path=payload["path"],
+ backend=backend,
script=script,
payload=payload,
action="render notebook",
@@ -239,9 +170,8 @@ async def _generate_thumbnails(
execute: bool,
notebook_args: tuple[str, ...],
continue_on_error: bool,
- sandbox_mode: SandboxMode | None,
+ sandbox: Backend | None,
) -> None:
- from marimo._cli.sandbox import SandboxMode
from marimo._metadata.opengraph import default_opengraph_image_abs
failures: list[tuple[MarimoPath, Exception]] = []
@@ -260,81 +190,61 @@ async def _generate_thumbnails(
) from None
raise
- use_per_notebook_sandbox = sandbox_mode is SandboxMode.MULTI
-
- if use_per_notebook_sandbox and not DependencyManager.which("uv"):
- raise MarimoCLIMissingDependencyError(
- "uv is required for --sandbox thumbnail generation.",
- "uv",
- additional_tip="Install uv from https://github.com/astral-sh/uv",
- )
-
static_dir = marimo_package_path() / "_static"
- sandbox_pool: SandboxVenvPool | None = (
- SandboxVenvPool() if use_per_notebook_sandbox else None
- )
- try:
- with HtmlAssetServer(
- directory=static_dir, route="/__marimo_thumbnail__.html"
- ) as server:
- async with async_playwright() as playwright:
- browser = await playwright.chromium.launch()
- context = await browser.new_context(
- viewport={"width": width, "height": height},
- device_scale_factor=scale,
- )
- page = await context.new_page()
- await page.emulate_media(reduced_motion="reduce")
-
- for index, notebook in enumerate(notebooks):
- try:
- out_path = (
- output
- if output is not None
- else default_opengraph_image_abs(
- str(notebook.path)
- )
- )
- if out_path.exists() and not overwrite:
- echo(
- red("skip")
- + f": {notebook.short_name} (exists, use --overwrite)"
- )
- continue
-
- maybe_make_dirs(out_path)
-
- echo(f"Rendering {notebook.short_name}...")
- sandbox = (
- sandbox_pool.get_target(str(notebook.path))
- if sandbox_pool is not None
- else None
- )
- html = await _render_html(
- notebook,
- execute=execute,
- include_code=include_code,
- args=notebook_args,
- asset_url=server.base_url,
- sandbox=sandbox,
+ with HtmlAssetServer(
+ directory=static_dir, route="/__marimo_thumbnail__.html"
+ ) as server:
+ async with async_playwright() as playwright:
+ browser = await playwright.chromium.launch()
+ context = await browser.new_context(
+ viewport={"width": width, "height": height},
+ device_scale_factor=scale,
+ )
+ page = await context.new_page()
+ await page.emulate_media(reduced_motion="reduce")
+
+ for index, notebook in enumerate(notebooks):
+ try:
+ out_path = (
+ output
+ if output is not None
+ else default_opengraph_image_abs(str(notebook.path))
+ )
+ if out_path.exists() and not overwrite:
+ echo(
+ red("skip")
+ + f": {notebook.short_name} (exists, use --overwrite)"
)
- server.set_html(html)
-
- echo(f"Screenshotting -> {out_path}...")
- page_url = f"{server.page_url}?v={index}"
- await page.goto(page_url, wait_until="load")
- # Hide chrome and watermarks marked for print so thumbnails stay focused on notebook content.
- await page.add_style_tag(
- content=(
- '.print\\:hidden,[data-testid="watermark"]{display:none !important;}'
- )
+ continue
+
+ maybe_make_dirs(out_path)
+
+ echo(f"Rendering {notebook.short_name}...")
+ html = await _render_html(
+ notebook,
+ execute=execute,
+ include_code=include_code,
+ args=notebook_args,
+ asset_url=server.base_url,
+ sandbox=sandbox,
+ )
+ server.set_html(html)
+
+ echo(f"Screenshotting -> {out_path}...")
+ page_url = f"{server.page_url}?v={index}"
+ await page.goto(page_url, wait_until="load")
+ # Hide chrome and watermarks marked for print so thumbnails stay focused on notebook content.
+ await page.add_style_tag(
+ content=(
+ '.print\\:hidden,[data-testid="watermark"]{display:none !important;}'
)
- # Nb renderer starts cell contents as invisible for a short period to avoid flicker
- # --> we wait for the first cell container to be visible before snapshotting.
- try:
- await page.wait_for_function(
- r"""
+ )
+ # Nb renderer starts cell contents as invisible for a short period to avoid flicker
+ # --> we wait for the first cell container to be visible before snapshotting.
+ try:
+ await page.wait_for_function(
+ r"""
() => {
const root = document.getElementById("root");
if (!root) return false;
@@ -351,30 +261,25 @@ async def _generate_thumbnails(
return root.childElementCount > 0;
}
""",
- timeout=_READINESS_WAIT_TIMEOUT_MS,
- )
- except PlaywrightTimeoutError:
- echo(
- yellow("warning")
- + ": readiness check timed out; capturing screenshot anyway."
- )
- await page.wait_for_timeout(timeout_ms)
- await page.screenshot(
- path=str(out_path), full_page=False
+ timeout=_READINESS_WAIT_TIMEOUT_MS,
+ )
+ except PlaywrightTimeoutError:
+ echo(
+ yellow("warning")
+ + ": readiness check timed out; capturing screenshot anyway."
)
+ await page.wait_for_timeout(timeout_ms)
+ await page.screenshot(path=str(out_path), full_page=False)
- echo(green("ok") + f": {out_path}")
- except Exception as e:
- failures.append((notebook, e))
- echo(red("error") + f": {notebook.short_name}: {e}")
- if not continue_on_error:
- raise
+ echo(green("ok") + f": {out_path}")
+ except Exception as e:
+ failures.append((notebook, e))
+ echo(red("error") + f": {notebook.short_name}: {e}")
+ if not continue_on_error:
+ raise
- await context.close()
- await browser.close()
- finally:
- if sandbox_pool is not None:
- sandbox_pool.close()
+ await context.close()
+ await browser.close()
if failures:
raise click.ClickException(
@@ -383,7 +288,9 @@ async def _generate_thumbnails(
@click.command(
- "thumbnail", help="Generate OpenGraph thumbnails for notebooks."
+ "thumbnail",
+ cls=SandboxCommand,
+ help="Generate OpenGraph thumbnails for notebooks.",
)
@click.argument(
"name",
@@ -447,12 +354,17 @@ async def _generate_thumbnails(
),
)
@click.option(
- "--sandbox/--no-sandbox",
- is_flag=True,
+ "--sandbox",
default=None,
- type=bool,
+ type=click.Choice(["uv", "pixi"]),
help=_sandbox_message,
)
+ "--no-sandbox",
+ is_flag=True,
+ default=False,
+ help="Never run in a sandbox, and never prompt to.",
+)
@click.option(
"--continue-on-error/--fail-fast",
default=True,
@@ -469,12 +381,17 @@ def thumbnail(
overwrite: bool,
include_code: bool,
execute: bool,
- sandbox: bool | None,
+ sandbox: str | None,
+ no_sandbox: bool,
continue_on_error: bool,
args: tuple[str, ...],
) -> None:
"""Generate thumbnails for one or more notebooks (or directories)."""
- paths, notebook_args = _split_paths_and_args(str(name), args)
+ notebook_args: tuple[str, ...] = click.get_current_context().meta.get(
+ "marimo_run_args_after_separator", ()
+ )
+ targets = args[: -len(notebook_args)] if notebook_args else args
+ paths = [str(name), *targets]
path_targets = [Path(p) for p in paths]
notebooks = collect_notebooks(path_targets)
if not notebooks:
@@ -484,27 +401,40 @@ def thumbnail(
"--output can only be used when generating thumbnail for a single notebook."
)
- if not execute and sandbox:
+ if not execute and sandbox and not no_sandbox:
raise click.UsageError("--sandbox requires --execute.")
- sandbox_mode = _resolve_thumbnail_sandbox_mode(
- execute=execute,
- sandbox=sandbox,
- path_targets=path_targets,
- first_target=str(name),
+ bootstrapped = os.environ.get(_sandbox_bootstrapped_env)
+ backend = (
+ resolve_sandbox(
+ sandbox or bootstrapped,
+ no_sandbox,
+ str(name) if len(path_targets) == 1 else None,
+ )
+ if execute
+ else None
)
- if (
- execute
- and sandbox_mode is not None
- and _sandbox_mode_from_env() is None
- ):
- _bootstrap_thumbnail_sandbox(
- args=sys.argv[1:],
- name=str(name),
- sandbox_mode=sandbox_mode,
+ if backend and not bootstrapped:
+ require_sandbox_backend(backend)
+ # The renderer needs Playwright, not a notebook-bound environment
+ # whose identity would be inherited by the export workers.
+ sys.exit(
+ _wait_on_plan(
+ launch_isolated(
+ ["-m", "marimo", *_strip_sandbox_args(sys.argv[1:])],
+ requirements=runtime_overlay(
+ command=["playwright"]
+ ).requirements,
+ python=sys.executable,
+ backend=backend,
+ base_env={
+ **os.environ,
+ _sandbox_bootstrapped_env: backend,
+ },
+ )
+ )
)
- return
try:
DependencyManager.playwright.require("for thumbnail generation")
@@ -530,6 +460,6 @@ def thumbnail(
execute=execute,
notebook_args=notebook_args,
continue_on_error=continue_on_error,
- sandbox_mode=sandbox_mode,
+ sandbox=backend,
)
)
diff --git a/marimo/_cli/help_formatter.py b/marimo/_cli/help_formatter.py
index fe61b93c88..0f054ea5c1 100644
--- a/marimo/_cli/help_formatter.py
+++ b/marimo/_cli/help_formatter.py
@@ -65,6 +65,33 @@ class RunCommand(ColoredCommand):
return super().parse_args(ctx, args)
+def _normalize_sandbox_args(args: list[str]) -> list[str]:
+ """Give a bare `--sandbox` its backwards-compatible uv value.
+
+ Click options cannot reliably accept both an optional value and a
+ following positional argument. Normalize the bare spelling before Click
+ parses it, leaving explicit uv/pixi values for Click to consume.
+ """
+ normalized = list(args)
+ try:
+ limit = normalized.index("--")
+ except ValueError:
+ limit = len(normalized)
+ for index, token in enumerate(normalized[:limit]):
+ if token == "--sandbox" and (
+ index + 1 == limit or normalized[index + 1] not in ("uv", "pixi")
+ ):
+ normalized[index] = "--sandbox=uv"
+ return normalized
+
+
+class SandboxCommand(RunCommand):
+ """Accept `--sandbox` with an optional uv/pixi backend."""
+
+ def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+ return super().parse_args(ctx, _normalize_sandbox_args(args))
+
+
class ColoredGroup(click.Group):
"""Click Group with colored help output (cargo-style)."""
diff --git a/marimo/_cli/sandbox.py b/marimo/_cli/sandbox.py
index 7e6ab05b89..a402969b93 100644
--- a/marimo/_cli/sandbox.py
+++ b/marimo/_cli/sandbox.py
@@ -1,6 +1,7 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+import asyncio
import atexit
import os
import platform
@@ -8,13 +9,15 @@ import signal
import subprocess
import sys
import tempfile
-from enum import Enum
from pathlib import Path
import click
from marimo import _loggers
-from marimo._cli.errors import MarimoCLIMissingDependencyError
+from marimo._cli.errors import (
+ MarimoCLIMissingDependencyError,
+ MarimoCLIRuntimeError,
+)
from marimo._cli.print import bold, echo, green, muted
from marimo._config.settings import GLOBAL_SETTINGS
from marimo._environments import environment, script_metadata
@@ -34,19 +37,6 @@ from marimo._utils.inline_script_metadata import (
from marimo._utils.versions import is_editable
from marimo._version import __version__
-
-class SandboxMode(Enum):
- """Sandbox mode for marimo notebooks.
-
- - SINGLE: Single-file sandbox (the server runs from the notebook's
- script environment)
- - MULTI: Multi-file sandbox (IPC kernels with per-notebook venvs)
- """
-
- SINGLE = "single"
- MULTI = "multi"
-
-
LOGGER = _loggers.marimo_logger()
@@ -104,62 +94,19 @@ def maybe_prompt_run_in_sandbox(name: str | None) -> bool:
return False
-def resolve_sandbox_mode(
- sandbox: bool | None, name: str | None
-) -> SandboxMode | None:
- """Determine sandbox mode for the given target.
-
- Returns:
- - None: No sandboxing
- - 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
- (only for single notebooks, not directories).
- """
- # Determine if target is a directory (or None = current directory)
- is_directory = name is None or os.path.isdir(name)
-
- # When the sandbox flag is omitted we infer whether to
- # start in sandbox mode by examining the notebook file and
- # prompting the user. Only prompt for single notebooks, not directories.
- if sandbox is None:
- # Don't prompt for directories - user must explicitly pass --sandbox
- if not is_directory:
- sandbox = maybe_prompt_run_in_sandbox(name)
- else:
- sandbox = False
-
- if not sandbox:
- return None
-
- # Sandbox enabled - determine mode based on target type
- # Directory or home page -> multi-file sandbox (IPC kernels)
- # Single file -> single-file sandbox (server in the script environment)
- return SandboxMode.MULTI if is_directory else SandboxMode.SINGLE
-
-
def resolve_sandbox(
sandbox: str | None,
no_sandbox: bool,
name: str | None,
-) -> tuple[SandboxMode | None, SandboxBackend]:
- """Resolve the sandbox mode and backend from the CLI flags.
-
- `sandbox` is None (unset; the user may be prompted), "uv" (a bare
- `--sandbox`), or a named backend (`--sandbox=pixi`). `no_sandbox`
- disables sandboxing and the prompt.
- """
- enabled: bool | None
+) -> SandboxBackend | None:
+ """Select a backend, prompting only for a notebook with dependencies."""
if no_sandbox:
- enabled = False
- elif sandbox is None:
- enabled = None
- else:
- enabled = True
- mode = resolve_sandbox_mode(sandbox=enabled, name=name)
- return mode, backend_from_flag(sandbox)
+ return None
+ if sandbox is not None:
+ return backend_from_flag(sandbox)
+ if maybe_prompt_run_in_sandbox(name):
+ return "uv"
+ return None
def backend_from_flag(sandbox: str | None) -> SandboxBackend:
@@ -167,6 +114,45 @@ def backend_from_flag(sandbox: str | None) -> SandboxBackend:
return "pixi" if sandbox == "pixi" else "uv"
+def ensure_server_environment(
+ backend: SandboxBackend | None, *, stdin_notebook: str | None = None
+) -> None:
+ """Relaunch the editor with server tools, leaving kernels lazy."""
+ if (
+ backend is None
+ or os.environ.pop("MARIMO_SERVER_OVERLAY", None) is not None
+ ):
+ return
+
+ from marimo._environments.backends import launch_server
+ from marimo._environments.errors import EnvironmentManagerError
+
+ try:
+ require_sandbox_backend(backend)
+ except EnvironmentManagerError as error:
+ raise MarimoCLIRuntimeError(str(error)) from error
+ args = _strip_sandbox_args(sys.argv[1:])
+ # Preserve a prompted choice and keep options before notebook arguments.
+ index = args.index("--") if "--" in args else len(args)
+ args[index:index] = [f"--sandbox={backend}"]
+ if stdin_notebook is not None:
+ # The outer process already consumed stdin and owns this temp file.
+ args.insert(index, stdin_notebook)
+ sys.exit(
+ _wait_on_plan(
+ launch_server(
+ ["-m", "marimo", *args],
+ backend=backend,
+ base_env={
+ **os.environ,
+ "MARIMO_SERVER_OVERLAY": "1",
+ "MARIMO_ANCESTOR_PID": str(os.getpid()),
+ },
+ )
+ )
+ )
+
+
def _is_versioned(dependency: str) -> bool:
return any(c in dependency for c in ("==", ">=", "<=", ">", "<", "~"))
@@ -411,6 +397,27 @@ def construct_uv_command(
return uv_cmd + cmd
+def require_sandbox_backend(backend: SandboxBackend) -> None:
+ """Check the backend and report installation instructions if missing."""
+ from marimo._environments import backends
+ from marimo._environments.errors import EnvironmentManagerNotFoundError
+
+ try:
+ backends.ensure_available(backend)
+ except EnvironmentManagerNotFoundError as e:
+ option = "--sandbox=pixi" if backend == "pixi" else "--sandbox"
+ install_url = (
+ "https://pixi.prefix.dev/latest/installation/"
+ if backend == "pixi"
+ else "https://docs.astral.sh/uv/getting-started/installation/"
+ )
+ raise MarimoCLIMissingDependencyError(
+ f"{backend} must be installed to use {option}.",
+ backend,
+ additional_tip=f"Install {backend} from {install_url}",
+ ) from e
+
+
def run_in_sandbox(
args: list[str],
*,
@@ -434,27 +441,11 @@ def run_in_sandbox(
Used for "single" sandbox mode (marimo edit --sandbox notebook.py).
For "multi" sandbox mode (directory), see IPCKernelManagerImpl.
"""
- from marimo._environments import backends
- from marimo._environments.errors import (
- EnvironmentManagerError,
- EnvironmentManagerNotFoundError,
- )
+ from marimo._environments.errors import EnvironmentManagerError
from marimo._environments.sandbox import NotebookSandbox
try:
- backends.ensure_available(backend)
- except EnvironmentManagerNotFoundError as e:
- option = "--sandbox=pixi" if backend == "pixi" else "--sandbox"
- install_url = (
- "https://pixi.prefix.dev/latest/installation/"
- if backend == "pixi"
- else "https://docs.astral.sh/uv/getting-started/installation/"
- )
- raise MarimoCLIMissingDependencyError(
- f"{backend} must be installed to use {option}.",
- backend,
- additional_tip=f"Install {backend} from {install_url}",
- ) from e
+ require_sandbox_backend(backend)
except EnvironmentManagerError as e:
# e.g. an environment manager too old for script environments.
echo(str(e), err=True)
@@ -522,12 +513,16 @@ def run_in_sandbox(
if not overridden and (name is None or os.path.isfile(name)):
notebook_sandbox = NotebookSandbox(name, backend)
try:
- plan = notebook_sandbox.launch(
- cmd,
- overlay=overlay,
- base_env=env,
- python_override=python_request if backend == "uv" else None,
- on_output=lambda _line: None,
+ plan = asyncio.run(
+ notebook_sandbox.launch_async(
+ cmd,
+ overlay=overlay,
+ base_env=env,
+ python_override=python_request
+ if backend == "uv"
+ else None,
+ on_output=lambda _line: None,
+ )
)
handle = notebook_sandbox.environment
assert handle is not None
@@ -543,6 +538,9 @@ def run_in_sandbox(
notebook_sandbox.close()
echo(str(e), err=True)
return getattr(e, "returncode", None) or 1
+ except BaseException:
+ notebook_sandbox.close()
+ raise
if plan is None:
if backend == "pixi":
@@ -558,7 +556,7 @@ def run_in_sandbox(
for line in _resolve_requirements_txt_lines(pyproject)
if line.strip() and not is_marimo_dependency(line)
] + requirements
- from marimo._environments.environment import launch_isolated
+ from marimo._environments.backends import launch_isolated
# The one resolve the parent environment cannot serve: an
# overridden interpreter under external constraints.
@@ -590,6 +588,8 @@ def _strip_sandbox_args(cmd: list[str]) -> list[str]:
continue
if token == "--sandbox":
index += 1
+ if index < len(cmd) and cmd[index] in ("uv", "pixi"):
+ index += 1
continue
stripped.append(token)
index += 1
diff --git a/marimo/_environments/backends.py b/marimo/_environments/backends.py
index 31ce32837a..31c2689823 100644
--- a/marimo/_environments/backends.py
+++ b/marimo/_environments/backends.py
@@ -13,9 +13,6 @@ Both managers honor the runtime overlay: uv layers it directly via
prefix's site-packages. Either way the manifest carries only a loose
`marimo` (for standalone runs) and the overlay supplies the running
version.
-
-SINGLE and MULTI sandbox modes are topologies, not engines: they differ
-in which process gets launched, not in how environments are made.
"""
from __future__ import annotations
@@ -110,6 +107,98 @@ def launch(
)
+async def sync_notebook_async(
+ path: str,
+ *,
+ backend: Backend,
+ python_override: str | None = None,
+ on_output: Callable[[str], None] | None = None,
+) -> Environment:
+ """Synchronize cancellably, keeping the carrier until the command exits."""
+ from marimo._environments import script_metadata
+
+ adapter = adapter_for(backend)
+ await adapter.ensure_available_async()
+ async with script_metadata.materialized_for_environment_async(
+ path
+ ) as target:
+ return await adapter.sync_async(
+ target, python_override=python_override, on_output=on_output
+ )
+
+
+def _uv_launcher(backend: Backend) -> tuple[str, ...]:
+ if backend == "pixi":
+ from marimo._environments.pixi import UV_OVERLAY_SPEC, require_pixi_bin
+
+ return (
+ require_pixi_bin(),
+ "exec",
+ "--spec",
+ UV_OVERLAY_SPEC,
+ "uv",
+ )
+ from marimo._environments.uv import require_uv_bin
+
+ return (require_uv_bin(),)
+
+
+def launch_server(
+ args: Sequence[str],
+ *,
+ backend: Backend,
+ base_env: Mapping[str, str] | None = None,
+) -> ProcessPlan:
+ """Layer editor tools over the host Python, independently of notebooks."""
+ from marimo._environments import environment
+ from marimo._environments.overlay import runtime_overlay
+
+ return environment.launch(
+ environment.Environment(sys.executable, sys.prefix, "unchanged"),
+ args,
+ overlay=runtime_overlay(["lsp"]),
+ base_env=base_env,
+ launcher=_uv_launcher(backend),
+ )
+
+
+def launch_isolated(
+ args: Sequence[str],
+ *,
+ requirements: Sequence[str],
+ python: str,
+ backend: Backend = "uv",
+ base_env: Mapping[str, str] | None = None,
+) -> ProcessPlan:
+ """Plan an ephemeral Python environment using the selected backend.
+
+ Used for command dependencies and constrained interpreter overrides,
+ independently of any notebook's environment or metadata.
+ """
+ from marimo._environments.environment import ProcessPlan, _with_args
+
+ 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=(
+ *_uv_launcher(backend),
+ "run",
+ "--isolated",
+ "--no-project",
+ "--compile-bytecode",
+ "--python",
+ python,
+ *_with_args(requirements),
+ "--",
+ "python",
+ *args,
+ ),
+ env=env,
+ start_new_session=True,
+ )
+
+
def launch_fallback(
args: Sequence[str],
*,
@@ -168,6 +257,24 @@ class UvBackendAdapter(_ReportingBackendAdapter):
ensure_supported_uv()
+ async def ensure_available_async(self) -> None:
+ from marimo._environments.environment import ensure_supported_uv_async
+
+ await ensure_supported_uv_async()
+
+ async def prepare_source_async(self, source: str) -> None:
+ from marimo._environments import script_metadata
+
+ try:
+ await script_metadata.ensure_marimo_async(
+ source,
+ on_command=lambda command: self._report("prepare", command),
+ )
+ except Exception as error:
+ LOGGER.warning(
+ "Failed to add marimo to script metadata: %s", error
+ )
+
def prepare_source(self, source: str) -> None:
import subprocess
@@ -292,6 +399,25 @@ class UvBackendAdapter(_ReportingBackendAdapter):
tree = parse_uv_tree(completed.stdout)
return PackageState(packages=_flatten_tree(tree), tree=tree)
+ async def sync_async(
+ self,
+ target: MaterializedScript,
+ *,
+ python_override: str | None,
+ on_output: LogCallback | None,
+ active_environment: Environment | None = None,
+ ) -> Environment:
+ from marimo._environments.environment import sync_async
+
+ return await sync_async(
+ target.path,
+ cwd=target.directory,
+ python_override=python_override,
+ active_environment=active_environment,
+ on_output=on_output,
+ on_command=lambda argv: self._report("sync", argv),
+ )
+
def launch(
self,
environment: Environment,
@@ -321,6 +447,48 @@ class PixiBackendAdapter(_ReportingBackendAdapter):
pixi.require_pixi_bin()
pixi.ensure_supported_pixi()
+ async def ensure_available_async(self) -> None:
+ from marimo._environments import pixi
+
+ await pixi.ensure_supported_pixi_async()
+
+ async def prepare_source_async(self, source: str) -> None:
+ from marimo._environments import pixi
+
+ try:
+ await pixi.ensure_marimo_async(
+ source,
+ on_command=lambda command: self._report("prepare", command),
+ )
+ except Exception as error:
+ LOGGER.warning(
+ "Failed to add marimo to script metadata: %s", error
+ )
+
+ async def sync_async(
+ self,
+ target: MaterializedScript,
+ *,
+ python_override: str | None,
+ on_output: LogCallback | None,
+ active_environment: Environment | None = None,
+ ) -> Environment:
+ from marimo._environments import pixi
+
+ if python_override is not None:
+ raise pixi.PixiError(
+ "pixi sandboxes do not support a Python version override"
+ )
+ environment = await pixi.sync_async(
+ target.path,
+ cwd=target.directory,
+ on_output=on_output,
+ on_command=lambda command: self._report("sync", command),
+ )
+
+ self._check_active_environment(environment, active_environment)
+ return environment
+
def prepare_source(self, source: str) -> None:
import subprocess
@@ -396,6 +564,13 @@ class PixiBackendAdapter(_ReportingBackendAdapter):
on_output=on_output,
on_command=lambda command: self._report("sync", command),
)
+ self._check_active_environment(environment, active_environment)
+ return environment
+
+ @staticmethod
+ def _check_active_environment(
+ environment: Environment, active_environment: Environment | None
+ ) -> None:
if active_environment is not None and os.path.realpath(
environment.root
) != os.path.realpath(active_environment.root):
@@ -412,7 +587,6 @@ class PixiBackendAdapter(_ReportingBackendAdapter):
"in a new environment. Restart the kernel to use the updated "
"dependencies. Restarting clears in-memory variables."
)
- return environment
def packages(
self,
diff --git a/marimo/_environments/environment.py b/marimo/_environments/environment.py
index b031e966b4..5d1167c8ca 100644
--- a/marimo/_environments/environment.py
+++ b/marimo/_environments/environment.py
@@ -24,6 +24,7 @@ from marimo._environments.uv import (
require_uv_bin,
script_command_env,
uv,
+ uv_async,
uv_stream,
)
@@ -104,6 +105,7 @@ def launch(
*,
overlay: RuntimeOverlay,
base_env: Mapping[str, str] | None = None,
+ launcher: Sequence[str] | None = None,
) -> ProcessPlan:
"""Plans running `python <args...>` inside the environment.
@@ -121,7 +123,7 @@ def launch(
env = environment.process_env(base_env)
return ProcessPlan(
argv=(
- require_uv_bin(),
+ *(launcher if launcher is not None else (require_uv_bin(),)),
"run",
# The script environment is VIRTUAL_ENV in `env`; --active
# makes uv layer on top of it instead of ignoring it.
@@ -139,46 +141,6 @@ def launch(
)
-def launch_isolated(
- args: Sequence[str],
- *,
- requirements: Sequence[str],
- python: str,
- base_env: Mapping[str, str] | None = None,
-) -> ProcessPlan:
- """Plans `python <args...>` in an ephemeral environment.
-
- For resolves no existing environment can serve: an overridden
- interpreter under external constraints (html-wasm pins the Pyodide
- interpreter and resolution). Nothing is layered here, so unlike
- `launch` the requirements are the whole environment -- the notebook's
- dependencies as well as marimo's. uv resolves them 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(requirements),
- "--",
- "python",
- *args,
- ),
- env=env,
- start_new_session=True,
- )
-
-
def _with_args(requirements: Sequence[str]) -> list[str]:
"""`uv run` flags for layered requirements; `-e <path>` is editable."""
with_args: list[str] = []
@@ -211,6 +173,43 @@ def sync(
Raises `UvCommandError` on failure and never mutates `script`.
"""
ensure_supported_uv()
+ args, env = _sync_command(script, python_override, active_environment)
+ if on_output is not None:
+ completed = uv_stream(
+ args,
+ on_output,
+ env=env,
+ cwd=cwd,
+ on_command=on_command,
+ )
+ else:
+ completed = uv(args, env=env, cwd=cwd, on_command=on_command)
+ return _parse_report(completed.stdout)
+
+
+async def sync_async(
+ script: str,
+ *,
+ cwd: str | None = None,
+ python_override: str | None = None,
+ active_environment: Environment | None = None,
+ on_output: Callable[[str], None] | None = None,
+ on_command: Callable[[Sequence[str]], None] | None = None,
+) -> Environment:
+ """Synchronize without blocking; cancellation stops uv before returning."""
+ await ensure_supported_uv_async()
+ args, env = _sync_command(script, python_override, active_environment)
+ completed = await uv_async(
+ args, env=env, cwd=cwd, on_output=on_output, on_command=on_command
+ )
+ return _parse_report(completed.stdout)
+
+
+def _sync_command(
+ script: str,
+ python_override: str | None,
+ active_environment: Environment | None,
+) -> tuple[list[str], dict[str, str]]:
args = [
"sync",
"--script",
@@ -227,22 +226,22 @@ def sync(
# Never inherit VIRTUAL_ENV: it may name the runtime overlay.
env["VIRTUAL_ENV"] = active_environment.root
args.append("--active")
- if on_output is not None:
- completed = uv_stream(
- args,
- on_output,
- env=env,
- cwd=cwd,
- on_command=on_command,
- )
- else:
- completed = uv(args, env=env, cwd=cwd, on_command=on_command)
- return _parse_report(completed.stdout)
+ return args, env
def ensure_supported_uv() -> None:
"""Raise `UvUnsupportedVersionError` for a uv below the minimum."""
version = _uv_version()
+ _check_version(version)
+
+
+async def ensure_supported_uv_async() -> None:
+ completed = await uv_async(["--version"])
+ version = completed.stdout.strip().removeprefix("uv ").split(" ")[0]
+ _check_version(version)
+
+
+def _check_version(version: str) -> None:
parsed = _parse_version(version)
if parsed is None:
# An unparsable version is likely newer than anything we know;
diff --git a/marimo/_environments/errors.py b/marimo/_environments/errors.py
index f9f213b03f..57e3a9c44f 100644
--- a/marimo/_environments/errors.py
+++ b/marimo/_environments/errors.py
@@ -22,8 +22,9 @@ class MissingScriptMetadataError(EnvironmentManagerError):
class SandboxRestartRequired(EnvironmentManagerError):
- """The manifest synchronized, but not into the live kernel's prefix.
+ """Applying the manifest requires relaunching the kernel.
- This is not a solver failure. Callers must not report the requested
+ The active interpreter is incompatible, or synchronization selected a
+ different prefix. Callers must not report the requested
packages as importable until the kernel launches the new environment.
"""
diff --git a/marimo/_environments/pixi.py b/marimo/_environments/pixi.py
index 2de6a554d3..54fe16e365 100644
--- a/marimo/_environments/pixi.py
+++ b/marimo/_environments/pixi.py
@@ -123,6 +123,16 @@ def ensure_supported_pixi() -> None:
raise PixiUnsupportedVersionError()
+async def ensure_supported_pixi_async() -> None:
+ from marimo._environments.process import run_command
+
+ completed = await run_command(
+ [require_pixi_bin(), "install", "--help"], timeout=10
+ )
+ if completed.returncode != 0 or "--script" not in completed.stdout:
+ raise PixiUnsupportedVersionError()
+
+
# `pixi install --script` reports the environment on stderr:
# ✔ The script environment has been installed at '<prefix>'.
# A `--json` report is the upstream ask that retires this parse.
@@ -145,33 +155,43 @@ def sync(
on interpreter identity. Raises `PixiCommandError` on failure and
never mutates `script`.
"""
- from marimo._environments.environment import Environment
+ completed = _run(
+ _sync_command(script),
+ cwd=cwd,
+ on_output=on_output,
+ on_command=on_command,
+ )
+ return _parse_sync_report(completed.stderr)
- args = [
- require_pixi_bin(),
- "install",
- "--script",
- os.path.abspath(script),
- ]
+
+async def sync_async(
+ script: str,
+ *,
+ cwd: str | None = None,
+ on_output: Callable[[str], None] | None = None,
+ on_command: Callable[[Sequence[str]], None] | None = None,
+) -> Environment:
+ from marimo._environments.process import run_command
+
+ args = _sync_command(script)
if on_command is not None:
on_command(args)
- completed = subprocess.run(
- args,
- capture_output=True,
- text=True,
- encoding="utf-8",
- # pixi must never hang waiting for input.
- stdin=subprocess.DEVNULL,
- env=command_env(),
- cwd=cwd,
- start_new_session=os.name != "nt",
+ completed = await run_command(
+ args, env=command_env(), cwd=cwd, on_stderr=on_output
)
- if on_output is not None:
- for line in (completed.stdout + completed.stderr).splitlines(True):
- on_output(line)
if completed.returncode != 0:
raise _command_error(completed)
- report = _ANSI.sub("", completed.stderr)
+ return _parse_sync_report(completed.stderr)
+
+
+def _sync_command(script: str) -> list[str]:
+ return [require_pixi_bin(), "install", "--script", os.path.abspath(script)]
+
+
+def _parse_sync_report(stderr: str) -> Environment:
+ from marimo._environments.environment import Environment
+
+ report = _ANSI.sub("", stderr)
match = _INSTALLED_AT.search(report)
if match is None:
raise PixiError(
@@ -288,7 +308,8 @@ def tree_script_packages(script: str, *, cwd: str) -> str:
def _run(
args: Sequence[str],
*,
- cwd: str,
+ cwd: str | None,
+ timeout: float | None = None,
on_output: Callable[[str], None] | None = None,
on_command: Callable[[Sequence[str]], None] | None = None,
) -> subprocess.CompletedProcess[str]:
@@ -303,6 +324,7 @@ def _run(
stdin=subprocess.DEVNULL,
env=command_env(),
cwd=cwd,
+ timeout=timeout,
start_new_session=os.name != "nt",
)
if on_output is not None:
@@ -345,22 +367,12 @@ def ensure_marimo(
"--pypi",
"marimo",
]
- if on_command is not None:
- on_command(args)
- completed = subprocess.run(
+ _run(
args,
- capture_output=True,
- text=True,
- encoding="utf-8",
- # pixi must never hang waiting for input.
- stdin=subprocess.DEVNULL,
- env=command_env(),
cwd=os.path.dirname(os.path.abspath(path)),
timeout=60,
- start_new_session=os.name != "nt",
+ on_command=on_command,
)
- if completed.returncode != 0:
- raise _command_error(completed)
# The uv that applies launch overlays, fetched through `pixi exec` so
@@ -370,6 +382,41 @@ def ensure_marimo(
UV_OVERLAY_SPEC = "uv>=0.12"
+async def ensure_marimo_async(
+ path: str,
+ *,
+ on_command: Callable[[Sequence[str]], None] | None = None,
+) -> None:
+ from marimo._environments.process import run_command
+ from marimo._environments.script_metadata import (
+ ensure_metadata_block,
+ should_add_marimo,
+ )
+
+ if not should_add_marimo(path):
+ return
+ ensure_metadata_block(path)
+ absolute = os.path.abspath(path) # noqa: ASYNC240
+ args = [
+ require_pixi_bin(),
+ "add",
+ "--script",
+ absolute,
+ "--pypi",
+ "marimo",
+ ]
+ if on_command is not None:
+ on_command(args)
+ completed = await run_command(
+ args,
+ env=command_env(),
+ cwd=os.path.dirname(absolute),
+ timeout=60,
+ )
+ if completed.returncode != 0:
+ raise _command_error(completed)
+
+
# Run before importing marimo: importing a module in this package would first
# import marimo itself with pixi exec's *tool* environment still activated.
# exec preserves Python's normal -m/-c/script argument handling and signal PID.
diff --git a/marimo/_environments/process.py b/marimo/_environments/process.py
new file mode 100644
index 0000000000..66d8ab3453
--- /dev/null
+++ b/marimo/_environments/process.py
@@ -0,0 +1,84 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Awaitable sandbox commands with ownership of their subprocesses."""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+from typing import TYPE_CHECKING
+
+from marimo import _loggers
+from marimo._utils.subprocess import stop_subprocess
+
+if TYPE_CHECKING:
+ from collections.abc import Callable, Mapping, Sequence
+
+LOGGER = _loggers.marimo_logger()
+
+
+async def run_command(
+ argv: Sequence[str],
+ *,
+ env: Mapping[str, str] | None = None,
+ cwd: str | None = None,
+ timeout: float | None = None,
+ on_stderr: Callable[[str], None] | None = None,
+) -> subprocess.CompletedProcess[str]:
+ """Capture output and stream stderr without blocking the event loop.
+
+ The callback runs on the caller's event loop. Cancellation and timeout
+ stop the command's owned process group and finish reading its pipes before
+ returning. Nonzero exits are returned for the backend to interpret.
+ """
+ loop = asyncio.get_running_loop()
+
+ def report(line: str) -> None:
+ if on_stderr is not None:
+ try:
+ on_stderr(line)
+ except Exception:
+ LOGGER.exception("Failed to report sandbox output")
+
+ # Windows sessions use a selector loop, which has no asyncio subprocess
+ # support. Own Popen here; only pipe reads and waiting run on threads.
+ with subprocess.Popen( # noqa: ASYNC220
+ list(argv),
+ stdin=subprocess.DEVNULL,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE,
+ text=True,
+ encoding="utf-8",
+ errors="replace",
+ env=env,
+ cwd=cwd,
+ start_new_session=True,
+ ) as process:
+ assert process.stdout is not None
+ assert process.stderr is not None
+ stderr_pipe = process.stderr
+
+ def read_stderr() -> str:
+ lines: list[str] = []
+ for line in stderr_pipe:
+ lines.append(line)
+ if on_stderr is not None:
+ loop.call_soon_threadsafe(report, line)
+ process.wait()
+ return "".join(lines)
+
+ output = asyncio.gather(
+ loop.run_in_executor(None, process.stdout.read),
+ loop.run_in_executor(None, read_stderr),
+ )
+ try:
+ stdout, stderr = await asyncio.wait_for(
+ asyncio.shield(output), timeout=timeout
+ )
+ except BaseException:
+ await stop_subprocess(
+ process, start_new_session=True, drain=output
+ )
+ raise
+ return subprocess.CompletedProcess(
+ list(argv), process.returncode, stdout, stderr
+ )
diff --git a/marimo/_environments/sandbox.py b/marimo/_environments/sandbox.py
index 7729cd3c76..d9fc74eeb4 100644
--- a/marimo/_environments/sandbox.py
+++ b/marimo/_environments/sandbox.py
@@ -11,12 +11,19 @@ from __future__ import annotations
import re
import shlex
+import subprocess
import tempfile
from collections.abc import Callable
from dataclasses import dataclass
+from pathlib import Path
from typing import TYPE_CHECKING, Literal, Protocol
from marimo._environments import script_metadata
+from marimo._environments.errors import (
+ EnvironmentManagerError,
+ SandboxRestartRequired,
+)
+from marimo._environments.process import run_command
if TYPE_CHECKING:
from collections.abc import Mapping, Sequence
@@ -99,8 +106,21 @@ class BackendAdapter(Protocol):
def ensure_available(self) -> None: ...
+ async def ensure_available_async(self) -> None: ...
+
def prepare_source(self, source: str) -> None: ...
+ async def prepare_source_async(self, source: str) -> None: ...
+
+ async def sync_async(
+ self,
+ target: MaterializedScript,
+ *,
+ python_override: str | None,
+ on_output: LogCallback | None,
+ active_environment: Environment | None = None,
+ ) -> Environment: ...
+
def add(
self,
target: MaterializedScript,
@@ -292,6 +312,60 @@ class NotebookSandbox:
environment = self._sync(
python_override=python_override, on_output=on_output
)
+ return self._launch_plan(environment, args, overlay, base_env)
+
+ async def launch_async(
+ self,
+ args: Sequence[str],
+ *,
+ overlay: RuntimeOverlay,
+ base_env: Mapping[str, str] | None = None,
+ python_override: str | None = None,
+ on_output: LogCallback | None = None,
+ ) -> ProcessPlan:
+ """Prepare cancellably; publish the environment only after success."""
+ await self._adapter.ensure_available_async()
+ script_metadata.ensure_metadata_block(self._source)
+ await self._adapter.prepare_source_async(self._source)
+ async with script_metadata.materialized_for_environment_async(
+ self._source
+ ) as target:
+ environment = await self._adapter.sync_async(
+ target, python_override=python_override, on_output=on_output
+ )
+ self._environment = environment
+ self._environment_source = self._source
+ return self._launch_plan(environment, args, overlay, base_env)
+
+ async def sync_async(self) -> None:
+ """Apply the saved manifest to the environment used by this kernel."""
+ await self._adapter.ensure_available_async()
+ async with script_metadata.materialized_for_environment_async(
+ self._source
+ ) as target:
+ requirement = _python_requirement(target, self._environment)
+ if requirement is not None:
+ assert self._environment is not None
+ completed = await run_command(
+ [self._environment.python, "-I", "-S", "--version"]
+ )
+ _check_python_requirement(requirement, completed)
+ environment = await self._adapter.sync_async(
+ target,
+ python_override=None,
+ on_output=None,
+ active_environment=self._environment,
+ )
+ self._environment = environment
+ self._environment_source = self._source
+
+ def _launch_plan(
+ self,
+ environment: Environment,
+ args: Sequence[str],
+ overlay: RuntimeOverlay,
+ base_env: Mapping[str, str] | None,
+ ) -> ProcessPlan:
plan = self._adapter.launch(
environment,
args,
@@ -426,20 +500,7 @@ class NotebookSandbox:
with script_metadata.materialized_for_environment(
self._source
) as target:
- state = self._adapter.packages(target, self._environment)
- packages = tuple(
- package
- for package in state.packages
- if _normalize_dependency_name(package.name) != "marimo"
- )
- tree = state.tree
- if tree is not None:
- tree.dependencies = [
- dependency
- for dependency in tree.dependencies
- if _normalize_dependency_name(dependency.name) != "marimo"
- ]
- return PackageState(packages=packages, tree=tree)
+ return self._adapter.packages(target, self._environment)
def _reopened_requirement(
self, bare: _BareRequirement
@@ -553,6 +614,15 @@ class NotebookSandbox:
with script_metadata.materialized_for_environment(
self._source
) as target:
+ requirement = _python_requirement(target, active_environment)
+ if requirement is not None:
+ assert active_environment is not None
+ completed = subprocess.run(
+ [active_environment.python, "-I", "-S", "--version"],
+ capture_output=True,
+ text=True,
+ )
+ _check_python_requirement(requirement, completed)
environment = self._adapter.sync(
target,
python_override=python_override,
@@ -564,6 +634,47 @@ class NotebookSandbox:
return environment
+def _python_requirement(
+ target: MaterializedScript, active_environment: Environment | None
+) -> str | None:
+ if active_environment is None:
+ return None
+ project = script_metadata.loads(Path(target.path).read_text("utf-8"))
+ requirement = (
+ project.get("requires-python") if project is not None else None
+ )
+ if requirement is not None and not isinstance(requirement, str):
+ raise script_metadata.ScriptMetadataError(
+ "requires-python must be a version specifier string"
+ )
+ return requirement
+
+
+def _check_python_requirement(
+ requirement: str, completed: subprocess.CompletedProcess[str]
+) -> None:
+ from packaging.specifiers import InvalidSpecifier, SpecifierSet
+
+ try:
+ specifier = SpecifierSet(requirement)
+ except InvalidSpecifier as error:
+ raise script_metadata.ScriptMetadataError(
+ f"Invalid requires-python: {requirement}"
+ ) from error
+ if completed.returncode != 0:
+ raise EnvironmentManagerError(
+ "Could not determine the active sandbox's Python version.\n"
+ + completed.stderr
+ )
+ version = completed.stdout.strip().removeprefix("Python ")
+ if not specifier.contains(version, prereleases=True):
+ raise SandboxRestartRequired(
+ f"The manifest requires Python {requirement}, but the running "
+ f"kernel uses Python {version}. Restart the kernel to apply "
+ "the new Python requirement."
+ )
+
+
def _normalize_dependency_name(requirement: str) -> str:
match = re.match(r"[A-Za-z0-9][A-Za-z0-9._-]*", requirement.strip())
if match is None:
diff --git a/marimo/_environments/script_metadata.py b/marimo/_environments/script_metadata.py
index 05d9a79578..c5f32a5196 100644
--- a/marimo/_environments/script_metadata.py
+++ b/marimo/_environments/script_metadata.py
@@ -16,8 +16,10 @@ so directory-scoped configuration applies.
from __future__ import annotations
+import asyncio
import contextlib
import errno
+import hashlib
import os
import platform
import re
@@ -39,18 +41,20 @@ from marimo._environments.uv import (
UvError,
script_command_env,
uv,
+ uv_async,
uv_stream,
)
from marimo._utils.toml import toml_reader
+from marimo._utils.xdg import marimo_state_dir
if TYPE_CHECKING:
- from collections.abc import Callable, Iterator, Sequence
+ from collections.abc import AsyncIterator, Callable, Iterator, Sequence
LOGGER = _loggers.marimo_logger()
REGEX = (
- r"(?m)^# /// (?P<type>[a-zA-Z0-9-]+)$\s"
- r"(?P<content>(^#(?! ///$)(| .*)$\s)+)^# ///$"
+ r"(?m)^# /// (?P<type>[a-zA-Z0-9-]+)\r?$\n"
+ r"(?P<content>(^#(?! ///\r?$)(| .*)\r?$\n)+)^# ///(?=\r?$)"
)
@@ -58,6 +62,66 @@ class ScriptMetadataError(EnvironmentManagerError):
"""A script metadata edit could not be completed."""
+class ManifestConflictError(ScriptMetadataError):
+ """The manifest changed after it was opened for editing."""
+
+
+def _manifest_text(script: str) -> tuple[re.Match[str] | None, str]:
+ matches = [
+ match
+ for match in re.finditer(REGEX, script)
+ if match.group("type") == "script"
+ ]
+ if len(matches) > 1:
+ raise ScriptMetadataError("Multiple script metadata blocks found")
+ if not matches:
+ return None, ""
+ match = matches[0]
+ contents = "".join(
+ line[2:] if line.startswith("# ") else line[1:]
+ for line in match.group("content").splitlines(keepends=True)
+ )
+ return match, contents.replace("\r\n", "\n")
+
+
+def read_manifest(path: str) -> str:
+ """Read the original TOML, including malformed TOML that needs repair."""
+ if path.endswith((".md", ".qmd")):
+ return _manifest_text(_read_frontmatter(path).header)[1]
+ with open(path, encoding="utf-8", newline="") as file:
+ return _manifest_text(file.read())[1]
+
+
+def write_manifest(path: str, contents: str, *, previous: str) -> str:
+ """Replace only metadata, rejecting stale edits and invalid TOML."""
+ toml_reader.reads(contents)
+ if any(line == "///" for line in contents.splitlines()):
+ raise ScriptMetadataError("The manifest cannot contain script markers")
+ with notebook_file_lock(path), materialized_for_edit(path) as target:
+ file = Path(target.path)
+ with file.open(encoding="utf-8", newline="") as source:
+ script = source.read()
+ match, current = _manifest_text(script)
+ if current != previous:
+ raise ManifestConflictError(
+ "The manifest changed on disk. Reopen it before saving."
+ )
+ newline = "\r\n" if "\r\n" in script else "\n"
+ block = wrap_block(contents.replace("\r\n", "\n")).replace(
+ "\n", newline
+ )
+ if match is not None:
+ updated = script[: match.start()] + block + script[match.end() :]
+ elif script.startswith("#!"):
+ shebang, _, rest = script.partition("\n")
+ updated = f"{shebang}\n{block}{newline}{rest}"
+ else:
+ updated = f"{block}{newline}{script}"
+ with file.open("w", encoding="utf-8", newline="") as destination:
+ destination.write(updated)
+ return read_manifest(path)
+
+
def loads(script: str) -> dict[str, Any] | None:
"""Parse the `# /// script` block, or None if the script has none.
@@ -121,7 +185,7 @@ def metadata_transaction(path: str) -> Iterator[None]:
try:
yield
except SandboxRestartRequired:
- # Synchronization succeeded; the live kernel uses a different prefix.
+ # Keep the requested manifest so the restart can apply it.
raise
except (Exception, KeyboardInterrupt):
if _metadata_block(path) == block:
@@ -295,6 +359,24 @@ def ensure_marimo(
_edit(path, edit)
+async def ensure_marimo_async(
+ path: str,
+ *,
+ on_command: Callable[[Sequence[str]], None] | None = None,
+) -> None:
+ if not should_add_marimo(path):
+ return
+ ensure_metadata_block(path)
+ with materialized_for_edit(path) as target:
+ await uv_async(
+ ["add", "--script", target.path, "marimo"],
+ env=script_command_env(),
+ timeout=30,
+ cwd=target.directory,
+ on_command=on_command,
+ )
+
+
def ensure_requires_python(path: str) -> None:
"""Add `requires-python` to existing script metadata if not present.
@@ -388,23 +470,54 @@ def _carrier_prefix(path: str) -> str:
@contextlib.contextmanager
-def _stable_carrier_lock(path: str) -> Iterator[None]:
- """Hold an OS lock through creation, use, and removal of the carrier.
+def notebook_file_lock(path: str) -> Iterator[None]:
+ """Serialize notebook read-modify-write operations across processes.
+
+ Keep this separate from the carrier lock: async environment operations
+ hold that lock while yielding, but notebook saves can run on the event loop.
+ """
+ with _file_lock(_notebook_lock_path(path), blocking=True):
+ yield
+
+
+def _notebook_lock_path(path: str) -> Path:
+ # Processes may have different temporary directories for the same notebook.
+ directory = marimo_state_dir() / "notebook-locks"
+ directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+ key = hashlib.sha256(
+ os.path.normcase(os.path.realpath(path)).encode()
+ ).hexdigest()
+ return directory / f"{key}.lock"
+
+
+def _stable_carrier_lock(
+ path: str, *, blocking: bool = True
+) -> Iterator[None]:
+ # Carrier lifetimes can span async environment operations, so they must
+ # use a different lock from notebook writes.
+ target = _notebook_lock_path(path).with_suffix(".carrier.lock")
+ with _file_lock(target, blocking=blocking):
+ yield
+
+
+def _file_lock(target: Path, *, blocking: bool) -> Iterator[None]:
+ """Hold an OS lock on a persistent file.
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.
"""
- 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}")
+ raise OSError(f"Refusing to use symlink as lock file: {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}")
+ raise OSError(f"Lock file is not a regular file: {target}")
if sys.platform == "win32":
import msvcrt
@@ -415,6 +528,8 @@ def _stable_carrier_lock(path: str) -> Iterator[None]:
except OSError as error:
if error.errno not in (errno.EACCES, errno.EDEADLK):
raise
+ if not blocking:
+ raise BlockingIOError from error
time.sleep(0.05)
try:
yield
@@ -423,7 +538,10 @@ def _stable_carrier_lock(path: str) -> Iterator[None]:
else:
import fcntl
- fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+ fcntl.flock(
+ lock.fileno(),
+ fcntl.LOCK_EX | (0 if blocking else fcntl.LOCK_NB),
+ )
try:
yield
finally:
@@ -545,8 +663,34 @@ def materialized_for_environment(path: str) -> Iterator[MaterializedScript]:
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.
+ threads and processes; its persistent file lives in marimo's state directory.
"""
+ with _materialized_for_environment(path, blocking=True) as target:
+ yield target
+
+
+async def materialized_for_environment_async(
+ path: str,
+) -> AsyncIterator[MaterializedScript]:
+ """Wait cancellably for the same carrier lock used by synchronous callers."""
+ with contextlib.ExitStack() as stack:
+ while True:
+ try:
+ target = stack.enter_context(
+ _materialized_for_environment(path, blocking=False)
+ )
+ break
+ except BlockingIOError:
+ # OS file locks have no portable readiness notification.
+ await asyncio.sleep(0.05)
+ yield target
+
+
+def _materialized_for_environment(
+ path: str, *, blocking: bool
+) -> Iterator[MaterializedScript]:
absolute = os.path.abspath(path)
directory = os.path.dirname(absolute)
if not path.endswith((".md", ".qmd")):
@@ -555,12 +699,15 @@ def materialized_for_environment(path: str) -> Iterator[MaterializedScript]:
with contextlib.ExitStack() as stack:
try:
- stack.enter_context(_stable_carrier_lock(absolute))
+ stack.enter_context(
+ _stable_carrier_lock(absolute, blocking=blocking)
+ )
+ except BlockingIOError:
+ raise
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."
+ f"Cannot lock a metadata carrier for {path}. "
+ f"Check the lock directory's permissions and files: {error}"
) from error
content = (
"# Generated by marimo; safe to delete.\n"
diff --git a/marimo/_environments/uv.py b/marimo/_environments/uv.py
index 424a4a9c1c..a6cd2194da 100644
--- a/marimo/_environments/uv.py
+++ b/marimo/_environments/uv.py
@@ -189,6 +189,42 @@ def uv(
return completed
+async def uv_async(
+ args: Sequence[str],
+ *,
+ env: Mapping[str, str] | None = None,
+ cwd: str | None = None,
+ timeout: float | None = None,
+ on_output: Callable[[str], None] | None = None,
+ on_command: Callable[[Sequence[str]], None] | None = None,
+) -> subprocess.CompletedProcess[str]:
+ """Await a uv command, retaining typed errors and cancellation cleanup."""
+ from marimo._environments.process import run_command
+
+ command = [find_uv_bin(), *args]
+ if on_command is not None:
+ on_command(command)
+ try:
+ completed = await run_command(
+ command,
+ env=env,
+ cwd=cwd,
+ timeout=timeout,
+ on_stderr=(lambda line: _stream_output(line, on_output))
+ if on_output is not None
+ else None,
+ )
+ except OSError as error:
+ if cwd is not None:
+ os.stat(cwd) # noqa: ASYNC240
+ if isinstance(error, FileNotFoundError):
+ raise UvNotFoundError() from error
+ raise
+ if completed.returncode != 0:
+ raise _refine(completed)
+ return completed
+
+
def uv_stream(
args: Sequence[str],
on_output: Callable[[str], None],
@@ -249,22 +285,7 @@ def uv_stream(
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")
+ _stream_output(decoded, on_output)
returncode = process.wait()
except BaseException:
kill_subprocess(process, start_new_session=True)
@@ -284,6 +305,23 @@ def uv_stream(
return completed
+def _stream_output(line: str, on_output: Callable[[str], None]) -> None:
+ # Kernel stderr may be redirected; reporting must never stop pipe reads.
+ try:
+ buffer = getattr(sys.stderr, "buffer", None)
+ if buffer is not None:
+ buffer.write(line.encode("utf-8"))
+ buffer.flush()
+ else:
+ sys.stderr.write(line)
+ except Exception:
+ pass
+ try:
+ on_output(line)
+ except Exception:
+ LOGGER.exception("Failed to stream uv output")
+
+
def script_command_env() -> dict[str, str]:
"""Environment for uv script commands.
diff --git a/marimo/_export/file.py b/marimo/_export/file.py
index d2c03a43c9..18ce6ec5fc 100644
--- a/marimo/_export/file.py
+++ b/marimo/_export/file.py
@@ -652,7 +652,7 @@ async def run_notebook(
# Create a session
session_consumer = RunUntilCompletionSessionConsumer()
- session = SessionImpl.create(
+ session = await SessionImpl.create(
# Any initialization ID will do
initialization_id="_any_",
session_consumer=session_consumer,
diff --git a/marimo/_messaging/notification.py b/marimo/_messaging/notification.py
index fb0bcf2800..8a8f6ff46e 100644
--- a/marimo/_messaging/notification.py
+++ b/marimo/_messaging/notification.py
@@ -37,6 +37,7 @@ from marimo._messaging.notebook.changes import Transaction
from marimo._plugins.core.web_component import JSONType
from marimo._runtime.layout.layout import LayoutConfig
from marimo._secrets.models import SecretKeysWithProvider
+from marimo._session.model import StartupPhase
from marimo._sql.parse import SqlCatalogCheckResult, SqlParseResult
from marimo._types.ids import (
CellId_t,
@@ -565,6 +566,13 @@ class BannerNotification(Notification, tag="banner"):
action: Literal["restart"] | None = None
+class StartupProgressNotification(Notification, tag="startup-progress"):
+ """Progress reported before a session's kernel is ready."""
+
+ name: ClassVar[str] = "startup-progress"
+ phase: StartupPhase
+
+
class KernelStartupErrorNotification(Notification, tag="kernel-startup-error"):
"""Kernel failed to start.
@@ -1018,6 +1026,7 @@ NotificationMessage = (
| MissingPackageAlertNotification
| InstallingPackageAlertNotification
| StartupLogsNotification
+ | StartupProgressNotification
| KernelStartupErrorNotification
# Variables
| VariablesNotification
diff --git a/marimo/_server/api/endpoints/assets.py b/marimo/_server/api/endpoints/assets.py
index 448c1f89a0..3ed8bc653f 100644
--- a/marimo/_server/api/endpoints/assets.py
+++ b/marimo/_server/api/endpoints/assets.py
@@ -19,7 +19,6 @@ from starlette.responses import (
from starlette.staticfiles import StaticFiles
from marimo import _loggers
-from marimo._cli.sandbox import SandboxMode
from marimo._config.manager import get_default_config_manager
from marimo._config.reader import find_nearest_pyproject_toml
from marimo._config.settings import GLOBAL_SETTINGS
@@ -390,11 +389,11 @@ async def index(request: Request) -> Response:
absolute_filepath = app_manager.filename
# Pre-compute notebook snapshot for faster initial render
- # Only in EDIT + SandboxMode.MULTI where each notebook gets its own IPC
+ # Only in sandboxed edit mode where each notebook gets its own IPC
# kernel.
notebook_snapshot = None
if (
- app_state.session_manager.sandbox_mode is SandboxMode.MULTI
+ app_state.session_manager.sandbox
and app_state.mode == SessionMode.EDIT
and app_manager.filename
):
diff --git a/marimo/_server/api/endpoints/editing.py b/marimo/_server/api/endpoints/editing.py
index 5bc53faa4d..038400b6af 100644
--- a/marimo/_server/api/endpoints/editing.py
+++ b/marimo/_server/api/endpoints/editing.py
@@ -5,7 +5,6 @@ from typing import TYPE_CHECKING
from starlette.authentication import requires
-from marimo._cli.sandbox import SandboxMode
from marimo._messaging.notification import FocusCellNotification
from marimo._server.api.deps import AppState
from marimo._server.api.utils import (
@@ -149,15 +148,11 @@ async def format_cell(request: Request) -> FormatResponse:
codes = await formatter.format(body.codes, filename)
return FormatResponse(codes)
except ModuleNotFoundError:
- # In multi-sandbox mode each kernel has its own venv, so installing
- # ruff into the server wouldn't help the kernel. Just surface the
- # error without an install prompt.
- if app_state.session_manager.sandbox_mode is SandboxMode.MULTI:
+ # Sandboxed kernels cannot install the server's formatter.
+ if app_state.session_manager.sandbox:
raise ModuleNotFoundError(
"Server does not have a formatter. Please install ruff"
) from None
- # For single-sandbox and non-sandbox modes the server *is* the
- # formatting environment, so offer to install ruff there.
notify_server_missing_packages(
app_state.get_current_session(),
app_state.get_current_session_id(),
diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.py
index fa8e418f96..b6d68a9f67 100644
--- a/marimo/_server/api/endpoints/execution.py
+++ b/marimo/_server/api/endpoints/execution.py
@@ -557,8 +557,8 @@ async def shutdown(
session_manager = app_state.session_manager
workspace = session_manager.workspace
- def shutdown_server() -> None:
- app_state.session_manager.shutdown()
+ async def shutdown_server() -> None:
+ await app_state.session_manager.shutdown()
close_uvicorn(app_state.server)
# If we are only operating on a single file (new or explicit file),
@@ -566,18 +566,18 @@ async def shutdown(
# from the file explorer) then we should shutdown the whole server
key = workspace.get_unique_file_key()
if key and len(session_manager.sessions) <= 1:
- shutdown_server()
+ await shutdown_server()
return SuccessResponse()
# Otherwise, get the session
session_id = app_state.get_current_session_id()
if not session_id:
- shutdown_server()
+ await shutdown_server()
return SuccessResponse()
was_shutdown = session_manager.close_session(session_id)
if not was_shutdown:
- shutdown_server()
+ await shutdown_server()
return SuccessResponse()
diff --git a/marimo/_server/api/endpoints/packages.py b/marimo/_server/api/endpoints/packages.py
index 567e9da2db..5a22b2cf6b 100644
--- a/marimo/_server/api/endpoints/packages.py
+++ b/marimo/_server/api/endpoints/packages.py
@@ -7,6 +7,13 @@ from typing import TYPE_CHECKING
from starlette.authentication import requires
from marimo._config.settings import GLOBAL_SETTINGS
+from marimo._environments import script_metadata
+from marimo._environments.backends import current_backend
+from marimo._environments.errors import (
+ EnvironmentManagerError,
+ SandboxRestartRequired,
+)
+from marimo._environments.sandbox import Backend, NotebookSandbox
from marimo._runtime.packages.package_manager import PackageManager
from marimo._runtime.packages.package_managers import create_package_manager
from marimo._runtime.packages.sandbox_package_manager import (
@@ -24,8 +31,13 @@ from marimo._server.models.packages import (
PackageOperationResponse,
RemovePackageRequest,
SandboxPackageContext,
+ SandboxRequest,
+ SandboxResponse,
+ SyncSandboxResponse,
+ UpdateManifestRequest,
)
from marimo._server.router import APIRouter
+from marimo._utils.http import HTTPException
if TYPE_CHECKING:
from starlette.requests import Request
@@ -217,14 +229,10 @@ 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
- sandbox_environment = None
from marimo._session.managers.ipc import IPCKernelManagerImpl
from marimo._session.session import SessionImpl
if isinstance(session, SessionImpl):
- from marimo._environments.sandbox import NotebookSandbox
-
sandbox = session.notebook_sandbox
if isinstance(sandbox, NotebookSandbox):
return SandboxPackageManager(sandbox)
@@ -232,19 +240,10 @@ 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
- sandbox_environment = kernel_manager.script_environment
- 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,
- script_path=script_path,
- sandbox_environment=sandbox_environment,
)
@@ -261,3 +260,148 @@ def _get_filename(request: Request) -> str | None:
if session is None:
return None
return session.app_file_manager.filename
+
+
+def _sandbox_source(
+ request: Request, file_key: str | None, *, mutation: bool = False
+) -> tuple[NotebookSandbox | None, str | None, Backend | None]:
+ state = AppState(request)
+ manager = state.session_manager
+ if mutation and manager.is_session_starting(
+ state.require_current_session_id()
+ ):
+ raise HTTPException(409, "Wait for sandbox preparation to finish.")
+ session = state.get_current_session()
+ if session is not None:
+ sandbox = getattr(session, "notebook_sandbox", None)
+ if isinstance(sandbox, NotebookSandbox):
+ return sandbox, sandbox.source, sandbox.backend
+ return None, None, None
+ if not manager.sandbox:
+ return None, None, None
+ key = file_key or manager.workspace.get_unique_file_key()
+ path = manager.workspace.resolve(key) if key else None
+ return None, path, current_backend()
+
+
[email protected]("/sandbox")
+@requires("edit")
+async def get_sandbox(request: Request) -> SandboxResponse:
+ """
+ parameters:
+ - in: header
+ name: Marimo-Session-Id
+ schema:
+ type: string
+ required: true
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/SandboxRequest"
+ responses:
+ 200:
+ description: Sandbox manifest, available before kernel startup
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/SandboxResponse"
+ """
+ body = await parse_request(request, cls=SandboxRequest)
+ _, path, backend = _sandbox_source(request, body.file_key)
+ try:
+ manifest = (
+ await asyncio.to_thread(script_metadata.read_manifest, path)
+ if path is not None
+ else None
+ )
+ except (OSError, ValueError, EnvironmentManagerError) as error:
+ raise HTTPException(400, str(error)) from error
+ return SandboxResponse(backend=backend, manifest=manifest, filename=path)
+
+
[email protected]("/manifest")
+@requires("edit")
+async def update_manifest(request: Request) -> SandboxResponse:
+ """
+ parameters:
+ - in: header
+ name: Marimo-Session-Id
+ schema:
+ type: string
+ required: true
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/UpdateManifestRequest"
+ responses:
+ 200:
+ description: Save notebook metadata without changing its cells
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/SandboxResponse"
+ """
+ body = await parse_request(request, cls=UpdateManifestRequest)
+ _, path, backend = _sandbox_source(request, body.file_key, mutation=True)
+ if path is None or backend is None:
+ raise HTTPException(400, "No notebook manifest is available to edit.")
+ try:
+ manifest = await asyncio.to_thread(
+ script_metadata.write_manifest,
+ path,
+ body.contents,
+ previous=body.previous,
+ )
+ except script_metadata.ManifestConflictError as error:
+ raise HTTPException(409, str(error)) from error
+ except (OSError, ValueError, EnvironmentManagerError) as error:
+ raise HTTPException(400, str(error)) from error
+ return SandboxResponse(backend=backend, manifest=manifest, filename=path)
+
+
+@requires("edit")
+async def sync_sandbox(request: Request) -> SyncSandboxResponse:
+ """
+ parameters:
+ - in: header
+ name: Marimo-Session-Id
+ schema:
+ type: string
+ required: true
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/SandboxRequest"
+ responses:
+ 200:
+ description: Apply the saved manifest, or reconnect to retry startup
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/SyncSandboxResponse"
+ """
+ body = await parse_request(request, cls=SandboxRequest)
+ sandbox, _, backend = _sandbox_source(
+ request, body.file_key, mutation=True
+ )
+ if backend is None:
+ raise HTTPException(400, "This notebook does not use a sandbox.")
+ if sandbox is None:
+ # Connection creation owns provisioning and streams its progress.
+ return SyncSandboxResponse(success=True, reconnect=True)
+ try:
+ await sandbox.sync_async()
+ except SandboxRestartRequired as error:
+ return SyncSandboxResponse(
+ success=False, error=str(error), restart_required=True
+ )
+ except (EnvironmentManagerError, OSError) as error:
+ return SyncSandboxResponse(success=False, error=str(error))
+ return SyncSandboxResponse(success=True)
diff --git a/marimo/_server/api/endpoints/ws/session_handler.py b/marimo/_server/api/endpoints/ws/session_handler.py
index 400645b4c8..5989001c81 100644
--- a/marimo/_server/api/endpoints/ws/session_handler.py
+++ b/marimo/_server/api/endpoints/ws/session_handler.py
@@ -5,6 +5,7 @@ from __future__ import annotations
import abc
import asyncio
+from contextlib import asynccontextmanager
from typing import TYPE_CHECKING
from marimo import _loggers
@@ -15,12 +16,19 @@ from marimo._messaging.notification import (
BannerNotification,
NotificationMessage,
ReconnectedNotification,
+ StartupProgressNotification,
+)
+from marimo._messaging.serde import (
+ deserialize_kernel_notification_name,
+ serialize_kernel_message,
)
-from marimo._messaging.serde import serialize_kernel_message
from marimo._server.api.endpoints.ws.ws_kernel_ready import (
build_kernel_ready,
is_rtc_available,
)
+from marimo._server.api.endpoints.ws.ws_message_loop import (
+ prepare_wire_message,
+)
from marimo._server.api.endpoints.ws.ws_session_connector import (
SessionConnector,
is_viewer_connection,
@@ -29,10 +37,10 @@ from marimo._server.codes import WebSocketCloseReason, WebSocketCodes
from marimo._session.consumer import SessionConsumer
from marimo._session.model import ConnectionState, SessionMode
from marimo._types.ids import ConsumerId
+from marimo._utils.asyncio_utils import cancel_and_wait
if TYPE_CHECKING:
- from collections.abc import Callable
- from typing import Any
+ from collections.abc import AsyncGenerator, AsyncIterator
from starlette.requests import HTTPConnection
@@ -77,11 +85,16 @@ class SessionHandler(SessionConsumer, abc.ABC):
self.params = params
self.mode = mode
self.doc_manager = doc_manager
- self.status: ConnectionState
+ self.status = ConnectionState.CONNECTING
+ self._session: Session | None = None
self.cancel_close_handle: asyncio.TimerHandle | None = None
# Messages from the kernel are put in this queue
# to be sent to the frontend
self.message_queue: asyncio.Queue[KernelMessage] = asyncio.Queue()
+ # Startup precedes session attachment and its viewer filtering.
+ self._startup_queue: asyncio.Queue[KernelMessage | None] | None = (
+ asyncio.Queue()
+ )
self._consumer_id = ConsumerId(params.session_id)
@property
@@ -107,7 +120,21 @@ class SessionHandler(SessionConsumer, abc.ABC):
# Shared session lifecycle
- def _connect_session(
+ @asynccontextmanager
+ async def _connection_lifetime(
+ self, connection: HTTPConnection
+ ) -> AsyncIterator[asyncio.Task[tuple[Session, ConnectionType]]]:
+ """Own attachment through startup, progress delivery, and streaming."""
+ startup = asyncio.create_task(self._connect_session(connection))
+ try:
+ yield startup
+ finally:
+ try:
+ await cancel_and_wait(startup)
+ finally:
+ self._on_disconnect()
+
+ async def _connect_session(
self, connection: HTTPConnection
) -> tuple[Session, ConnectionType]:
"""Connect this handler to a session (new, resume, reconnect, ...).
@@ -117,12 +144,53 @@ class SessionHandler(SessionConsumer, abc.ABC):
WebSocketDisconnect: If the connection is rejected; carries the
close code and reason.
"""
- return SessionConnector(
- manager=self.manager,
- handler=self,
- params=self.params,
- connection=connection,
- ).connect()
+ startup = asyncio.create_task(
+ SessionConnector(
+ manager=self.manager,
+ handler=self,
+ params=self.params,
+ connection=connection,
+ ).connect()
+ )
+ disconnected = asyncio.create_task(self._wait_for_disconnect())
+ try:
+ done, _ = await asyncio.wait(
+ (startup, disconnected), return_when=asyncio.FIRST_COMPLETED
+ )
+ if disconnected in done:
+ await disconnected
+ await cancel_and_wait(startup)
+ raise asyncio.CancelledError
+ return await startup
+ finally:
+ await cancel_and_wait(disconnected)
+ await cancel_and_wait(startup)
+
+ @abc.abstractmethod
+ async def _wait_for_disconnect(self) -> None:
+ """Notice a closed transport even while a session is starting."""
+
+ async def _startup_messages(
+ self, startup: asyncio.Task[tuple[Session, ConnectionType]]
+ ) -> AsyncGenerator[str, None]:
+ """Send progress before session messages, including before failure."""
+ queue = self._startup_queue
+ assert queue is not None
+
+ def finished(
+ _task: asyncio.Task[tuple[Session, ConnectionType]],
+ ) -> None:
+ queue.put_nowait(None)
+
+ startup.add_done_callback(finished)
+ try:
+ while (data := await queue.get()) is not None:
+ text = prepare_wire_message(data, is_kiosk=self.params.kiosk)
+ if text is not None:
+ yield text
+ finally:
+ startup.remove_done_callback(finished)
+ self._startup_queue = None
def _is_viewer(
self, session: Session, connection_type: ConnectionType
@@ -134,7 +202,14 @@ class SessionHandler(SessionConsumer, abc.ABC):
)
def notify(self, notification: KernelMessage) -> None:
- self.message_queue.put_nowait(notification)
+ if (
+ self._startup_queue is not None
+ and deserialize_kernel_notification_name(notification)
+ == StartupProgressNotification.name
+ ):
+ self._startup_queue.put_nowait(notification)
+ else:
+ self.message_queue.put_nowait(notification)
def _serialize_and_notify(self, notification: NotificationMessage) -> None:
self.notify(serialize_kernel_message(notification))
@@ -281,24 +356,19 @@ class SessionHandler(SessionConsumer, abc.ABC):
LOGGER.debug("Replaying notification %s", notif)
self._serialize_and_notify(notif)
- def _on_disconnect(
- self,
- e: Exception,
- cleanup_fn: Callable[[], Any],
- ) -> None:
+ def _on_disconnect(self) -> None:
+ session = self._session
+ if session is None:
+ return
LOGGER.debug(
- "Connection closed for session %s with exception %s, type %s",
+ "Connection closed for session %s",
self.params.session_id,
- str(e),
- type(e),
)
# Change the status
self.status = ConnectionState.CLOSED
# Disconnect the consumer
- session = self.manager.get_session(self.params.session_id)
- if session:
- session.disconnect_consumer(self)
+ session.disconnect_consumer(self)
# When the connection is closed, we wait session.ttl_seconds before
# closing the session. This prevents the session from being closed
@@ -330,27 +400,18 @@ class SessionHandler(SessionConsumer, abc.ABC):
"Closing session %s (TTL EXPIRED)",
self.params.session_id,
)
- # wait until TTL is expired before calling the cleanup
- # function
- cleanup_fn()
self.manager.close_session(self.params.session_id)
- if session is not None:
- cancellation_handle = asyncio.get_running_loop().call_later(
- session.ttl_seconds, _close
- )
- self.cancel_close_handle = cancellation_handle
- else:
- _close()
- else:
- cleanup_fn()
+ self.cancel_close_handle = asyncio.get_running_loop().call_later(
+ session.ttl_seconds, _close
+ )
def on_attach(self, session: Session, event_bus: SessionEventBus) -> None:
- del session
del event_bus
- return
+ self._session = session
def on_detach(self) -> None:
+ self._session = None
# If the transport is open, send a close message
is_connected = (
self.status == ConnectionState.OPEN
diff --git a/marimo/_server/api/endpoints/ws/sse_handler.py b/marimo/_server/api/endpoints/ws/sse_handler.py
index eb4e923ccb..3aa2c8c3a0 100644
--- a/marimo/_server/api/endpoints/ws/sse_handler.py
+++ b/marimo/_server/api/endpoints/ws/sse_handler.py
@@ -23,6 +23,7 @@ from __future__ import annotations
import asyncio
import enum
+from contextlib import aclosing
from typing import TYPE_CHECKING, Union, cast
from starlette.websockets import WebSocketDisconnect
@@ -126,66 +127,76 @@ class SSESessionHandler(SessionHandler):
(shutdown, takeover); ends without one on client disconnect.
"""
try:
- session, connection_type = self._connect_session(self.request)
- except KernelStartupError as e:
- LOGGER.error("Kernel startup failed: %s", e)
- yield format_sse_event(
- serialize_notification_for_wire(
- KernelStartupErrorNotification(error=str(e))
- )
- )
- yield format_close_event(
- WebSocketCodes.UNEXPECTED_ERROR,
- WebSocketCloseReason.KERNEL_STARTUP_ERROR,
- )
- return
- except WebSocketDisconnect as e:
- # SessionConnector signals connection rejections (e.g. kiosk
- # not allowed) with WebSocketDisconnect regardless of
- # transport.
- yield format_close_event(e.code, e.reason or "")
- return
-
- LOGGER.debug(
- "Connected to session %s with type %s",
- session.initialization_id,
- connection_type,
- )
-
- disconnect_task = asyncio.create_task(self._signal_on_disconnect())
- heartbeat_task = asyncio.create_task(self._heartbeat_loop())
- self._check_status_update()
- try:
- while True:
- item = await self._queue.get()
- if item is _Signal.DISCONNECT:
+ async with self._connection_lifetime(self.request) as startup:
+ try:
+ async with aclosing(
+ self._startup_messages(startup)
+ ) as messages:
+ async for progress in messages:
+ yield format_sse_event(progress)
+ session, connection_type = await startup
+ except asyncio.CancelledError:
return
- if item is _Signal.CLOSE:
- if self._close_code is not None:
- yield format_close_event(
- self._close_code, self._close_reason or ""
+ except KernelStartupError as e:
+ LOGGER.error("Kernel startup failed: %s", e)
+ yield format_sse_event(
+ serialize_notification_for_wire(
+ KernelStartupErrorNotification(error=str(e))
)
+ )
+ yield format_close_event(
+ WebSocketCodes.UNEXPECTED_ERROR,
+ WebSocketCloseReason.KERNEL_STARTUP_ERROR,
+ )
return
- if item is _Signal.HEARTBEAT:
- yield HEARTBEAT_EVENT
- continue
- text = prepare_wire_message(
- item,
- is_kiosk=self._is_viewer(session, connection_type),
+ except WebSocketDisconnect as e:
+ # SessionConnector signals connection rejections (e.g. kiosk
+ # not allowed) with WebSocketDisconnect regardless of
+ # transport.
+ yield format_close_event(e.code, e.reason or "")
+ return
+
+ LOGGER.debug(
+ "Connected to session %s with type %s",
+ session.initialization_id,
+ connection_type,
)
- if text is not None:
- yield format_sse_event(text)
+
+ disconnect_task = asyncio.create_task(
+ self._signal_on_disconnect()
+ )
+ heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+ self._check_status_update()
+ try:
+ while True:
+ item = await self._queue.get()
+ if item is _Signal.DISCONNECT:
+ return
+ if item is _Signal.CLOSE:
+ if self._close_code is not None:
+ yield format_close_event(
+ self._close_code, self._close_reason or ""
+ )
+ return
+ if item is _Signal.HEARTBEAT:
+ yield HEARTBEAT_EVENT
+ continue
+ text = prepare_wire_message(
+ item,
+ is_kiosk=self._is_viewer(session, connection_type),
+ )
+ if text is not None:
+ yield format_sse_event(text)
+ finally:
+ # Also runs when the client disconnects and StreamingResponse
+ # cancels the generator; don't await anything cancellable here.
+ disconnect_task.cancel()
+ heartbeat_task.cancel()
finally:
- # Also runs when the client disconnects and StreamingResponse
- # cancels the generator; don't await anything cancellable here.
self._stream_finished = True
- disconnect_task.cancel()
- heartbeat_task.cancel()
- if not self._close_requested:
- self._on_disconnect(
- ConnectionError("SSE client disconnected"),
- lambda: None,
- )
+
+ async def _wait_for_disconnect(self) -> None:
+ await wait_for_http_disconnect(self.request)
async def _signal_on_disconnect(self) -> None:
"""Signal the stream loop when the client disconnects.
@@ -195,7 +206,7 @@ class SSESessionHandler(SessionHandler):
to the disconnect first, the generator is cancelled and its
`finally` performs the same teardown.
"""
- await wait_for_http_disconnect(self.request)
+ await self._wait_for_disconnect()
self._queue.put_nowait(_Signal.DISCONNECT)
async def _heartbeat_loop(self) -> None:
diff --git a/marimo/_server/api/endpoints/ws/ws_message_loop.py b/marimo/_server/api/endpoints/ws/ws_message_loop.py
index 77cc266253..e03d8b2d7b 100644
--- a/marimo/_server/api/endpoints/ws/ws_message_loop.py
+++ b/marimo/_server/api/endpoints/ws/ws_message_loop.py
@@ -2,7 +2,7 @@
from __future__ import annotations
import asyncio
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
from starlette.websockets import WebSocketDisconnect, WebSocketState
@@ -90,16 +90,12 @@ class WebSocketMessageLoop:
websocket: WebSocket,
message_queue: asyncio.Queue[KernelMessage],
is_kiosk: Callable[[], bool],
- on_disconnect: Callable[[Exception, Callable[[], Any]], None],
on_check_status_update: Callable[[], None],
):
self.websocket = websocket
self.message_queue = message_queue
self.is_kiosk = is_kiosk
- self.on_disconnect = on_disconnect
self.on_check_status_update = on_check_status_update
- self._listen_messages_task: asyncio.Task[None] | None = None
- self._listen_disconnect_task: asyncio.Task[None] | None = None
async def start(self) -> None:
"""Start the message loops.
@@ -108,17 +104,22 @@ class WebSocketMessageLoop:
- listen_for_messages: Sends messages from kernel to frontend
- listen_for_disconnect: Detects when WebSocket disconnects
"""
- self._listen_messages_task = asyncio.create_task(
- self._listen_for_messages()
- )
- self._listen_disconnect_task = asyncio.create_task(
- self._listen_for_disconnect()
- )
-
- await asyncio.gather(
- self._listen_messages_task,
- self._listen_disconnect_task,
+ tasks = (
+ asyncio.create_task(self._listen_for_messages()),
+ asyncio.create_task(self._listen_for_disconnect()),
)
+ try:
+ done, _ = await asyncio.wait(
+ tasks, return_when=asyncio.FIRST_COMPLETED
+ )
+ for task in done:
+ task.result()
+ except WebSocketDisconnect:
+ pass
+ finally:
+ for task in tasks:
+ task.cancel()
+ await asyncio.gather(*tasks, return_exceptions=True)
async def _listen_for_messages(self) -> None:
"""Listen for messages from kernel and send to frontend."""
@@ -131,9 +132,7 @@ class WebSocketMessageLoop:
# Send to WebSocket
try:
await self.websocket.send_text(text)
- except WebSocketDisconnect as e:
- self.on_disconnect(e, self._cancel_disconnect_task)
- except RuntimeError as e:
+ except RuntimeError:
# Starlette can raise a runtime error if a message is sent
# when the socket is closed. In case the disconnection
# error hasn't made its way to listen_for_disconnect, do
@@ -142,40 +141,11 @@ class WebSocketMessageLoop:
self.websocket.application_state
== WebSocketState.DISCONNECTED
):
- self.on_disconnect(e, self._cancel_disconnect_task)
- else:
- LOGGER.error(
- "Error sending message to frontend: %s", str(e)
- )
- except Exception as e:
- LOGGER.error("Error sending message to frontend: %s", str(e))
+ return
raise
async def _listen_for_disconnect(self) -> None:
"""Listen for WebSocket disconnect."""
- try:
- # Check for marimo updates when connection starts
- self.on_check_status_update()
- # Wait for disconnection
+ self.on_check_status_update()
+ while True:
await self.websocket.receive_text()
- except WebSocketDisconnect as e:
- self.on_disconnect(e, self._cancel_messages_task)
- except Exception as e:
- LOGGER.error("Error listening for disconnect: %s", str(e))
- raise
-
- def _cancel_messages_task(self) -> None:
- """Cancel the messages task."""
- if (
- self._listen_messages_task
- and not self._listen_messages_task.done()
- ):
- self._listen_messages_task.cancel()
-
- def _cancel_disconnect_task(self) -> None:
- """Cancel the disconnect task."""
- if (
- self._listen_disconnect_task
- and not self._listen_disconnect_task.done()
- ):
- self._listen_disconnect_task.cancel()
diff --git a/marimo/_server/api/endpoints/ws/ws_session_connector.py b/marimo/_server/api/endpoints/ws/ws_session_connector.py
index b88555b051..1774a4252c 100644
--- a/marimo/_server/api/endpoints/ws/ws_session_connector.py
+++ b/marimo/_server/api/endpoints/ws/ws_session_connector.py
@@ -68,7 +68,7 @@ class SessionConnector:
self.params = params
self.connection = connection
- def connect(self) -> tuple[Session, ConnectionType]:
+ async def connect(self) -> tuple[Session, ConnectionType]:
"""Determine connection type and establish session connection.
Returns:
@@ -78,6 +78,12 @@ class SessionConnector:
Raises:
WebSocketDisconnect: If the connection cannot be established.
"""
+ async with self.manager.connection_lock(
+ self.params.session_id, self.params.file_key
+ ):
+ return await self._connect()
+
+ async def _connect(self) -> tuple[Session, ConnectionType]:
# 1. Kiosk mode
if self.params.kiosk:
return self._connect_kiosk()
@@ -118,7 +124,7 @@ class SessionConnector:
return self._resume_session(resumable)
# 5. Create new session
- return self._create_new_session()
+ return await self._create_new_session()
def _connect_kiosk(self) -> tuple[Session, ConnectionType]:
"""Connect to kiosk session.
@@ -196,7 +202,7 @@ class SessionConnector:
"""Check if we're in run mode (read-only app mode)."""
return self.manager.mode == SessionMode.RUN
- def _create_new_session(self) -> tuple[Session, ConnectionType]:
+ async def _create_new_session(self) -> tuple[Session, ConnectionType]:
"""Create a new session.
Grabs query params from the connection and creates a new session
@@ -208,7 +214,7 @@ class SessionConnector:
# session was created.
query_params = self._extract_query_params()
- new_session = self.manager.create_session(
+ new_session = await self.manager.create_session(
query_params=query_params.to_dict(),
session_id=self.params.session_id,
session_consumer=self.handler,
diff --git a/marimo/_server/api/endpoints/ws_endpoint.py b/marimo/_server/api/endpoints/ws_endpoint.py
index e1b091a65f..85b9750c5a 100644
--- a/marimo/_server/api/endpoints/ws_endpoint.py
+++ b/marimo/_server/api/endpoints/ws_endpoint.py
@@ -3,10 +3,11 @@ from __future__ import annotations
import asyncio
import sys
+from contextlib import aclosing
from typing import TYPE_CHECKING
from starlette.responses import StreamingResponse
-from starlette.websockets import WebSocket, WebSocketState
+from starlette.websockets import WebSocket, WebSocketDisconnect, WebSocketState
from marimo import _loggers
from marimo._dependencies.dependencies import DependencyManager
@@ -245,32 +246,49 @@ class WebSocketHandler(SessionHandler):
)
LOGGER.debug("Existing sessions: %s", self.manager.sessions)
- try:
- session, connection_type = self._connect_session(self.websocket)
- except KernelStartupError as e:
- LOGGER.error("Kernel startup failed: %s", e)
- await self._close_kernel_startup_error(str(e))
- return
- LOGGER.debug(
- "Connected to session %s with type %s",
- session.initialization_id,
- connection_type,
- )
+ async with self._connection_lifetime(self.websocket) as startup:
+ try:
+ async with aclosing(
+ self._startup_messages(startup)
+ ) as messages:
+ async for text in messages:
+ await self.websocket.send_text(text)
+ session, connection_type = await startup
+ except asyncio.CancelledError:
+ await self._safe_close(WebSocketCodes.NORMAL_CLOSE, "")
+ return
+ except KernelStartupError as e:
+ LOGGER.error("Kernel startup failed: %s", e)
+ await self._close_kernel_startup_error(str(e))
+ return
+ except WebSocketDisconnect as e:
+ await self._safe_close(e.code, e.reason or "")
+ return
+ LOGGER.debug(
+ "Connected to session %s with type %s",
+ session.initialization_id,
+ connection_type,
+ )
- # Start message loops
- message_loop = WebSocketMessageLoop(
- websocket=self.websocket,
- message_queue=self.message_queue,
- is_kiosk=lambda: self._is_viewer(session, connection_type),
- on_disconnect=self._on_disconnect,
- on_check_status_update=self._check_status_update,
- )
+ # Start message loops
+ message_loop = WebSocketMessageLoop(
+ websocket=self.websocket,
+ message_queue=self.message_queue,
+ is_kiosk=lambda: self._is_viewer(session, connection_type),
+ on_check_status_update=self._check_status_update,
+ )
- try:
- self.ws_future = asyncio.create_task(message_loop.start())
- await self.ws_future
- except asyncio.CancelledError:
- LOGGER.debug("Websocket terminated with CancelledError")
+ try:
+ self.ws_future = asyncio.create_task(message_loop.start())
+ await self.ws_future
+ except asyncio.CancelledError:
+ LOGGER.debug("Websocket terminated with CancelledError")
+
+ async def _wait_for_disconnect(self) -> None:
+ while True:
+ message = await self.websocket.receive()
+ if message["type"] == "websocket.disconnect":
+ return
async def _safe_close(self, code: int, reason: str) -> None:
"""Close the WebSocket, ignoring errors from uninitialized state.
@@ -282,6 +300,8 @@ class WebSocketHandler(SessionHandler):
"""
try:
await self.websocket.close(code, reason)
+ except WebSocketDisconnect:
+ pass
except AttributeError as e:
if "transfer_data_task" not in str(e):
raise
diff --git a/marimo/_server/api/lifespans.py b/marimo/_server/api/lifespans.py
index 5468a8c83d..f118aae05e 100644
--- a/marimo/_server/api/lifespans.py
+++ b/marimo/_server/api/lifespans.py
@@ -214,16 +214,24 @@ async def signal_handler(app: Starlette) -> AsyncIterator[None]:
manager = state.session_manager
# Interrupt handler
- def shutdown() -> None:
- manager.shutdown()
+ async def shutdown() -> None:
+ await manager.shutdown()
if state.server:
close_uvicorn(state.server)
+ def request_shutdown() -> None:
+ supervised_task(
+ shutdown(), name="server.shutdown", registry=background_tasks
+ )
+
InterruptHandler(
quiet=state.quiet,
- shutdown=shutdown,
+ shutdown=request_shutdown,
).register()
- yield
+ try:
+ yield
+ finally:
+ await manager.shutdown()
@contextlib.asynccontextmanager
diff --git a/marimo/_server/api/middleware.py b/marimo/_server/api/middleware.py
index 1788c82321..26f38566fb 100644
--- a/marimo/_server/api/middleware.py
+++ b/marimo/_server/api/middleware.py
@@ -719,15 +719,15 @@ class TimeoutMiddleware(BaseHTTPMiddleware):
now = time.time()
if now >= timeout_at:
print_tabbed("Timeout due to inactivity")
- self.shutdown()
+ await self.shutdown()
break
# Sleep until 1s after the next potential activity timeout
await asyncio.sleep(timeout_at - now + 1)
- def shutdown(self) -> None:
+ async def shutdown(self) -> None:
manager = self.app_state.session_manager
- manager.shutdown()
+ await manager.shutdown()
if self.app_state.server:
close_uvicorn(self.app_state.server)
diff --git a/marimo/_server/models/packages.py b/marimo/_server/models/packages.py
index e95c853144..453005f74a 100644
--- a/marimo/_server/models/packages.py
+++ b/marimo/_server/models/packages.py
@@ -33,6 +33,22 @@ class RemovePackageRequest(msgspec.Struct, rename="camel"):
group: str | None = None
+class SandboxRequest(msgspec.Struct, rename="camel"):
+ file_key: str | None = None
+
+
+class UpdateManifestRequest(msgspec.Struct, rename="camel"):
+ contents: str
+ previous: str
+ file_key: str | None = None
+
+
+class SandboxResponse(msgspec.Struct, rename="camel"):
+ backend: Literal["uv", "pixi"] | None
+ manifest: str | None
+ filename: str | None
+
+
class SandboxPackageContext(
msgspec.Struct,
frozen=True,
@@ -77,3 +93,7 @@ class PackageOperationResponse(msgspec.Struct, rename="camel"):
@staticmethod
def of_failure(error: str) -> PackageOperationResponse:
return PackageOperationResponse(success=False, error=error)
+
+
+class SyncSandboxResponse(PackageOperationResponse, rename="camel"):
+ reconnect: bool = False
diff --git a/marimo/_server/session_manager.py b/marimo/_server/session_manager.py
index 70cb80b66c..c89d09e7f1 100644
--- a/marimo/_server/session_manager.py
+++ b/marimo/_server/session_manager.py
@@ -8,11 +8,13 @@ file watching, and LSP server management.
from __future__ import annotations
+import asyncio
+from dataclasses import dataclass
from pathlib import Path
from typing import TYPE_CHECKING
+from weakref import WeakValueDictionary
from marimo import _loggers
-from marimo._cli.sandbox import SandboxMode
from marimo._config.manager import MarimoConfigManager
from marimo._runtime.commands import (
SerializedCLIArgs,
@@ -42,6 +44,7 @@ from marimo._session.file_change_handler import (
from marimo._session.file_watcher_integration import (
SessionFileWatcherExtension,
)
+from marimo._session.managers.ipc import KernelStartupError
from marimo._session.model import ConnectionState, SessionMode
from marimo._session.session import Session, SessionImpl
from marimo._session.session_repository import SessionRepository
@@ -58,6 +61,12 @@ if TYPE_CHECKING:
LOGGER = _loggers.marimo_logger()
+@dataclass
+class _PendingSession:
+ task: asyncio.Task[Session]
+ waiters: int = 0
+
+
class SessionManager:
"""Orchestrates session management
@@ -83,7 +92,7 @@ class SessionManager:
redirect_console_to_browser: bool,
ttl_seconds: int | None,
watch: bool = False,
- sandbox_mode: SandboxMode | None = None,
+ sandbox: bool = False,
isolate_apps: bool = False,
execute_opengraph_generators: bool = False,
) -> None:
@@ -98,7 +107,7 @@ class SessionManager:
self.argv = argv
self.redirect_console_to_browser = redirect_console_to_browser
self._config_manager = config_manager
- self.sandbox_mode = sandbox_mode
+ self.sandbox = sandbox
self.execute_opengraph_generators = execute_opengraph_generators
# When running multiple apps, each app runs in an isolated host
@@ -107,10 +116,15 @@ class SessionManager:
self._app_host_pool: AppHostPool | None = None
if isolate_apps and mode == SessionMode.RUN:
self._app_host_pool = AppHostPool(
- sandbox=sandbox_mode is SandboxMode.MULTI,
+ sandbox=sandbox,
)
self._repository = SessionRepository()
+ self._pending: dict[SessionId, _PendingSession] = {}
+ self._connection_locks: WeakValueDictionary[str, asyncio.Lock] = (
+ WeakValueDictionary()
+ )
+ self._closed = False
def _get_code() -> str:
defaults = AppDefaults.from_config_manager(config_manager)
@@ -170,7 +184,24 @@ class SessionManager:
self.workspace.register_allowed_path(key)
return self.workspace.load(key, defaults)
- def create_session(
+ def connection_lock(
+ self, session_id: SessionId, file_key: MarimoFileKey
+ ) -> asyncio.Lock:
+ """Serialize reconnect decisions while a notebook is starting."""
+ if self._closed:
+ raise KernelStartupError("Session manager is shut down")
+ key = (
+ self._resolve_file_key(file_key) or file_key
+ if self.mode == SessionMode.EDIT
+ else session_id
+ )
+ lock = self._connection_locks.get(key)
+ if lock is None:
+ lock = asyncio.Lock()
+ self._connection_locks[key] = lock
+ return lock
+
+ async def create_session(
self,
session_id: SessionId,
session_consumer: SessionConsumer,
@@ -178,13 +209,58 @@ class SessionManager:
file_key: MarimoFileKey,
auto_instantiate: bool,
) -> Session:
- """Create a new session."""
- LOGGER.debug("Creating new session for id %s", session_id)
-
- # Check if session already exists
+ """Return a ready session, retaining ownership during startup."""
+ if self._closed:
+ raise KernelStartupError("Session manager is shut down")
existing = self._repository.get_sync(session_id)
- if existing:
+ if existing is not None:
return existing
+ pending = self._pending.get(session_id)
+ if pending is None:
+ task = asyncio.create_task(
+ self._create_session(
+ session_id,
+ session_consumer,
+ query_params,
+ file_key,
+ auto_instantiate,
+ ),
+ name=f"session.start.{session_id}",
+ )
+ pending = _PendingSession(task)
+ self._pending[session_id] = pending
+
+ def finished(task: asyncio.Task[Session]) -> None:
+ self._pending.pop(session_id, None)
+ # A disconnected caller may no longer be awaiting the error.
+ if not task.cancelled():
+ task.exception()
+
+ task.add_done_callback(finished)
+ pending.waiters += 1
+ try:
+ return await asyncio.shield(pending.task)
+ finally:
+ pending.waiters -= 1
+ if pending.waiters == 0 and not pending.task.done():
+ # The last disconnected caller releases its connection lock
+ # only after the abandoned launch has cleaned up.
+ pending.task.cancel()
+ await asyncio.gather(pending.task, return_exceptions=True)
+
+ def is_session_starting(self, session_id: SessionId) -> bool:
+ return session_id in self._pending
+
+ async def _create_session(
+ self,
+ session_id: SessionId,
+ session_consumer: SessionConsumer,
+ query_params: SerializedQueryParams,
+ file_key: MarimoFileKey,
+ auto_instantiate: bool,
+ ) -> Session:
+ """Create a new session."""
+ LOGGER.debug("Creating new session for id %s", session_id)
# Get app file manager
defaults = AppDefaults.from_config_manager(self._config_manager)
@@ -205,7 +281,7 @@ class SessionManager:
)
)
- session = SessionImpl.create(
+ session = await SessionImpl.create(
initialization_id=file_key,
session_consumer=session_consumer,
mode=self.mode,
@@ -233,7 +309,7 @@ class SessionManager:
ttl_seconds=self.ttl_seconds,
auto_instantiate=auto_instantiate,
extensions=extensions,
- sandbox_mode=self.sandbox_mode,
+ sandbox=self.sandbox,
app_host_context=AppHostContext(
pool=self._app_host_pool, session_id=session_id
)
@@ -435,9 +511,14 @@ class SessionManager:
self.close_session(session_id)
LOGGER.debug("Closed all sessions.")
- def shutdown(self) -> None:
+ async def shutdown(self) -> None:
"""Shutdown the session manager and stop all file watchers."""
LOGGER.debug("Shutting down")
+ self._closed = True
+ pending = [entry.task for entry in self._pending.values()]
+ for task in pending:
+ task.cancel()
+ await asyncio.gather(*pending, return_exceptions=True)
self.close_all_sessions()
if self._app_host_pool is not None:
self._app_host_pool.shutdown()
diff --git a/marimo/_server/start.py b/marimo/_server/start.py
index 5cca29565b..4e49ad0270 100644
--- a/marimo/_server/start.py
+++ b/marimo/_server/start.py
@@ -10,10 +10,10 @@ from urllib.parse import urlparse
import uvicorn
from marimo._cli.print import echo
-from marimo._cli.sandbox import SandboxMode
from marimo._config.config import PartialMarimoConfig
from marimo._config.manager import get_default_config_manager
from marimo._config.settings import GLOBAL_SETTINGS
+from marimo._environments.sandbox import Backend
from marimo._mcp.setup import McpType, setup_mcp_server
from marimo._messaging.notification import StartupLogsNotification
from marimo._runtime.commands import SerializedCLIArgs
@@ -211,7 +211,7 @@ def start(
server_startup_command: str | None = None,
asset_url: str | None = None,
timeout: float | None = None,
- sandbox_mode: SandboxMode | None = None,
+ sandbox: Backend | None = None,
startup_tip: CliTip | None = None,
show_tracebacks: bool | None = None,
execute_opengraph_generators: bool = False,
@@ -221,8 +221,8 @@ def start(
"""
import packaging.version
- # In single-file sandbox mode, uv becomes our direct parent. So we
- # watch the outer CLI's PID, terminating if the CLI terminates.
+ # Sandboxed run commands put a launcher between the CLI and server.
+ # Watch the outer CLI's PID, terminating if the CLI terminates.
ancestor_pid_env = os.environ.get("MARIMO_ANCESTOR_PID")
if ancestor_pid_env:
try:
@@ -282,6 +282,15 @@ def start(
"trusted directories and authentication controls."
)
+ if sandbox is not None:
+ os.environ["MARIMO_SANDBOX_BACKEND"] = sandbox
+ GLOBAL_SETTINGS.SANDBOX_BACKEND = sandbox
+ if mode == SessionMode.EDIT:
+ os.environ["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"
+ GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA = True
+ os.environ["MARIMO_SANDBOX_MODE"] = "multi"
+ GLOBAL_SETTINGS.SANDBOX_MODE = "multi"
+
if GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA:
config_reader = config_reader.with_overrides(
{
@@ -321,7 +330,7 @@ def start(
auth_token=auth_token,
redirect_console_to_browser=redirect_console_to_browser,
watch=watch,
- sandbox_mode=sandbox_mode,
+ sandbox=sandbox is not None,
isolate_apps=isolate_apps,
execute_opengraph_generators=execute_opengraph_generators,
)
diff --git a/marimo/_session/_venv.py b/marimo/_session/_venv.py
index 01c8076490..56e3413a0d 100644
--- a/marimo/_session/_venv.py
+++ b/marimo/_session/_venv.py
@@ -12,14 +12,14 @@ in marimo's sandbox mode. It handles:
from __future__ import annotations
import os
-import subprocess
import sys
from pathlib import Path
from typing import TYPE_CHECKING
from marimo import _loggers
from marimo._cli.print import echo
-from marimo._environments.uv import UvCommandError, uv
+from marimo._environments.process import run_command
+from marimo._environments.uv import UvCommandError, uv_async
from marimo._version import __version__
if TYPE_CHECKING:
@@ -123,7 +123,7 @@ def get_kernel_pythonpath() -> str:
return os.pathsep.join(paths)
-def has_marimo_installed(venv_python: str) -> bool:
+async def has_marimo_installed(venv_python: str) -> bool:
"""Check if marimo and its IPC deps are installed in the venv.
Args:
@@ -132,14 +132,12 @@ def has_marimo_installed(venv_python: str) -> bool:
Returns:
True if marimo, msgspec, and zmq can all be imported.
"""
- result = subprocess.run(
+ result = await run_command(
[
venv_python,
"-c",
"import marimo, msgspec, zmq; print(marimo.__version__)",
],
- capture_output=True,
- text=True,
)
if result.returncode != 0:
return False
@@ -157,7 +155,7 @@ def has_marimo_installed(venv_python: str) -> bool:
return True
-def check_python_version_compatibility(venv_python: str) -> bool:
+async def check_python_version_compatibility(venv_python: str) -> bool:
"""Check if venv Python version matches current Python.
Binary dependencies (pyzmq, msgspec) aren't cross-version compatible,
@@ -169,14 +167,12 @@ def check_python_version_compatibility(venv_python: str) -> bool:
Returns:
True if versions match, False otherwise.
"""
- result = subprocess.run(
+ result = await run_command(
[
venv_python,
"-c",
"import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')",
],
- capture_output=True,
- text=True,
)
venv_version = result.stdout.strip()
current_version = f"{sys.version_info.major}.{sys.version_info.minor}"
@@ -184,7 +180,7 @@ def check_python_version_compatibility(venv_python: str) -> bool:
return venv_version == current_version
-def install_marimo_into_venv(venv_python: str) -> None:
+async def install_marimo_into_venv(venv_python: str) -> None:
"""Install marimo into a venv.
Args:
@@ -195,7 +191,7 @@ def install_marimo_into_venv(venv_python: str) -> None:
echo("Installing marimo into configured venv...", err=True)
try:
- uv(["pip", "install", "--python", venv_python] + packages)
+ await uv_async(["pip", "install", "--python", venv_python] + packages)
except UvCommandError as e:
LOGGER.warning(
f"Failed to install marimo into configured venv: {e.stderr}"
diff --git a/marimo/_session/consumer.py b/marimo/_session/consumer.py
index 02d103059a..6f5209d43a 100644
--- a/marimo/_session/consumer.py
+++ b/marimo/_session/consumer.py
@@ -25,7 +25,9 @@ class SessionConsumer(ABC, SessionExtension):
def consumer_id(self) -> ConsumerId: ...
@abstractmethod
- def notify(self, notification: KernelMessage) -> None: ...
+ def notify(self, notification: KernelMessage) -> None:
+ """Enqueue a notification, including startup progress before attach."""
+ ...
@abstractmethod
def connection_state(self) -> ConnectionState: ...
diff --git a/marimo/_session/managers/app_host.py b/marimo/_session/managers/app_host.py
index 84a1b21280..2a4f89b8cb 100644
--- a/marimo/_session/managers/app_host.py
+++ b/marimo/_session/managers/app_host.py
@@ -175,7 +175,7 @@ class AppHostKernelManager(KernelManager):
self.kernel_task: ProcessLike | threading.Thread | None = None
- def start_kernel(self) -> None:
+ async def start_kernel(self) -> None:
response = self._app_host.create_kernel(
session_id=self._session_id,
configs=self._configs,
diff --git a/marimo/_session/managers/ipc.py b/marimo/_session/managers/ipc.py
index 09688c150a..f970edfef2 100644
--- a/marimo/_session/managers/ipc.py
+++ b/marimo/_session/managers/ipc.py
@@ -7,24 +7,21 @@ via ZeroMQ channels. Each notebook gets its own sandboxed virtual environment.
from __future__ import annotations
+import asyncio
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 SandboxMode
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
from marimo._environments.overlay import runtime_overlay
from marimo._messaging.types import KernelMessage
from marimo._runtime import commands
@@ -40,17 +37,22 @@ from marimo._session.queue import ProcessLike, QueueType, route_control_request
from marimo._session.types import KernelManager, QueueManager
from marimo._utils.subprocess import (
interrupt_kernel_process,
+ stop_subprocess,
try_kill_process_and_group,
)
from marimo._utils.typed_connection import TypedConnection
if TYPE_CHECKING:
+ from collections.abc import Callable
+ from typing import Literal
+
from marimo._ast.cell import CellConfig
from marimo._environments.sandbox import NotebookSandbox
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._session.model import StartupPhase
from marimo._types.ids import CellId_t
LOGGER = _loggers.marimo_logger()
@@ -276,7 +278,7 @@ class IPCKernelManagerImpl(KernelManager):
app_metadata: AppMetadata,
config_manager: MarimoConfigReader,
redirect_console_to_browser: bool = True,
- sandbox_mode: SandboxMode = SandboxMode.MULTI,
+ on_progress: Callable[[StartupPhase], None] | None = None,
) -> None:
self.queue_manager = queue_manager
self.connection_info = connection_info
@@ -285,31 +287,24 @@ class IPCKernelManagerImpl(KernelManager):
self.app_metadata = app_metadata
self.config_manager = config_manager
self.redirect_console_to_browser = redirect_console_to_browser
- self.sandbox_mode = sandbox_mode
+ self._on_progress = on_progress
self._process: subprocess.Popen[bytes] | None = None
+ self._start_new_session = False
self.kernel_task: ProcessLike | None = None
self._venv_python: str | None = None
self._profile_path = _profile_path_for(app_metadata.filename)
- self._script_environment: Environment | None = None
self._notebook_sandbox: NotebookSandbox | 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."""
- if self._notebook_sandbox is not None:
- return self._notebook_sandbox.environment
- return self._script_environment
-
@property
def notebook_sandbox(self) -> NotebookSandbox | None:
"""The session-owned notebook sandbox, if this kernel uses one."""
return self._notebook_sandbox
- def start_kernel(self) -> None:
+ async def start_kernel(self) -> None:
from marimo._cli.print import echo, muted
from marimo._ipc.types import KernelArgs
@@ -326,16 +321,12 @@ class IPCKernelManagerImpl(KernelManager):
virtual_file_storage=_virtual_file_storage(),
)
+ if self._on_progress is not None:
+ self._on_progress("preparing-environment")
venv_config = _get_venv_config(self.config_manager)
try:
- # SINGLE already selected its script environment at the CLI.
- # Preserve that precedence when changing its kernel transport.
- configured_python = (
- get_configured_venv_python(
- venv_config, base_path=self.app_metadata.filename
- )
- if self.sandbox_mode is SandboxMode.MULTI
- else None
+ configured_python = get_configured_venv_python(
+ venv_config, base_path=self.app_metadata.filename
)
except ValueError as e:
raise KernelStartupError(str(e)) from e
@@ -361,14 +352,14 @@ class IPCKernelManagerImpl(KernelManager):
# environment can spawn a marimo kernel.
if writable:
try:
- install_marimo_into_venv(venv_python)
+ await install_marimo_into_venv(venv_python)
except Exception as e:
raise KernelStartupError(
f"Failed to install marimo into configured venv.\n\n{e}"
) from e
- elif not has_marimo_installed(venv_python):
+ elif not await has_marimo_installed(venv_python):
# Check Python version compatibility for binary deps
- if not check_python_version_compatibility(venv_python):
+ if not await check_python_version_compatibility(venv_python):
# If we have gotten to this point
# - We have a prescribed venv
# - The venv is not writable
@@ -410,13 +401,9 @@ class IPCKernelManagerImpl(KernelManager):
kernel_args_list = ["-m", "marimo._ipc.launch_kernel"]
overlay = runtime_overlay()
filename = self.app_metadata.filename
- sandbox = (
- NotebookSandbox.from_running_process(None, backend)
- if filename is None and self.sandbox_mode is SandboxMode.SINGLE
- else NotebookSandbox(filename, backend)
- )
+ sandbox = NotebookSandbox(filename, backend)
try:
- plan = sandbox.launch(
+ plan = await sandbox.launch_async(
kernel_args_list,
overlay=overlay,
base_env=os.environ.copy(),
@@ -427,6 +414,9 @@ class IPCKernelManagerImpl(KernelManager):
raise KernelStartupError(
f"Failed to build sandbox environment.\n\n{e}"
) from e
+ except BaseException:
+ sandbox.close()
+ raise
handle = sandbox.environment
if handle is None:
sandbox.close()
@@ -436,7 +426,6 @@ class IPCKernelManagerImpl(KernelManager):
self._notebook_sandbox = sandbox
self._venv_python = handle.python
- self._script_environment = handle
echo(
f"Running kernel in script environment: {muted(handle.root)}",
err=True,
@@ -445,22 +434,26 @@ class IPCKernelManagerImpl(KernelManager):
plan_launched = True
env = plan.env
env["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"
- env["MARIMO_SANDBOX_MODE"] = self.sandbox_mode.value
+ env["MARIMO_SANDBOX_MODE"] = "multi"
env["MARIMO_SANDBOX_BACKEND"] = backend
cmd = list(plan.argv)
+ self._start_new_session = (
+ plan.start_new_session if plan_launched else False
+ )
LOGGER.debug(f"Launching kernel: {' '.join(cmd)}")
+ handshake: asyncio.Future[list[str]] | None = None
try:
- self._process = subprocess.Popen(
+ if self._on_progress is not None:
+ self._on_progress("starting-kernel")
+ self._process = subprocess.Popen( # noqa: ASYNC220 — owns the child before yielding
cmd,
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
env=env,
- start_new_session=(
- plan.start_new_session if plan_launched else False
- ),
+ start_new_session=self._start_new_session,
)
# Drain the kernel's stderr from the very start: uv resolves
@@ -468,52 +461,100 @@ class IPCKernelManagerImpl(KernelManager):
# 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
+ process = self._process
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()
-
- # 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
+ def drain_output(stream: Literal["stdout", "stderr"]) -> None:
+ pipe = process.stderr if stream == "stderr" else process.stdout
+ assert pipe is not None
+ with pipe:
+ for line in iter(pipe.readline, b""):
+ if stream == "stderr":
+ stderr_tail.append(line)
+ try:
+ output = getattr(sys, stream).buffer
+ output.write(line)
+ output.flush()
+ except Exception:
+ pass
+
+ threading.Thread(
+ target=drain_output, args=("stderr",), daemon=True
+ ).start()
+
+ # Pipe I/O stays on a thread for Windows selector loops. EOF
+ # wakes the awaiter just like a handshake; no liveness polling.
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
- )
+ def exchange_handshake() -> list[str]:
+ assert process.stdin is not None
+ assert process.stdout is not None
+ with process.stdin:
+ process.stdin.write(kernel_args.encode_json())
+ process.stdin.flush()
+ try:
+ lines = [
+ process.stdout.readline().decode().strip()
+ for _ in range(expected_lines)
+ ]
+ finally:
+ # Notebook subprocesses can inherit this pipe for stdout.
+ # Keep draining it without occupying an executor worker
+ # for the kernel's lifetime.
+ threading.Thread(
+ target=drain_output, args=("stdout",), daemon=True
+ ).start()
+ if not all(lines):
+ process.wait()
+ return lines
+
+ loop = asyncio.get_running_loop()
+ handshake = loop.run_in_executor(None, exchange_handshake)
+ exited: asyncio.Future[int] = loop.create_future()
+
+ def report_exit(code: int) -> None:
+ if not exited.done():
+ exited.set_result(code)
+
+ def watch_exit() -> None:
+ code = process.wait()
+ try:
+ loop.call_soon_threadsafe(report_exit, code)
+ except RuntimeError:
+ pass # The server's event loop has already closed.
+
+ # A descendant can retain the launcher's pipes after it exits.
+ # Watch exit separately so that case fails promptly too. This
+ # daemon must not occupy an executor worker for the kernel's life.
+ threading.Thread(target=watch_exit, daemon=True).start()
+ try:
+ done, _ = await asyncio.wait(
+ (handshake, exited),
+ timeout=_startup_timeout(),
+ return_when=asyncio.FIRST_COMPLETED,
+ )
+ if not done:
+ raise asyncio.TimeoutError
+ if handshake not in done:
+ # Let the reader finish lines printed immediately before
+ # exit, but don't wait on pipes inherited by descendants.
+ try:
+ await asyncio.wait_for(asyncio.shield(handshake), 0.5)
+ except asyncio.TimeoutError:
+ raise KernelStartupError(
+ f"Kernel exited during startup (exit code {exited.result()})."
+ ) from None
+ lines = handshake.result()
+ finally:
+ exited.cancel()
+ if not all(lines):
+ raise KernelStartupError(
+ f"Kernel exited during startup "
+ f"(exit code {process.returncode}).\n\n"
+ f"Command: {' '.join(cmd)}\n\n"
+ f"Stderr:\n{_decode_tail(stderr_tail)}"
+ )
+ ready = lines[0]
if ready != "KERNEL_READY":
raise KernelStartupError(
f"Kernel failed to start.\n\n"
@@ -522,9 +563,7 @@ class IPCKernelManagerImpl(KernelManager):
)
if plan_launched:
- info = self._await_handshake_line(
- handshake, deadline, stderr_tail, cmd
- )
+ info = lines[1]
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:
@@ -537,74 +576,39 @@ class IPCKernelManagerImpl(KernelManager):
# Create a ProcessLike wrapper for the subprocess
self.kernel_task = _SubprocessWrapper(self._process)
+ except asyncio.TimeoutError as e:
+ raise KernelStartupError(
+ f"Kernel did not become ready within {_startup_timeout():.0f}s "
+ f"(override with MARIMO_KERNEL_STARTUP_TIMEOUT).\n\n"
+ f"Command: {' '.join(cmd)}\n\n"
+ f"Stderr:\n{_decode_tail(stderr_tail)}"
+ ) from e
except KernelStartupError:
- self._cleanup_failed_start()
raise
except Exception as e:
- self._cleanup_failed_start()
# Wrap other exceptions as KernelStartupError
raise KernelStartupError(
f"Failed to start kernel subprocess.\n\n{e}"
) from e
+ finally:
+ if self.kernel_task is None:
+ await self._cleanup_failed_start(handshake)
- def _cleanup_failed_start(self) -> None:
+ async def _cleanup_failed_start(
+ self, handshake: asyncio.Future[list[str]] | None = None
+ ) -> None:
"""Release resources retained before the startup handshake."""
- if self._process is not None and self._process.poll() is None:
- try:
- try_kill_process_and_group(_SubprocessWrapper(self._process))
- except (ProcessLookupError, PermissionError):
- pass
- except Exception as error:
- LOGGER.warning(error)
- if self._notebook_sandbox is not None:
- self._notebook_sandbox.close()
- self._notebook_sandbox = None
-
- 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)}"
+ try:
+ if self._process is not None:
+ await stop_subprocess(
+ self._process,
+ start_new_session=self._start_new_session,
+ drain=handshake,
)
+ finally:
+ if self._notebook_sandbox is not None:
+ self._notebook_sandbox.close()
+ self._notebook_sandbox = None
@property
def pid(self) -> int | None:
diff --git a/marimo/_session/managers/kernel.py b/marimo/_session/managers/kernel.py
index 9a556453e2..ee039bcdad 100644
--- a/marimo/_session/managers/kernel.py
+++ b/marimo/_session/managers/kernel.py
@@ -65,7 +65,7 @@ class KernelManagerImpl(KernelManager):
self._read_conn: TypedConnection[KernelMessage] | None = None
self._virtual_file_storage = virtual_file_storage
- def start_kernel(self) -> None:
+ async def start_kernel(self) -> None:
# We use a process in edit mode so that we can interrupt the app
# with a SIGINT; we don't mind the additional memory consumption,
# since there's only one client session
diff --git a/marimo/_session/model.py b/marimo/_session/model.py
index 36f2328d91..b6e603498a 100644
--- a/marimo/_session/model.py
+++ b/marimo/_session/model.py
@@ -2,6 +2,9 @@
from __future__ import annotations
from enum import Enum
+from typing import Literal
+
+StartupPhase = Literal["preparing-environment", "starting-kernel"]
class ConnectionState(Enum):
diff --git a/marimo/_session/notebook/file_manager.py b/marimo/_session/notebook/file_manager.py
index e6be930e72..14728b0a11 100644
--- a/marimo/_session/notebook/file_manager.py
+++ b/marimo/_session/notebook/file_manager.py
@@ -3,6 +3,7 @@ from __future__ import annotations
import os
import threading
+from contextlib import nullcontext
from pathlib import Path
from typing import TYPE_CHECKING, Any
@@ -12,6 +13,7 @@ from marimo._ast.app import App, InternalApp
from marimo._ast.app_config import overloads_from_env
from marimo._ast.cell import CellConfig
from marimo._environments.script_metadata import (
+ notebook_file_lock,
with_python_version_requirement,
)
from marimo._messaging.notebook.changes import (
@@ -220,7 +222,10 @@ class AppFileManager:
"""
LOGGER.debug("Saving app to %s", path)
- with self._save_lock:
+ # Read the header and write the cells under the same lock as manifest
+ # edits, so neither writer can restore the other's stale contents.
+ file_lock = notebook_file_lock(str(path)) if persist else nullcontext()
+ with self._save_lock, file_lock:
# Get the header in case it was modified by the user (e.g. package installation)
handler = get_notebook_serializer(path)
header: str | None = None
diff --git a/marimo/_session/session.py b/marimo/_session/session.py
index 0eac4cf904..deb45f6a29 100644
--- a/marimo/_session/session.py
+++ b/marimo/_session/session.py
@@ -13,10 +13,12 @@ from typing import TYPE_CHECKING
from uuid import uuid4
from marimo import _loggers
-from marimo._cli.sandbox import SandboxMode
from marimo._config.manager import MarimoConfigManager, ScriptConfigManager
from marimo._messaging.notebook.document import NotebookDocument
-from marimo._messaging.notification import NotificationMessage
+from marimo._messaging.notification import (
+ NotificationMessage,
+ StartupProgressNotification,
+)
from marimo._messaging.serde import serialize_kernel_message
from marimo._messaging.types import KernelMessage
from marimo._runtime import commands
@@ -86,7 +88,7 @@ class SessionImpl(Session):
"""
@classmethod
- def create(
+ async def create(
cls,
*,
initialization_id: str,
@@ -100,7 +102,7 @@ class SessionImpl(Session):
auto_instantiate: bool,
ttl_seconds: int | None,
extensions: list[SessionExtension] | None = None,
- sandbox_mode: SandboxMode | None = None,
+ sandbox: bool = False,
app_host_context: AppHostContext | None = None,
) -> Session:
"""
@@ -114,21 +116,9 @@ class SessionImpl(Session):
configs = app_file_manager.app.cell_manager.config_map()
- from marimo._config.settings import GLOBAL_SETTINGS
-
- # The single-file launcher strips --sandbox before starting the
- # server. Edit kernels must still relaunch from the current manifest,
- # not inherit the server's original interpreter after a rename.
- if (
- mode == SessionMode.EDIT
- and sandbox_mode is None
- and GLOBAL_SETTINGS.SANDBOX_MODE == "single"
- ):
- sandbox_mode = SandboxMode.SINGLE
-
# Create kernel manager
# AppHost path handles multi-app run mode (both sandbox and non-sandbox).
- # SandboxMode.MULTI falls through to IPC kernels only in edit mode.
+ # Sandboxed edit sessions use IPC kernels.
queue_manager: QueueManager
kernel_manager: KernelManager
if app_host_context is not None and mode == SessionMode.RUN:
@@ -156,9 +146,7 @@ class SessionImpl(Session):
config_manager=config_manager,
redirect_console_to_browser=redirect_console_to_browser,
)
- elif sandbox_mode is SandboxMode.MULTI or (
- sandbox_mode is SandboxMode.SINGLE and mode == SessionMode.EDIT
- ):
+ elif sandbox:
# IPC kernel path — edit mode with sandbox
# (AppHostPool is never created in edit mode)
from marimo._ipc import QueueManager as IPCQueueManager
@@ -177,7 +165,11 @@ class SessionImpl(Session):
app_metadata=app_metadata,
config_manager=config_manager,
redirect_console_to_browser=redirect_console_to_browser,
- sandbox_mode=sandbox_mode,
+ on_progress=lambda phase: session_consumer.notify(
+ serialize_kernel_message(
+ StartupProgressNotification(phase=phase)
+ )
+ ),
)
else:
# Original kernel: Process for edit, Thread for run
@@ -220,6 +212,12 @@ class SessionImpl(Session):
SessionViewExtension(),
]
+ try:
+ await kernel_manager.start_kernel()
+ except BaseException:
+ queue_manager.close_queues()
+ raise
+
return cls(
initialization_id=initialization_id,
session_consumer=session_consumer,
@@ -258,7 +256,6 @@ class SessionImpl(Session):
self.scratchpad_lock = asyncio.Lock()
self._notebook_sandbox: NotebookSandbox | None = None
- self._kernel_manager.start_kernel()
self._bind_notebook_sandbox()
self._event_bus = SessionEventBus()
diff --git a/marimo/_session/types.py b/marimo/_session/types.py
index 7bfb1ae862..8edc134282 100644
--- a/marimo/_session/types.py
+++ b/marimo/_session/types.py
@@ -67,7 +67,7 @@ class KernelManager(Protocol):
kernel_task: ProcessLike | threading.Thread | None
mode: SessionMode
- def start_kernel(self) -> None:
+ async def start_kernel(self) -> None:
"""Start the kernel process or thread."""
...
diff --git a/marimo/_utils/inline_script_metadata.py b/marimo/_utils/inline_script_metadata.py
index f2bd6a81d1..a5ea8c458a 100644
--- a/marimo/_utils/inline_script_metadata.py
+++ b/marimo/_utils/inline_script_metadata.py
@@ -408,7 +408,7 @@ def get_headers_from_frontmatter(
pyproject = frontmatter.get("pyproject", "")
if pyproject:
- if not pyproject.startswith("#"):
+ if pyproject.splitlines()[0] != "# /// script":
# Wrap raw TOML content in PEP 723 format
pyproject = script_metadata.wrap_block(pyproject)
headers["pyproject"] = pyproject
diff --git a/marimo/_utils/subprocess.py b/marimo/_utils/subprocess.py
index d9cdd5628a..da5d41f5ef 100644
--- a/marimo/_utils/subprocess.py
+++ b/marimo/_utils/subprocess.py
@@ -6,6 +6,8 @@ import os
import signal
import subprocess
from collections.abc import Callable, Mapping, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from functools import partial
from typing import (
IO,
Any,
@@ -434,7 +436,8 @@ def kill_subprocess(
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:
+ # A launcher may have exited while its descendants still hold the pipes.
+ if process.poll() is not None and (is_windows() or not start_new_session):
return
if is_windows():
try:
@@ -448,10 +451,46 @@ def kill_subprocess(
process.kill()
else:
try:
- if start_new_session:
+ if start_new_session or os.getpgid(process.pid) == process.pid:
os.killpg(process.pid, signal.SIGKILL)
else:
process.kill()
except ProcessLookupError:
pass
process.wait()
+
+
+async def stop_subprocess(
+ process: subprocess.Popen[Any],
+ *,
+ start_new_session: bool,
+ drain: asyncio.Future[Any] | None = None,
+) -> None:
+ """Finish failed-command cleanup before the caller re-raises its error.
+
+ Killing and reaping run off the event loop. Further cancellation cannot
+ abandon the process or the pipe readers supplied by its owner.
+ """
+
+ async def cleanup() -> None:
+ # Pipe readers can fill the default executor while waiting for this
+ # kill. Cleanup must be able to run independently of those readers.
+ with ThreadPoolExecutor(max_workers=1) as executor:
+ await asyncio.get_running_loop().run_in_executor(
+ executor,
+ partial(
+ kill_subprocess,
+ process,
+ start_new_session=start_new_session,
+ ),
+ )
+ if drain is not None:
+ await asyncio.gather(drain, return_exceptions=True)
+
+ task = asyncio.create_task(cleanup())
+ while not task.done():
+ try:
+ await asyncio.shield(task)
+ except asyncio.CancelledError:
+ continue
+ task.result()
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 6d8d1bde41..1e040cb4fc 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -3171,6 +3171,7 @@ components:
- $ref: '#/components/schemas/MissingPackageAlertNotification'
- $ref: '#/components/schemas/InstallingPackageAlertNotification'
- $ref: '#/components/schemas/StartupLogsNotification'
+ - $ref: '#/components/schemas/StartupProgressNotification'
- $ref: '#/components/schemas/KernelStartupErrorNotification'
- $ref: '#/components/schemas/VariablesNotification'
- $ref: '#/components/schemas/VariableValuesNotification'
@@ -3233,6 +3234,7 @@ components:
sql-table-list-preview: '#/components/schemas/SQLTableListPreviewNotification'
sql-table-preview: '#/components/schemas/SQLTablePreviewNotification'
startup-logs: '#/components/schemas/StartupLogsNotification'
+ startup-progress: '#/components/schemas/StartupProgressNotification'
storage-download-ready: '#/components/schemas/StorageDownloadReadyNotification'
storage-entries: '#/components/schemas/StorageEntriesNotification'
storage-namespaces: '#/components/schemas/StorageNamespacesNotification'
@@ -4976,6 +4978,38 @@ components:
- backend
title: SandboxPackageContext
type: object
+ SandboxRequest:
+ properties:
+ fileKey:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
+ required: []
+ title: SandboxRequest
+ type: object
+ SandboxResponse:
+ properties:
+ backend:
+ anyOf:
+ - enum:
+ - pixi
+ - uv
+ - type: 'null'
+ filename:
+ anyOf:
+ - type: string
+ - type: 'null'
+ manifest:
+ anyOf:
+ - type: string
+ - type: 'null'
+ required:
+ - backend
+ - manifest
+ - filename
+ title: SandboxResponse
+ type: object
SaveAppConfigurationRequest:
properties:
config:
@@ -5474,6 +5508,21 @@ components:
- status
title: StartupLogsNotification
type: object
+ StartupProgressNotification:
+ description: Progress reported before a session's kernel is ready.
+ properties:
+ op:
+ enum:
+ - startup-progress
+ phase:
+ enum:
+ - preparing-environment
+ - starting-kernel
+ required:
+ - op
+ - phase
+ title: StartupProgressNotification
+ type: object
StdinRequest:
properties:
text:
@@ -5840,6 +5889,25 @@ components:
- deleteIds
title: SyncGraphCommand
type: object
+ SyncSandboxResponse:
+ properties:
+ error:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
+ reconnect:
+ default: false
+ type: boolean
+ restartRequired:
+ default: false
+ type: boolean
+ success:
+ type: boolean
+ required:
+ - success
+ title: SyncSandboxResponse
+ type: object
ToolDefinition:
description: Tool definition compatible with ai-sdk-ui format.
properties:
@@ -6039,6 +6107,22 @@ components:
- cellIdsToOutput
title: UpdateCellOutputsRequest
type: object
+ UpdateManifestRequest:
+ properties:
+ contents:
+ type: string
+ fileKey:
+ anyOf:
+ - type: string
+ - type: 'null'
+ default: null
+ previous:
+ type: string
+ required:
+ - contents
+ - previous
+ title: UpdateManifestRequest
+ type: object
UpdateUIElementCommand:
description: "Update UI element values.\n\n Triggered when users interact\
\ with UI elements (sliders, inputs, dropdowns, etc.).\n Updates element\
@@ -7769,6 +7853,27 @@ paths:
schema:
$ref: '#/components/schemas/ListPackagesResponse'
description: List installed packages
+ /api/packages/manifest:
+ post:
+ parameters:
+ - in: header
+ name: Marimo-Session-Id
+ required: true
+ schema:
+ type: string
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateManifestRequest'
+ required: true
+ responses:
+ 200:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SandboxResponse'
+ description: Save notebook metadata without changing its cells
/api/packages/remove:
post:
requestBody:
@@ -7783,6 +7888,48 @@ paths:
schema:
$ref: '#/components/schemas/PackageOperationResponse'
description: Uninstall package
+ /api/packages/sandbox:
+ post:
+ parameters:
+ - in: header
+ name: Marimo-Session-Id
+ required: true
+ schema:
+ type: string
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SandboxRequest'
+ required: true
+ responses:
+ 200:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SandboxResponse'
+ description: Sandbox manifest, available before kernel startup
+ /api/packages/sync:
+ post:
+ parameters:
+ - in: header
+ name: Marimo-Session-Id
+ required: true
+ schema:
+ type: string
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SandboxRequest'
+ required: true
+ responses:
+ 200:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SyncSandboxResponse'
+ description: Apply the saved manifest, or reconnect to retry startup
/api/packages/tree:
get:
responses:
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 5901adafc3..13c456f348 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -3097,6 +3097,47 @@ export interface paths {
patch?: never;
trace?: never;
};
+ "/api/packages/manifest": {
+ parameters: {
+ query?: never;
+ header?: never;
+ path?: never;
+ cookie?: never;
+ };
+ get?: never;
+ put?: never;
+ post: {
+ parameters: {
+ query?: never;
+ header: {
+ "Marimo-Session-Id": string;
+ };
+ path?: never;
+ cookie?: never;
+ };
+ requestBody: {
+ content: {
+ "application/json": components["schemas"]["UpdateManifestRequest"];
+ };
+ };
+ responses: {
+ /** @description Save notebook metadata without changing its cells */
+ 200: {
+ headers: {
+ [name: string]: unknown;
+ };
+ content: {
+ "application/json": components["schemas"]["SandboxResponse"];
+ };
+ };
+ };
+ };
+ delete?: never;
+ options?: never;
+ head?: never;
+ patch?: never;
+ trace?: never;
+ };
"/api/packages/remove": {
parameters: {
query?: never;
@@ -3136,6 +3177,88 @@ export interface paths {
patch?: never;
trace?: never;
};
+ "/api/packages/sandbox": {
+ parameters: {
+ query?: never;
+ header?: never;
+ path?: never;
+ cookie?: never;
+ };
+ get?: never;
+ put?: never;
+ post: {
+ parameters: {
+ query?: never;
+ header: {
+ "Marimo-Session-Id": string;
+ };
+ path?: never;
+ cookie?: never;
+ };
+ requestBody: {
+ content: {
+ "application/json": components["schemas"]["SandboxRequest"];
+ };
+ };
+ responses: {
+ /** @description Sandbox manifest, available before kernel startup */
+ 200: {
+ headers: {
+ [name: string]: unknown;
+ };
+ content: {
+ "application/json": components["schemas"]["SandboxResponse"];
+ };
+ };
+ };
+ };
+ delete?: never;
+ options?: never;
+ head?: never;
+ patch?: never;
+ trace?: never;
+ };
+ "/api/packages/sync": {
+ parameters: {
+ query?: never;
+ header?: never;
+ path?: never;
+ cookie?: never;
+ };
+ get?: never;
+ put?: never;
+ post: {
+ parameters: {
+ query?: never;
+ header: {
+ "Marimo-Session-Id": string;
+ };
+ path?: never;
+ cookie?: never;
+ };
+ requestBody: {
+ content: {
+ "application/json": components["schemas"]["SandboxRequest"];
+ };
+ };
+ responses: {
+ /** @description Apply the saved manifest, or reconnect to retry startup */
+ 200: {
+ headers: {
+ [name: string]: unknown;
+ };
+ content: {
+ "application/json": components["schemas"]["SyncSandboxResponse"];
+ };
+ };
+ };
+ };
+ delete?: never;
+ options?: never;
+ head?: never;
+ patch?: never;
+ trace?: never;
+ };
"/api/packages/tree": {
parameters: {
query?: never;
@@ -5636,6 +5759,7 @@ export interface components {
| components["schemas"]["MissingPackageAlertNotification"]
| components["schemas"]["InstallingPackageAlertNotification"]
| components["schemas"]["StartupLogsNotification"]
+ | components["schemas"]["StartupProgressNotification"]
| components["schemas"]["KernelStartupErrorNotification"]
| components["schemas"]["VariablesNotification"]
| components["schemas"]["VariableValuesNotification"]
@@ -6750,6 +6874,17 @@ export interface components {
/** @enum {unknown} */
kind: "sandbox";
};
+ /** SandboxRequest */
+ SandboxRequest: {
+ /** @default null */
+ fileKey?: string | null;
+ };
+ /** SandboxResponse */
+ SandboxResponse: {
+ backend: ("pixi" | "uv") | null;
+ filename: string | null;
+ manifest: string | null;
+ };
/** SaveAppConfigurationRequest */
SaveAppConfigurationRequest: {
config: Record<string, any>;
@@ -7057,6 +7192,16 @@ export interface components {
/** @enum {unknown} */
status: "append" | "done" | "start";
};
+ /**
+ * StartupProgressNotification
+ * @description Progress reported before a session's kernel is ready.
+ */
+ StartupProgressNotification: {
+ /** @enum {unknown} */
+ op: "startup-progress";
+ /** @enum {unknown} */
+ phase: "preparing-environment" | "starting-kernel";
+ };
/** StdinRequest */
StdinRequest: {
text: string;
@@ -7293,6 +7438,16 @@ export interface components {
/** @enum {unknown} */
type: "sync-graph";
};
+ /** SyncSandboxResponse */
+ SyncSandboxResponse: {
+ /** @default null */
+ error?: string | null;
+ /** @default false */
+ reconnect?: boolean;
+ /** @default false */
+ restartRequired?: boolean;
+ success: boolean;
+ };
/**
* ToolDefinition
* @description Tool definition compatible with ai-sdk-ui format.
@@ -7427,6 +7582,13 @@ export interface components {
];
};
};
+ /** UpdateManifestRequest */
+ UpdateManifestRequest: {
+ contents: string;
+ /** @default null */
+ fileKey?: string | null;
+ previous: string;
+ };
/**
* UpdateUIElementCommand
* @description Update UI element values.
diff --git a/tests/_cli/test_cli.py b/tests/_cli/test_cli.py
index 8e9b301a04..0d7b231e04 100644
--- a/tests/_cli/test_cli.py
+++ b/tests/_cli/test_cli.py
@@ -9,7 +9,9 @@ from __future__ import annotations
import contextlib
import inspect
+import json
import os
+import shutil
import signal
import socket
import subprocess
@@ -1388,24 +1390,24 @@ def test_cli_sandbox_edit_no_prompt(temp_marimo_file: str) -> None:
@pytest.mark.parametrize("command", ["edit", "run"])
@pytest.mark.parametrize(
- ("option", "backend"), [("--sandbox=pixi", "pixi"), ("--sandbox", "uv")]
+ ("options", "backend"),
+ [
+ (["--sandbox"], "uv"),
+ (["--sandbox=uv"], "uv"),
+ (["--sandbox=pixi"], "pixi"),
+ (["--sandbox", "uv"], "uv"),
+ (["--sandbox", "pixi"], "pixi"),
+ ],
)
[email protected]("directory", ["pixi", "uv"])
-def test_cli_sandbox_records_backend_and_preserves_paths(
+def test_cli_sandbox_selects_backend(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
command: str,
- option: str,
+ options: list[str],
backend: str,
- directory: str,
) -> None:
- """Kernel launches read the backend from GLOBAL_SETTINGS; `run` must
- record it or `run --sandbox=pixi` launches uv kernels."""
- from marimo._cli.sandbox import SandboxMode
- from marimo._config.settings import GLOBAL_SETTINGS
-
monkeypatch.chdir(tmp_path)
- notebook_dir = tmp_path / directory
+ notebook_dir = tmp_path / "notebooks"
notebook_dir.mkdir()
(notebook_dir / "nb.py").write_text(
codegen.generate_filecontents(
@@ -1415,48 +1417,148 @@ def test_cli_sandbox_records_backend_and_preserves_paths(
),
encoding="utf-8",
)
- runner = CliRunner()
- captured: dict[str, object] = {}
+ monkeypatch.setenv("MARIMO_SERVER_OVERLAY", "1")
+ with patch("marimo._cli.cli.start") as start_server:
+ result = CliRunner().invoke(
+ cli_main, [command, *options, "notebooks", "--headless"]
+ )
+ assert result.exit_code == 0, result.output
+ assert start_server.call_args.kwargs["sandbox"] == backend
+ assert start_server.call_args.kwargs["workspace"].directory == str(
+ notebook_dir
+ )
- def _capture_start(**kwargs: object) -> None:
- captured["backend"] = GLOBAL_SETTINGS.SANDBOX_BACKEND
- captured["sandbox_mode"] = kwargs["sandbox_mode"]
- with (
- patch.dict(os.environ),
- patch.object(GLOBAL_SETTINGS, "SANDBOX_BACKEND", None),
- patch.object(GLOBAL_SETTINGS, "SANDBOX_MODE", None),
- patch.object(GLOBAL_SETTINGS, "MANAGE_SCRIPT_METADATA", False),
- patch("marimo._cli.cli.start", side_effect=_capture_start),
- ):
- result = runner.invoke(
- cli_main,
- [command, option, directory, "--headless"],
- )
[email protected](scope="module")
+def bare_marimo_python(tmp_path_factory: pytest.TempPathFactory) -> str:
+ """A real marimo installation without server tools or test dependencies."""
+ root = tmp_path_factory.mktemp("bare-marimo")
+ python = root / ("Scripts/python.exe" if _is_win32() else "bin/python")
+ subprocess.run(
+ ["uv", "venv", "--python", sys.executable, str(root)], check=True
+ )
+ subprocess.run(
+ ["uv", "pip", "install", "--python", str(python), "-e", "."],
+ check=True,
+ )
+ return str(python)
- assert result.exit_code == 0, result.output
- assert captured["sandbox_mode"] is SandboxMode.MULTI
- assert captured["backend"] == backend
[email protected](not HAS_UV, reason="uv is required to install the fixture")
[email protected]("entry", ["file", "folder", "stdin", "new"])
[email protected]("backend", ["uv", "pixi"])
+def test_editor_sandbox_supplies_server_tools(
+ tmp_path: Path, bare_marimo_python: str, entry: str, backend: str
+) -> None:
+ """Formatting works without adding Ruff to the notebook or host."""
+ from websockets.sync.client import connect
[email protected](not HAS_UV, reason="uv is required for sandbox tests")
-def test_cli_sandbox_edit_new_file() -> None:
- with tempfile.TemporaryDirectory() as d:
- path = os.path.join(d, "new_sandbox_file.py")
- runner = CliRunner()
- 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", "--sandbox", path, "--headless", "--no-token"],
+ from marimo._environments.uv import find_uv_bin
+
+ if entry == "stdin" and _is_win32():
+ pytest.skip("Piped notebooks are not supported on Windows")
+
+ backend_bin = shutil.which(backend)
+ if backend_bin is None:
+ pytest.skip(f"{backend} is required")
+ source = (
+ '# /// script\n# dependencies = ["marimo"]\n# ///\n'
+ "import marimo\napp = marimo.App()\n"
+ )
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text(
+ source.replace('["marimo"]', '["does-not-exist-marimo-test"]')
+ )
+ targets = {"file": [str(notebook)], "folder": [str(tmp_path)]}
+ port = _get_port()
+ # A formatter on the test runner's PATH would hide this regression.
+ env = {
+ **os.environ,
+ "UV": str(find_uv_bin()),
+ "PATH": os.pathsep.join([str(Path(backend_bin).parent), os.defpath]),
+ }
+ env.pop("PYTHONPATH", None)
+ env.pop("MARIMO_SERVER_OVERLAY", None)
+ probe = [
+ bare_marimo_python,
+ "-c",
+ (
+ "import importlib.util, shutil; "
+ "assert shutil.which('ruff') is None; "
+ "assert all(importlib.util.find_spec(p) is None "
+ "for p in ('ruff', 'pylsp', 'pylsp_ruff'))"
+ ),
+ ]
+ subprocess.run(probe, env=env, check=True)
+ with subprocess.Popen(
+ [
+ bare_marimo_python,
+ "-m",
+ "marimo",
+ "new" if entry == "new" else "edit",
+ *targets.get(entry, []),
+ f"--sandbox={backend}",
+ "--headless",
+ "--no-token",
+ "--no-skew-protection",
+ "--port",
+ str(port),
+ ],
+ cwd=tmp_path,
+ env=env,
+ stdin=subprocess.PIPE,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.STDOUT,
+ ) as process:
+ try:
+ assert process.stdin is not None
+ if entry == "stdin":
+ process.stdin.write(source.encode())
+ process.stdin.close()
+ assert process.stdout is not None
+ output = []
+ for line in process.stdout:
+ output.append(line.decode())
+ if b"URL:" in line:
+ break
+ else:
+ pytest.fail("Server did not start: " + "".join(output))
+ assert _try_fetch(port) is not None
+ # An unresolvable manifest must not prevent server startup.
+ notebook.write_text(source)
+ query = urllib.parse.urlencode(
+ {
+ "session_id": "formatting",
+ **({"file": str(notebook)} if entry == "folder" else {}),
+ }
)
- assert result.exit_code == 0, result.output
- mock_run_in_sandbox.assert_called_once()
- call_kwargs = mock_run_in_sandbox.call_args
- assert call_kwargs.kwargs["name"] == path
- assert call_kwargs.kwargs["extras"] == ["lsp"]
+ with connect(f"ws://localhost:{port}/ws?{query}") as websocket:
+ while True:
+ message = json.loads(websocket.recv(timeout=60))
+ assert message["op"] != "kernel-startup-error", message
+ if message["op"] == "kernel-ready":
+ break
+ request = urllib.request.Request(
+ f"http://localhost:{port}/api/kernel/format",
+ data=json.dumps(
+ {
+ "codes": {"cell": "x= 1"},
+ "lineLength": 80,
+ }
+ ).encode(),
+ headers={
+ "Content-Type": "application/json",
+ "Marimo-Session-Id": "formatting",
+ },
+ )
+ with urllib.request.urlopen(request, timeout=10) as response:
+ assert json.load(response) == {"codes": {"cell": "x = 1"}}
+ finally:
+ process.terminate()
+ process.wait(timeout=15)
+ assert notebook.read_text() == source
+ subprocess.run(probe, env=env, check=True)
@pytest.mark.skipif(
@@ -1973,25 +2075,25 @@ def test_cli_with_custom_pyproject_config_no_file(tmp_path: Path) -> None:
finally:
p.kill()
- # marimo new --sandbox, in the directory with pyproject.toml
- runner = CliRunner()
- original_dir = os.getcwd()
+ # The unnamed editor reads the same project configuration.
+ port = _get_port()
+ p = subprocess.Popen(
+ [
+ "marimo",
+ "new",
+ "--sandbox",
+ "-p",
+ str(port),
+ "--headless",
+ "--no-token",
+ ],
+ cwd=tmp_path,
+ )
try:
- os.chdir(tmp_path)
- 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"],
- )
+ assert_custom_config(_try_fetch(port))
finally:
- os.chdir(original_dir)
- assert result.exit_code == 0, result.output
- mock_run_in_sandbox.assert_called_once()
- call_kwargs = mock_run_in_sandbox.call_args
- assert call_kwargs.kwargs["extras"] == ["lsp"]
+ p.kill()
+ p.wait()
# shell-completion has 1 input (value of $SHELL) & 3 outputs (return code, stdout, & stderr)
diff --git a/tests/_cli/test_cli_export_sandbox.py b/tests/_cli/test_cli_export_sandbox.py
new file mode 100644
index 0000000000..b962a10ed6
--- /dev/null
+++ b/tests/_cli/test_cli_export_sandbox.py
@@ -0,0 +1,321 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import json
+import os
+import sys
+from functools import partial
+from pathlib import Path
+from types import ModuleType
+from typing import TYPE_CHECKING
+from unittest.mock import AsyncMock, MagicMock
+
+import click
+import pytest
+from click.testing import CliRunner
+
+from marimo._cli.export import session, thumbnail
+from marimo._environments import backends, environment, pixi, uv
+from marimo._environments.environment import Environment, ProcessPlan
+from marimo._session.state.serialize import get_session_cache_file
+
+if TYPE_CHECKING:
+ from collections.abc import Mapping, Sequence
+
+ from marimo._environments.overlay import RuntimeOverlay
+ from marimo._environments.sandbox import Backend
+
+
+def local_environments(monkeypatch: pytest.MonkeyPatch) -> None:
+ # Substitute dependency installation, but run the real export workers.
+ async def sync(path: str, *, backend: Backend) -> Environment:
+ source = Path(path)
+ root = source.with_suffix("")
+ root.mkdir(exist_ok=True)
+ (root / "sandbox_dependency.py").write_text(
+ f"NAME = {source.stem!r}\nBACKEND = {backend!r}\n",
+ encoding="utf-8",
+ )
+ return Environment(sys.executable, str(root), "unchanged")
+
+ def launch(
+ env: Environment,
+ args: Sequence[str],
+ *,
+ overlay: RuntimeOverlay,
+ backend: Backend,
+ base_env: Mapping[str, str] | None = None,
+ ) -> ProcessPlan:
+ del overlay
+ process_env = dict(os.environ if base_env is None else base_env)
+ process_env["TEST_EXPORT_BACKEND"] = backend
+ process_env["PYTHONPATH"] = os.pathsep.join(
+ [env.root, process_env.get("PYTHONPATH", "")]
+ )
+ return ProcessPlan((env.python, *args), process_env, True)
+
+ monkeypatch.setattr(backends, "sync_notebook_async", sync)
+ monkeypatch.setattr(environment, "launch", partial(launch, backend="uv"))
+ monkeypatch.setattr(pixi, "launch", partial(launch, backend="pixi"))
+ monkeypatch.setattr(backends, "ensure_available", lambda _: None)
+ monkeypatch.setattr(environment, "require_uv_bin", lambda: "uv")
+ monkeypatch.setattr(uv, "require_uv_bin", lambda: "uv")
+ monkeypatch.setattr(pixi, "require_pixi_bin", lambda: "pixi")
+
+
+def browser(monkeypatch: pytest.MonkeyPatch) -> None:
+ page = AsyncMock()
+ context = AsyncMock()
+ context.new_page.return_value = page
+ browser = AsyncMock()
+ browser.new_context.return_value = context
+ playwright = MagicMock()
+ playwright.chromium.launch = AsyncMock(return_value=browser)
+ manager = AsyncMock()
+ manager.__aenter__.return_value = playwright
+ module = ModuleType("playwright.async_api")
+ module.async_playwright = lambda: manager
+ module.TimeoutError = TimeoutError
+ monkeypatch.setitem(sys.modules, "playwright.async_api", module)
+ monkeypatch.setattr(
+ thumbnail.DependencyManager.playwright, "require", lambda _: None
+ )
+
+
+def write_notebook(path: Path) -> None:
+ path.write_text(
+ """# /// script
+# dependencies = ["marimo", "sandbox-dependency"]
+# ///
+import marimo
+
+app = marimo.App()
+
+def _():
+ import json
+ import os
+ from pathlib import Path
+ import marimo as mo
+ import sandbox_dependency
+
+ result = Path(mo.cli_args()["output-dir"]) / (sandbox_dependency.NAME + ".json")
+ result.write_text(json.dumps({"value": mo.cli_args()["value"], "pid": os.getpid(), "backend": sandbox_dependency.BACKEND, "launcher": os.environ["TEST_EXPORT_BACKEND"], "sandbox_arg": mo.cli_args().get("sandbox")}))
+ return
+
+if __name__ == "__main__":
+ app.run()
+""",
+ encoding="utf-8",
+ )
+
+
[email protected]("export_format", ["session", "thumbnail"])
[email protected]("directory", [False, True])
+ ("option", "backend"),
+ [("--sandbox", "uv"), ("--sandbox=uv", "uv"), ("--sandbox=pixi", "pixi")],
+)
[email protected]("local_environments", "browser")
+def test_sandbox_exports_execute_in_each_notebook_environment(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ export_format: str,
+ directory: bool,
+ option: str,
+ backend: Backend,
+) -> None:
+ notebooks = tmp_path / "notebooks"
+ notebooks.mkdir()
+ paths = [notebooks / "first.py", notebooks / "second.py"]
+ for path in paths:
+ write_notebook(path)
+ sources = [path.read_text() for path in paths]
+ target = notebooks if directory else paths[0]
+ command = (
+ session.session if export_format == "session" else thumbnail.thumbnail
+ )
+ args = [str(target), option]
+ if export_format == "thumbnail":
+ args.append("--execute")
+ args.extend(
+ [
+ "--",
+ "--value",
+ "forwarded",
+ "--sandbox=pixi",
+ "--output-dir",
+ str(tmp_path),
+ ]
+ )
+
+ if backend == "pixi":
+
+ def unavailable_uv() -> str:
+ raise AssertionError("Pixi exports must not require a host uv")
+
+ monkeypatch.setattr(uv, "require_uv_bin", unavailable_uv)
+ monkeypatch.setattr(environment, "require_uv_bin", unavailable_uv)
+
+ # Re-enter as the Playwright bootstrap would, preserving notebook args.
+ def bootstrap(plan: ProcessPlan) -> int:
+ assert plan.argv[0] == backend
+ assert "playwright" in plan.argv
+ argv = list(plan.argv[plan.argv.index("marimo") + 3 :])
+ with monkeypatch.context() as child:
+ for key, value in plan.env.items():
+ child.setenv(key, value)
+ result = CliRunner().invoke(command, argv)
+ assert result.exit_code == 0, result.output
+ return result.exit_code
+
+ monkeypatch.setattr(thumbnail, "_wait_on_plan", bootstrap)
+ monkeypatch.setattr(
+ sys, "argv", ["marimo", "export", export_format, *args]
+ )
+ result = CliRunner().invoke(command, args)
+ assert result.exit_code == 0, result.output
+
+ executed = paths if directory else paths[:1]
+ results = {
+ path.stem: json.loads(path.read_text())
+ for path in tmp_path.glob("*.json")
+ }
+ assert set(results) == {path.stem for path in executed}
+ pids = {data["pid"] for data in results.values()}
+ assert os.getpid() not in pids
+ assert len(pids) == len(executed)
+ assert {data["value"] for data in results.values()} == {"forwarded"}
+ assert {
+ (data["backend"], data["launcher"]) for data in results.values()
+ } == {(backend, backend)}
+ assert {data["sandbox_arg"] for data in results.values()} == {"pixi"}
+ assert [path.read_text() for path in paths] == sources
+
+ if export_format == "session":
+ # Fresh snapshots skip environment preparation as well as execution.
+ def unavailable(*_args: object, **_kwargs: object) -> None:
+ raise AssertionError(
+ "A fresh snapshot must not provision dependencies"
+ )
+
+ monkeypatch.setattr(backends, "sync_notebook_async", unavailable)
+ monkeypatch.setattr(backends, "ensure_available", unavailable)
+ result = CliRunner().invoke(command, args)
+ assert result.exit_code == 0, result.output
+ assert "skip:" in result.output
+ assert {
+ path.stem: json.loads(path.read_text())
+ for path in tmp_path.glob("*.json")
+ } == results
+
+
[email protected]("continue_on_error", [False, True])
[email protected]("local_environments")
+def test_session_export_handles_dependency_failure(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ continue_on_error: bool,
+) -> None:
+ paths = [tmp_path / f"{name}.py" for name in ("first", "second", "third")]
+ for path in paths:
+ write_notebook(path)
+ sync = backends.sync_notebook_async
+
+ async def fail_second(path: str, *, backend: Backend) -> Environment:
+ if Path(path).stem == "second":
+ raise click.ClickException("Dependency resolution failed")
+ return await sync(path, backend=backend)
+
+ monkeypatch.setattr(backends, "sync_notebook_async", fail_second)
+ result = CliRunner().invoke(
+ session.session,
+ [
+ str(tmp_path),
+ "--sandbox",
+ "--continue-on-error"
+ if continue_on_error
+ else "--no-continue-on-error",
+ "--",
+ "--value=forwarded",
+ "--output-dir",
+ str(tmp_path),
+ ],
+ )
+ assert result.exit_code == 1
+ assert "Dependency resolution failed" in result.output
+ assert {path.stem for path in tmp_path.glob("*.json")} == (
+ {"first", "third"} if continue_on_error else {"first"}
+ )
+ assert [get_session_cache_file(path).exists() for path in paths] == [
+ True,
+ False,
+ continue_on_error,
+ ]
+
+
+ "options", [["--no-sandbox"], ["--sandbox=pixi", "--no-sandbox"]]
+)
+def test_session_export_does_not_require_a_backend(
+ temp_marimo_file: str,
+ monkeypatch: pytest.MonkeyPatch,
+ options: list[str],
+) -> None:
+ def unavailable(_: Backend) -> None:
+ raise AssertionError(
+ "Non-sandboxed exports must not require a backend"
+ )
+
+ monkeypatch.setattr(backends, "ensure_available", unavailable)
+ result = CliRunner().invoke(session.session, [temp_marimo_file, *options])
+ assert result.exit_code == 0, result.output
+ assert get_session_cache_file(Path(temp_marimo_file)).exists()
+
+
+def test_thumbnail_sandbox_requires_execution(tmp_path: Path) -> None:
+ path = tmp_path / "notebook.py"
+ write_notebook(path)
+ result = CliRunner().invoke(thumbnail.thumbnail, [str(path), "--sandbox"])
+ assert result.exit_code != 0
+ assert "--sandbox requires --execute" in result.output
+
+
+def test_session_export_reports_invalid_worker_output(
+ temp_marimo_file: str,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setattr(
+ session, "run_python_subprocess", AsyncMock(return_value="not json")
+ )
+ result = CliRunner().invoke(
+ session.session, [temp_marimo_file, "--sandbox"]
+ )
+ assert result.exit_code == 1
+ assert "Failed to parse sandbox session export output" in result.output
+ assert not get_session_cache_file(Path(temp_marimo_file)).exists()
+
+
[email protected]("export_format", ["session", "thumbnail"])
[email protected]("backend", ["uv", "pixi"])
+def test_export_reports_missing_selected_backend(
+ export_format: str,
+ backend: Backend,
+ temp_marimo_file: str,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("UV", raising=False)
+ monkeypatch.setenv("PATH", str(tmp_path))
+ monkeypatch.chdir(tmp_path)
+ command = (
+ session.session if export_format == "session" else thumbnail.thumbnail
+ )
+ args = [temp_marimo_file, f"--sandbox={backend}"]
+ if export_format == "thumbnail":
+ args.append("--execute")
+ result = CliRunner().invoke(command, args)
+ assert result.exit_code == 1
+ assert f"{backend} must be installed" in result.output
diff --git a/tests/_cli/test_cli_export_session.py b/tests/_cli/test_cli_export_session.py
deleted file mode 100644
index 38aeb5b99a..0000000000
--- a/tests/_cli/test_cli_export_session.py
+++ /dev/null
@@ -1,272 +0,0 @@
-# Copyright 2026 Marimo. All rights reserved.
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-from unittest.mock import AsyncMock, patch
-
-import click
-import pytest
-from click.testing import CliRunner
-
-import marimo._cli.export.session as session_module
-from marimo._cli.sandbox import SandboxMode
-from marimo._server.utils import asyncio_run
-from marimo._session.state.serialize import get_session_cache_file
-
-if TYPE_CHECKING:
- from pathlib import Path
-
-
-def _write_notebook(path: Path) -> None:
- path.write_text(
- """
-import marimo
-
-app = marimo.App()
-
-def _():
- return
-
-if __name__ == "__main__":
- app.run()
-""",
- encoding="utf-8",
- )
-
-
-def test_session_sandbox_single_runs_in_sandbox(tmp_path: Path) -> None:
- notebook = tmp_path / "notebook.py"
- _write_notebook(notebook)
- runner = CliRunner()
- export_sessions = AsyncMock()
-
- with (
- patch(
- "marimo._cli.sandbox.run_in_sandbox",
- return_value=0,
- ) as run_in_sandbox,
- patch(
- "marimo._cli.sandbox.resolve_sandbox_mode",
- return_value=SandboxMode.SINGLE,
- ) as resolve_sandbox_mode,
- patch.object(session_module, "_export_sessions", new=export_sessions),
- ):
- result = runner.invoke(
- session_module.session,
- [str(notebook), "--sandbox"],
- )
-
- assert result.exit_code == 0, result.output
- run_in_sandbox.assert_called_once()
- resolve_sandbox_mode.assert_called_once()
- assert run_in_sandbox.call_args.kwargs["name"] == str(notebook)
- export_sessions.assert_not_called()
-
-
-def test_session_sandbox_single_skips_before_sandbox_when_fresh(
- tmp_path: Path,
-) -> None:
- notebook = tmp_path / "notebook.py"
- _write_notebook(notebook)
- session_file = get_session_cache_file(notebook)
- session_file.parent.mkdir(parents=True, exist_ok=True)
- session_file.write_text("{}", encoding="utf-8")
- runner = CliRunner()
-
- with (
- patch(
- "marimo._cli.sandbox.resolve_sandbox_mode",
- return_value=SandboxMode.SINGLE,
- ),
- patch.object(
- session_module,
- "is_session_snapshot_stale",
- return_value=False,
- ) as is_stale,
- patch("marimo._cli.sandbox.run_in_sandbox") as run_in_sandbox,
- ):
- result = runner.invoke(
- session_module.session,
- [str(notebook), "--sandbox"],
- )
-
- assert result.exit_code == 0, result.output
- is_stale.assert_called_once()
- run_in_sandbox.assert_not_called()
- assert "skip:" in result.output
-
-
-def test_session_sandbox_multi_uses_in_process_export(tmp_path: Path) -> None:
- notebook_dir = tmp_path / "notebooks"
- notebook_dir.mkdir()
- first = notebook_dir / "first.py"
- second = notebook_dir / "second.py"
- _write_notebook(first)
- _write_notebook(second)
- runner = CliRunner()
- export_sessions = AsyncMock()
-
- with (
- patch("marimo._cli.sandbox.run_in_sandbox") as run_in_sandbox,
- patch("marimo._cli.sandbox.resolve_sandbox_mode") as resolve_mode,
- patch.object(session_module, "_export_sessions", new=export_sessions),
- ):
- result = runner.invoke(
- session_module.session,
- [str(notebook_dir), "--sandbox"],
- )
-
- assert result.exit_code == 0, result.output
- run_in_sandbox.assert_not_called()
- resolve_mode.assert_not_called()
- export_sessions.assert_called_once()
- assert (
- export_sessions.call_args.kwargs["sandbox_mode"] is SandboxMode.MULTI
- )
-
-
-def test_session_no_sandbox_uses_in_process_export(tmp_path: Path) -> None:
- notebook = tmp_path / "notebook.py"
- _write_notebook(notebook)
- runner = CliRunner()
- export_sessions = AsyncMock()
-
- with (
- patch("marimo._cli.sandbox.run_in_sandbox") as run_in_sandbox,
- patch(
- "marimo._cli.sandbox.resolve_sandbox_mode", return_value=None
- ) as resolve_mode,
- patch.object(session_module, "_export_sessions", new=export_sessions),
- ):
- result = runner.invoke(
- session_module.session,
- [str(notebook), "--no-sandbox"],
- )
-
- assert result.exit_code == 0, result.output
- run_in_sandbox.assert_not_called()
- resolve_mode.assert_called_once()
- export_sessions.assert_called_once()
- assert export_sessions.call_args.kwargs["sandbox_mode"] is None
-
-
-def test_export_sessions_continue_on_error_processes_remaining(
- tmp_path: Path,
-) -> None:
- first = tmp_path / "first.py"
- second = tmp_path / "second.py"
- third = tmp_path / "third.py"
- _write_notebook(first)
- _write_notebook(second)
- _write_notebook(third)
- notebooks = [
- session_module.MarimoPath(str(p)) for p in [first, second, third]
- ]
-
- called: list[str] = []
-
- async def fake_export(
- marimo_path: session_module.MarimoPath,
- *,
- notebook_args: tuple[str, ...],
- sandbox: object | None = None,
- ) -> tuple[dict[str, str], bool]:
- del notebook_args, sandbox
- called.append(marimo_path.short_name)
- if marimo_path.short_name == "second.py":
- raise click.ClickException("boom")
- return {"name": marimo_path.short_name}, False
-
- with (
- patch.object(
- session_module,
- "_export_session_snapshot",
- new=AsyncMock(side_effect=fake_export),
- ),
- pytest.raises(
- click.ClickException,
- match="Failed to export sessions for 1 notebooks",
- ),
- ):
- asyncio_run(
- session_module._export_sessions(
- notebooks=notebooks,
- force_overwrite=True,
- notebook_args=(),
- continue_on_error=True,
- sandbox_mode=None,
- )
- )
-
- assert called == ["first.py", "second.py", "third.py"]
- assert get_session_cache_file(first).exists()
- assert not get_session_cache_file(second).exists()
- assert get_session_cache_file(third).exists()
-
-
-def test_export_sessions_no_continue_on_error_stops_at_first_error(
- tmp_path: Path,
-) -> None:
- first = tmp_path / "first.py"
- second = tmp_path / "second.py"
- third = tmp_path / "third.py"
- _write_notebook(first)
- _write_notebook(second)
- _write_notebook(third)
- notebooks = [
- session_module.MarimoPath(str(p)) for p in [first, second, third]
- ]
-
- called: list[str] = []
-
- async def fake_export(
- marimo_path: session_module.MarimoPath,
- *,
- notebook_args: tuple[str, ...],
- sandbox: object | None = None,
- ) -> tuple[dict[str, str], bool]:
- del notebook_args, sandbox
- called.append(marimo_path.short_name)
- if marimo_path.short_name == "first.py":
- raise click.ClickException("first failed")
- return {"name": marimo_path.short_name}, False
-
- with (
- patch.object(
- session_module,
- "_export_session_snapshot",
- new=AsyncMock(side_effect=fake_export),
- ),
- pytest.raises(click.ClickException, match="first failed"),
- ):
- asyncio_run(
- session_module._export_sessions(
- notebooks=notebooks,
- force_overwrite=True,
- notebook_args=(),
- continue_on_error=False,
- sandbox_mode=None,
- )
- )
-
- assert called == ["first.py"]
- assert not get_session_cache_file(first).exists()
- assert not get_session_cache_file(second).exists()
- assert not get_session_cache_file(third).exists()
-
-
-def test_export_session_snapshot_subprocess_invalid_json() -> None:
- with (
- patch.object(
- session_module, "run_python_subprocess", return_value="not json"
- ),
- pytest.raises(
- click.ClickException,
- match="Failed to parse sandbox session export output",
- ),
- ):
- session_module._export_session_snapshot_in_subprocess(
- "python",
- {"path": "notebook.py", "args": []},
- )
diff --git a/tests/_cli/test_cli_export_thumbnail.py b/tests/_cli/test_cli_export_thumbnail.py
deleted file mode 100644
index f8a0840678..0000000000
--- a/tests/_cli/test_cli_export_thumbnail.py
+++ /dev/null
@@ -1,230 +0,0 @@
-# Copyright 2026 Marimo. All rights reserved.
-from __future__ import annotations
-
-import os
-from typing import TYPE_CHECKING
-from unittest.mock import AsyncMock, patch
-
-from click.testing import CliRunner
-
-import marimo._cli.export.thumbnail as thumbnail_module
-from marimo._cli.sandbox import SandboxMode
-
-if TYPE_CHECKING:
- from pathlib import Path
-
-
-def _write_notebook(path: Path) -> None:
- path.write_text(
- """
-import marimo
-
-app = marimo.App()
-
-def _():
- return
-
-if __name__ == "__main__":
- app.run()
-""",
- encoding="utf-8",
- )
-
-
-def test_thumbnail_sandbox_single_bootstrap_adds_playwright(
- tmp_path: Path,
-) -> None:
- notebook = tmp_path / "notebook.py"
- _write_notebook(notebook)
- runner = CliRunner()
-
- captured: dict[str, str | list[str] | None] = {}
-
- def _fake_run_in_sandbox(
- args: list[str],
- *,
- name: str | None = None,
- extras: list[str] | None = None,
- command_deps: list[str] | None = None,
- extra_env: dict[str, str] | None = None,
- ) -> int:
- del args
- del extras
- captured["name"] = name
- captured["deps"] = command_deps
- captured["mode"] = (extra_env or {}).get(
- thumbnail_module._sandbox_mode_env
- )
- captured["bootstrapped"] = (extra_env or {}).get(
- thumbnail_module._sandbox_bootstrapped_env
- )
- return 0
-
- with (
- patch(
- "marimo._cli.sandbox.run_in_sandbox",
- side_effect=_fake_run_in_sandbox,
- ) as run_in_sandbox,
- patch(
- "marimo._cli.sandbox.resolve_sandbox_mode",
- return_value=SandboxMode.SINGLE,
- ),
- patch.object(
- thumbnail_module.DependencyManager.playwright, "require"
- ) as playwright_require,
- ):
- result = runner.invoke(
- thumbnail_module.thumbnail,
- [str(notebook), "--execute", "--sandbox"],
- )
-
- assert result.exit_code == 0, result.output
- run_in_sandbox.assert_called_once()
- playwright_require.assert_not_called()
- assert captured["name"] == str(notebook)
- assert captured["deps"] == ["playwright"]
- assert captured["mode"] == SandboxMode.SINGLE.value
- assert captured["bootstrapped"] == "1"
- assert thumbnail_module._sandbox_bootstrapped_env not in os.environ
- assert thumbnail_module._sandbox_mode_env not in os.environ
-
-
-def test_thumbnail_sandbox_multi_bootstrap_sets_multi_mode(
- tmp_path: Path,
-) -> None:
- first = tmp_path / "first.py"
- second = tmp_path / "second.py"
- _write_notebook(first)
- _write_notebook(second)
- runner = CliRunner()
-
- captured: dict[str, str | list[str] | None] = {}
-
- def _fake_run_in_sandbox(
- args: list[str],
- *,
- name: str | None = None,
- extras: list[str] | None = None,
- command_deps: list[str] | None = None,
- extra_env: dict[str, str] | None = None,
- ) -> int:
- del args
- del extras
- captured["name"] = name
- captured["deps"] = command_deps
- captured["mode"] = (extra_env or {}).get(
- thumbnail_module._sandbox_mode_env
- )
- return 0
-
- with (
- patch(
- "marimo._cli.sandbox.run_in_sandbox",
- side_effect=_fake_run_in_sandbox,
- ) as run_in_sandbox,
- patch("marimo._cli.sandbox.resolve_sandbox_mode") as resolve_mode,
- patch.object(
- thumbnail_module.DependencyManager.playwright, "require"
- ) as playwright_require,
- ):
- result = runner.invoke(
- thumbnail_module.thumbnail,
- [str(first), str(second), "--execute", "--sandbox"],
- )
-
- assert result.exit_code == 0, result.output
- run_in_sandbox.assert_called_once()
- resolve_mode.assert_not_called()
- playwright_require.assert_not_called()
- assert captured["name"] == str(first)
- assert captured["deps"] == ["playwright"]
- assert captured["mode"] == SandboxMode.MULTI.value
-
-
-def test_thumbnail_sandbox_requires_execute(tmp_path: Path) -> None:
- notebook = tmp_path / "notebook.py"
- _write_notebook(notebook)
- runner = CliRunner()
-
- result = runner.invoke(
- thumbnail_module.thumbnail,
- [str(notebook), "--sandbox"],
- )
-
- assert result.exit_code != 0
- assert "--sandbox requires --execute" in result.output
-
-
-def test_thumbnail_reentry_single_skips_bootstrap(
- tmp_path: Path,
- monkeypatch,
-) -> None:
- notebook = tmp_path / "notebook.py"
- _write_notebook(notebook)
- runner = CliRunner()
- generate = AsyncMock()
-
- monkeypatch.setenv(thumbnail_module._sandbox_bootstrapped_env, "1")
- monkeypatch.setenv(
- thumbnail_module._sandbox_mode_env,
- SandboxMode.SINGLE.value,
- )
-
- with (
- patch("marimo._cli.sandbox.run_in_sandbox") as run_in_sandbox,
- patch("marimo._cli.sandbox.resolve_sandbox_mode") as resolve_mode,
- patch.object(
- thumbnail_module.DependencyManager.playwright, "require"
- ) as playwright_require,
- patch.object(thumbnail_module, "_generate_thumbnails", new=generate),
- ):
- result = runner.invoke(
- thumbnail_module.thumbnail,
- [str(notebook), "--execute"],
- )
-
- assert result.exit_code == 0, result.output
- run_in_sandbox.assert_not_called()
- resolve_mode.assert_not_called()
- playwright_require.assert_called_once_with("for thumbnail generation")
- generate.assert_called_once()
- assert generate.call_args.kwargs["sandbox_mode"] is SandboxMode.SINGLE
-
-
-def test_thumbnail_reentry_multi_skips_bootstrap(
- tmp_path: Path,
- monkeypatch,
-) -> None:
- first = tmp_path / "first.py"
- second = tmp_path / "second.py"
- _write_notebook(first)
- _write_notebook(second)
- runner = CliRunner()
- generate = AsyncMock()
-
- monkeypatch.setenv(thumbnail_module._sandbox_bootstrapped_env, "1")
- monkeypatch.setenv(
- thumbnail_module._sandbox_mode_env,
- SandboxMode.MULTI.value,
- )
-
- with (
- patch("marimo._cli.sandbox.run_in_sandbox") as run_in_sandbox,
- patch("marimo._cli.sandbox.resolve_sandbox_mode") as resolve_mode,
- patch.object(
- thumbnail_module.DependencyManager.playwright, "require"
- ) as playwright_require,
- patch.object(thumbnail_module, "_generate_thumbnails", new=generate),
- ):
- result = runner.invoke(
- thumbnail_module.thumbnail,
- [str(first), str(second), "--execute"],
- )
-
- assert result.exit_code == 0, result.output
- run_in_sandbox.assert_not_called()
- resolve_mode.assert_not_called()
- playwright_require.assert_called_once_with("for thumbnail generation")
- generate.assert_called_once()
- assert generate.call_args.kwargs["sandbox_mode"] is SandboxMode.MULTI
diff --git a/tests/_cli/test_export_subprocess.py b/tests/_cli/test_export_subprocess.py
index 78e9f10994..d8a35aa441 100644
--- a/tests/_cli/test_export_subprocess.py
+++ b/tests/_cli/test_export_subprocess.py
@@ -1,57 +1,155 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+import asyncio
+import json
import os
+import select
+import signal
import subprocess
import sys
-from typing import Any
+from typing import TYPE_CHECKING, Any
from unittest.mock import patch
import click
import pytest
-from marimo._cli.export._common import SandboxTarget, run_python_subprocess
+from marimo._cli.export._common import run_python_subprocess
from marimo._environments.environment import Environment, ProcessPlan
+from marimo._environments.pixi import PixiMissingScriptMetadataError
+from marimo._environments.sandbox import Backend
+from marimo._environments.uv import UvMissingScriptMetadataError
+if TYPE_CHECKING:
+ from pathlib import Path
[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 = (
- "marimo._environments.backends.launch_fallback"
- if isolated
- else f"{module}.launch"
+
+def notebook_without_metadata(monkeypatch: pytest.MonkeyPatch) -> str:
+ async def missing_metadata(*_args: Any, **_kwargs: Any) -> None:
+ raise UvMissingScriptMetadataError(
+ ["uv", "sync"], 1, "", "No script metadata"
+ )
+
+ monkeypatch.setattr(
+ "marimo._environments.backends.sync_notebook_async", missing_metadata
)
+ return "notebook.py"
+
+
+async def test_export_runs_the_planned_command() -> None:
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),
+ with (
+ patch(
+ "marimo._environments.backends.sync_notebook_async",
+ return_value=Environment(sys.executable, sys.prefix, "unchanged"),
+ ),
+ patch("marimo._environments.environment.launch", return_value=plan),
+ ):
+ output = await run_python_subprocess(
+ notebook_path="notebook.py",
+ backend="uv",
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
-):
[email protected]("backend", ["uv", "pixi"])
+async def test_export_without_metadata_uses_current_interpreter(
+ notebook_without_metadata: str,
+ backend: Backend,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ if backend == "pixi":
+
+ async def missing_metadata(*_args: Any, **_kwargs: Any) -> None:
+ raise PixiMissingScriptMetadataError(
+ ["pixi", "install"], 1, "No script metadata"
+ )
+
+ monkeypatch.setattr(
+ "marimo._environments.backends.sync_notebook_async",
+ missing_metadata,
+ )
+
+ payload = {"args": ["value with spaces", "--flag"], "unicode": "🎲"}
+ output = await run_python_subprocess(
+ notebook_path=notebook_without_metadata,
+ backend=backend,
+ script="import json,sys; print(json.dumps([sys.executable, json.loads(sys.argv[1])]))",
+ payload=payload,
+ action="export",
+ )
+ assert json.loads(output) == [sys.executable, payload]
+
+
[email protected](os.name == "nt", reason="POSIX process groups")
+async def test_export_fallback_cancellation_stops_descendants(
+ notebook_without_metadata: str, tmp_path: Path
+) -> None:
+ import psutil
+
+ ready = tmp_path / "child.pid"
+ child_code = (
+ "import os, signal; from pathlib import Path; "
+ f"Path({str(ready)!r}).write_text(str(os.getpid())); "
+ "signal.pause()"
+ )
+ script = (
+ "import subprocess, sys; "
+ f"subprocess.Popen([sys.executable, '-c', {child_code!r}])"
+ )
+ task = asyncio.create_task(
+ run_python_subprocess(
+ notebook_path=notebook_without_metadata,
+ backend="uv",
+ script=script,
+ payload={},
+ action="export",
+ )
+ )
+ child = None
+ try:
+
+ async def wait_for_child() -> int:
+ while True:
+ try:
+ return int(await asyncio.to_thread(ready.read_text))
+ except (FileNotFoundError, ValueError):
+ await asyncio.sleep(0.01)
+
+ child = psutil.Process(await asyncio.wait_for(wait_for_child(), 5))
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await asyncio.wait_for(task, timeout=5)
+ _, alive = await asyncio.to_thread(
+ psutil.wait_procs, [child], timeout=5
+ )
+ assert not alive, "Cancelled export left its descendant running"
+ finally:
+ if child is not None:
+ try:
+ child.kill()
+ except psutil.NoSuchProcess:
+ pass
+ task.cancel()
+ await asyncio.gather(task, return_exceptions=True)
+
+
+async def test_export_failure_identifies_launcher_without_payload_or_credentials(
+ notebook_without_metadata: str,
+) -> None:
plan = ProcessPlan(
(
sys.executable,
@@ -67,8 +165,9 @@ def test_export_failure_identifies_launcher_without_payload_or_credentials() ->
"marimo._environments.backends.launch_fallback", return_value=plan
):
with pytest.raises(click.ClickException) as error:
- run_python_subprocess(
- sandbox=SandboxTarget(None),
+ await run_python_subprocess(
+ notebook_path=notebook_without_metadata,
+ backend="uv",
script="private notebook",
payload={"token": "secret"},
action="export",
@@ -80,87 +179,103 @@ def test_export_failure_identifies_launcher_without_payload_or_credentials() ->
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
[email protected](os.name == "nt", reason="POSIX termination signals")
[email protected]("signal_name", ["SIGINT", "SIGTERM"])
[email protected]("phase", ["preparation", "execution"])
+def test_session_cli_cancellation_stops_active_subprocesses(
+ tmp_path: Path, signal_name: str, phase: str
+) -> None:
+ import psutil
- class InterruptedProcess(subprocess.Popen):
- def communicate(self, *_args: Any, **_kwargs: Any):
- assert self.stdout.readline().strip() == "ready"
- raise KeyboardInterrupt
+ ready = tmp_path / "ready"
+ os.mkfifo(ready)
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text(
+ "import marimo\napp = marimo.App()\[email protected]\ndef _():\n"
+ " import os, time\n from pathlib import Path\n"
+ f" Path({str(ready)!r}).write_text(str(os.getpid()))\n"
+ " time.sleep(30)\n return\n",
+ encoding="utf-8",
+ )
+ # Skip dependency installation, but exercise the CLI, worker, and kernel.
+ code = """
+from marimo._cli.cli import main
+from marimo._environments import backends
+from marimo._environments.uv import UvMissingScriptMetadataError
- 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
+async def missing_metadata(*args, **kwargs):
+ raise UvMissingScriptMetadataError(["uv", "sync"], 1, "", "No script metadata")
- plan = ProcessPlan(
- (
- sys.executable,
- "-c",
- "import time; print('ready', flush=True); time.sleep(30)",
- ),
- dict(os.environ),
- new_session,
- )
+backends.sync_notebook_async = missing_metadata
+main(prog_name="marimo")
+"""
+
+ env = dict(os.environ)
+ if phase == "preparation":
+ # Stop in the real preparation path before an export worker exists.
+ command = tmp_path / "uv"
+ command.write_text(
+ f"#!{sys.executable}\n"
+ "import os, signal, sys\nfrom pathlib import Path\n"
+ "if '--version' in sys.argv:\n"
+ " print('uv 0.12.0')\n"
+ "elif 'sync' in sys.argv:\n"
+ f" Path({str(ready)!r}).write_text(str(os.getpid()))\n"
+ " signal.pause()\n",
+ encoding="utf-8",
+ )
+ command.chmod(0o755)
+ env["UV"] = str(command)
+ code = "from marimo._cli.cli import main; main(prog_name='marimo')"
+
+ children: list[psutil.Process] = []
with (
- patch(
- "marimo._environments.backends.launch_fallback",
- return_value=plan,
- ),
- patch(
- "marimo._cli.export._common.subprocess.Popen", side_effect=launch
- ),
+ (tmp_path / "stderr").open("w+") as stderr,
+ os.fdopen(
+ os.open(ready, os.O_RDONLY | os.O_NONBLOCK), "rb"
+ ) as readiness,
):
- with pytest.raises(KeyboardInterrupt):
- run_python_subprocess(
- sandbox=SandboxTarget(None),
- script="",
- payload={},
- action="export",
+ parent = subprocess.Popen(
+ [
+ sys.executable,
+ "-c",
+ code,
+ "export",
+ "session",
+ str(tmp_path),
+ "--sandbox",
+ ],
+ cwd=tmp_path,
+ env=env,
+ stdout=subprocess.DEVNULL,
+ stderr=stderr,
+ start_new_session=True,
+ )
+ try:
+ assert select.select([readiness], [], [], 15)[0], (
+ "Sandbox subprocess did not start"
)
- 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, backends
-child = "import os,time; from pathlib import Path; Path({str(ready)!r}).write_text(str(os.getpid())); time.sleep(30)"
-backends.launch_fallback = 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
+ active_pid = int(readiness.read())
+ children = psutil.Process(parent.pid).children(recursive=True)
+ assert active_pid in {child.pid for child in children}
+ signum = getattr(signal, signal_name)
+ parent.send_signal(signum)
+ exit_code = parent.wait(timeout=5)
+ _, alive = psutil.wait_procs(children, timeout=5)
+ assert not alive, "Export left children running"
+ # Click reports KeyboardInterrupt as an aborted command (exit 1).
+ assert exit_code == (
+ 1 if signal_name == "SIGINT" else 128 + signum
+ )
+ finally:
+ if parent.poll() is None:
+ children += psutil.Process(parent.pid).children(recursive=True)
+ for child in reversed(children):
+ try:
+ child.kill()
+ except psutil.NoSuchProcess:
+ pass
+ parent.kill()
+ parent.wait(timeout=5)
+ stderr.seek(0)
+ print(stderr.read())
diff --git a/tests/_cli/test_sandbox.py b/tests/_cli/test_sandbox.py
index 0494e4d6aa..d8a2eaf4e1 100644
--- a/tests/_cli/test_sandbox.py
+++ b/tests/_cli/test_sandbox.py
@@ -8,11 +8,10 @@ from unittest.mock import patch
import pytest
from marimo._cli.sandbox import (
- SandboxMode,
_normalize_sandbox_dependencies,
_uv_export_script_requirements_txt,
construct_uv_command,
- resolve_sandbox_mode,
+ resolve_sandbox,
run_in_sandbox,
)
from marimo._dependencies.dependencies import DependencyManager
@@ -459,8 +458,7 @@ import marimo
assert "numpy" in requirements
-def test_resolve_sandbox_mode_user_confirms(tmp_path: Path) -> None:
- """Test that resolve_sandbox_mode returns SandboxMode.SINGLE when user types 'y'."""
+def test_resolve_sandbox_user_confirms(tmp_path: Path) -> None:
# Create a file with dependencies
script_path = tmp_path / "test.py"
script_path.write_text(
@@ -482,70 +480,12 @@ import marimo
patch("marimo._cli.sandbox.is_uv_available", return_value=True),
patch("marimo._cli.sandbox.sys.stdin.isatty", return_value=True),
):
- result = resolve_sandbox_mode(
+ result = resolve_sandbox(
sandbox=None,
+ no_sandbox=False,
name=str(script_path),
)
- assert result is SandboxMode.SINGLE
-
-
-def test_resolve_sandbox_mode_explicit_single() -> None:
- """Test that resolve_sandbox_mode returns SandboxMode.SINGLE for single file with sandbox=True."""
- result = resolve_sandbox_mode(
- sandbox=True,
- name="test.py",
- )
- assert result is SandboxMode.SINGLE
-
-
-def test_resolve_sandbox_mode_explicit_false() -> None:
- """Test that resolve_sandbox_mode returns None when sandbox=False."""
- result = resolve_sandbox_mode(
- sandbox=False,
- name="test.py",
- )
- assert result is None
-
-
-def test_resolve_sandbox_mode_directory(tmp_path: Path) -> None:
- """Test that resolve_sandbox_mode returns SandboxMode.MULTI for directories."""
- dir_path = tmp_path / "notebooks"
- dir_path.mkdir()
-
- # Directory with sandbox=True returns SandboxMode.MULTI
- result = resolve_sandbox_mode(
- sandbox=True,
- name=str(dir_path),
- )
- assert result is SandboxMode.MULTI
-
-
-def test_resolve_sandbox_mode_all_cases(tmp_path: Path) -> None:
- """Test resolve_sandbox_mode for all cases."""
- dir_path = tmp_path / "notebooks"
- dir_path.mkdir()
- file_path = tmp_path / "notebook.py"
- file_path.write_text("# test")
-
- # sandbox=False always returns None
- assert resolve_sandbox_mode(sandbox=False, name=None) is None
- assert resolve_sandbox_mode(sandbox=False, name=str(dir_path)) is None
- assert resolve_sandbox_mode(sandbox=False, name=str(file_path)) is None
-
- # sandbox=True with None (current dir) -> SandboxMode.MULTI
- assert resolve_sandbox_mode(sandbox=True, name=None) is SandboxMode.MULTI
-
- # sandbox=True with directory -> SandboxMode.MULTI
- assert (
- resolve_sandbox_mode(sandbox=True, name=str(dir_path))
- is SandboxMode.MULTI
- )
-
- # sandbox=True with file -> SandboxMode.SINGLE
- assert (
- resolve_sandbox_mode(sandbox=True, name=str(file_path))
- is SandboxMode.SINGLE
- )
+ assert result == "uv"
def test_construct_uv_cmd_without_python_version(tmp_path: Path) -> None:
@@ -765,47 +705,29 @@ def test_sandbox_exit_codes_propagate(tmp_path: Path) -> None:
)
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(
+ "marimo._cli.export.commands.run_in_sandbox", return_value=3
):
- 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)
-
-
-def test_resolve_sandbox_backends(tmp_path: Path) -> None:
- from marimo._cli.sandbox import resolve_sandbox
-
- notebook = tmp_path / "nb.py"
- notebook.write_text("import marimo\n")
-
- mode, backend = resolve_sandbox("pixi", False, str(notebook))
- assert mode is SandboxMode.SINGLE
- assert backend == "pixi"
+ result = runner.invoke(
+ cli_main, ["export", "html", str(notebook), "--sandbox"]
+ )
+ assert result.exit_code == 3, result.output
- mode, backend = resolve_sandbox("uv", False, str(notebook))
- assert mode is SandboxMode.SINGLE
- assert backend == "uv"
- mode, backend = resolve_sandbox("pixi", False, str(tmp_path))
- assert mode is SandboxMode.MULTI
- assert backend == "pixi"
[email protected]("name", [None, "notebook.py"])
[email protected]("backend", ["uv", "pixi"])
+def test_explicit_sandbox_selection(
+ name: str | None, backend: str, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ def unexpected_prompt(_name: str | None) -> bool:
+ raise AssertionError("Explicit sandbox flags must not prompt")
- mode, backend = resolve_sandbox("pixi", True, str(notebook))
- assert mode is None
+ monkeypatch.setattr(
+ "marimo._cli.sandbox.maybe_prompt_run_in_sandbox", unexpected_prompt
+ )
+ assert resolve_sandbox(backend, False, name) == backend
+ assert resolve_sandbox(backend, True, name) is None
+ assert resolve_sandbox(None, True, name) is None
def test_strip_sandbox_args() -> None:
@@ -819,10 +741,10 @@ def test_strip_sandbox_args() -> None:
) == ["-m", "marimo", "edit", "nb.py"]
assert _strip_sandbox_args(
["-m", "marimo", "edit", "--sandbox", "pixi", "nb.py"]
- ) == ["-m", "marimo", "edit", "pixi", "nb.py"]
+ ) == ["-m", "marimo", "edit", "nb.py"]
assert _strip_sandbox_args(
["-m", "marimo", "edit", "--sandbox", "uv"]
- ) == ["-m", "marimo", "edit", "uv"]
+ ) == ["-m", "marimo", "edit"]
assert _strip_sandbox_args(
["-m", "marimo", "run", "--sandbox", "nb.py", "--", "--sandbox"]
) == ["-m", "marimo", "run", "nb.py", "--", "--sandbox"]
@@ -863,3 +785,27 @@ def test_sandbox_launch_normalizes_child_status(
process.wait.return_value = returncode
with patch("marimo._cli.sandbox.subprocess.Popen", return_value=process):
assert _wait_on_plan(ProcessPlan(argv=("uv",), env={})) == expected
+
+
+def test_editor_reports_unsupported_sandbox_backend(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from click.testing import CliRunner
+
+ from marimo._cli.cli import main
+ from marimo._environments.errors import EnvironmentManagerError
+
+ def unavailable(_backend: str) -> None:
+ raise EnvironmentManagerError(
+ "pixi is too old for script environments"
+ )
+
+ monkeypatch.delenv("MARIMO_SERVER_OVERLAY", raising=False)
+ monkeypatch.setattr(
+ "marimo._environments.backends.ensure_available", unavailable
+ )
+ result = CliRunner().invoke(
+ main, ["new", "--sandbox", "pixi", "--headless"]
+ )
+ assert result.exit_code == 1
+ assert "Error: pixi is too old for script environments" in result.output
diff --git a/tests/_environments/test_async_preparation.py b/tests/_environments/test_async_preparation.py
new file mode 100644
index 0000000000..1bb49119ae
--- /dev/null
+++ b/tests/_environments/test_async_preparation.py
@@ -0,0 +1,244 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from contextlib import nullcontext
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+
+from marimo._environments import script_metadata
+from marimo._environments.errors import SandboxRestartRequired
+from marimo._environments.overlay import RuntimeOverlay
+from marimo._environments.sandbox import NotebookSandbox
+
+if TYPE_CHECKING:
+ from marimo._environments.sandbox import Backend
+
+
[email protected](params=["uv", "pixi"])
+def backend(
+ request: pytest.FixtureRequest,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> Backend:
+ if os.name == "nt":
+ pytest.skip("Executable script fixtures require POSIX")
+ name = request.param
+ command = tmp_path / name
+ command.write_text(
+ f"#!{sys.executable}\n"
+ + r"""
+import json, os, signal, sys
+if '--version' in sys.argv:
+ print('uv 0.12.0')
+ sys.exit()
+if '--help' in sys.argv:
+ print('--script')
+ sys.exit()
+source = sys.argv[sys.argv.index('--script') + 1]
+print(json.dumps({'pid': os.getpid(), 'source': source}), file=sys.stderr, flush=True)
+signal.pause()
+""",
+ encoding="utf-8",
+ )
+ command.chmod(0o755)
+ monkeypatch.setenv("UV", str(tmp_path / "uv"))
+ monkeypatch.setenv("PATH", str(tmp_path))
+ return name
+
+
+def markdown(tmp_path: Path) -> Path:
+ path = tmp_path / "notebook.md"
+ path.write_text(
+ "---\npyproject: |\n dependencies = []\n---\n\n# Notebook\n"
+ )
+ return path
+
+
+async def test_cancelled_preparation_releases_carrier(
+ backend: Backend, markdown: Path
+) -> None:
+ import psutil
+
+ original = markdown.read_text() # noqa: ASYNC240
+ ready = asyncio.Event()
+ command: dict[str, str | int] = {}
+
+ def on_output(line: str) -> None:
+ command.update(json.loads(line))
+ ready.set()
+
+ sandbox = NotebookSandbox(str(markdown), backend)
+ task = asyncio.create_task(
+ sandbox.launch_async(
+ [], overlay=RuntimeOverlay("marimo"), on_output=on_output
+ )
+ )
+ try:
+ await asyncio.wait_for(ready.wait(), timeout=5)
+ carrier = Path(str(command["source"]))
+ assert carrier.exists() # noqa: ASYNC240
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await asyncio.wait_for(asyncio.shield(task), timeout=5)
+ assert not psutil.pid_exists(int(command["pid"]))
+ assert not carrier.exists() # noqa: ASYNC240
+ assert markdown.read_text() == original # noqa: ASYNC240
+ assert sandbox.environment is None
+ finally:
+ task.cancel()
+ await asyncio.gather(task, return_exceptions=True)
+ sandbox.close()
+
+
+async def test_waiting_for_carrier_lock_is_cancellable(markdown: Path) -> None:
+ started = asyncio.Event()
+
+ async def wait_for_carrier() -> None:
+ started.set()
+ async with script_metadata.materialized_for_environment_async(
+ str(markdown)
+ ):
+ pytest.fail("Acquired a carrier still owned by another operation")
+
+ with script_metadata.materialized_for_environment(str(markdown)) as owner:
+ task = asyncio.create_task(wait_for_carrier())
+ try:
+ await started.wait()
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await asyncio.wait_for(asyncio.shield(task), timeout=2)
+ assert Path(owner.path).exists() # noqa: ASYNC240
+ finally:
+ task.cancel()
+ await asyncio.gather(task, return_exceptions=True)
+ async with script_metadata.materialized_for_environment_async(
+ str(markdown)
+ ) as next_owner:
+ assert next_owner.path == owner.path
+
+
+async def test_failed_preparation_leaves_notebook_directory_clean(
+ markdown: Path,
+) -> None:
+ from unittest.mock import AsyncMock, MagicMock
+
+ from marimo._environments.errors import EnvironmentManagerError
+
+ adapter = MagicMock()
+ adapter.name = "uv"
+ adapter.ensure_available_async = AsyncMock()
+ adapter.prepare_source_async = AsyncMock()
+ adapter.sync_async = AsyncMock(
+ side_effect=EnvironmentManagerError("No solution found")
+ )
+ sandbox = NotebookSandbox(str(markdown), "uv", adapter=adapter)
+ try:
+ with pytest.raises(EnvironmentManagerError, match="No solution found"):
+ await sandbox.launch_async([], overlay=RuntimeOverlay("marimo"))
+ finally:
+ sandbox.close()
+ assert list(markdown.parent.iterdir()) == [markdown]
+
+
[email protected]("backend", ["uv", "pixi"])
+async def test_sync_running_sandbox_retains_active_environment(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, backend: str
+) -> None:
+ from unittest.mock import AsyncMock
+
+ from marimo._environments.backends import (
+ PixiBackendAdapter,
+ UvBackendAdapter,
+ )
+ from marimo._environments.environment import Environment
+ from marimo._environments.errors import SandboxRestartRequired
+ from marimo._environments.sandbox import NotebookSandbox
+
+ source = tmp_path / "notebook.py"
+ source.write_text("# /// script\n# dependencies = []\n# ///\n")
+ active = Environment(
+ python="/active/bin/python", root="/active", action="unchanged"
+ )
+ moved = Environment(
+ python="/other/bin/python", root="/other", action="updated"
+ )
+ adapter = UvBackendAdapter() if backend == "uv" else PixiBackendAdapter()
+ monkeypatch.setattr(adapter, "ensure_available_async", AsyncMock())
+ sync = AsyncMock(return_value=active if backend == "uv" else moved)
+ target = (
+ "marimo._environments.environment.sync_async"
+ if backend == "uv"
+ else "marimo._environments.pixi.sync_async"
+ )
+ monkeypatch.setattr(target, sync)
+ sandbox = NotebookSandbox(
+ str(source), backend, environment=active, adapter=adapter
+ )
+ if backend == "pixi":
+ with pytest.raises(SandboxRestartRequired):
+ await sandbox.sync_async()
+ else:
+ await sandbox.sync_async()
+ assert sync.call_args.kwargs["active_environment"] == active
+ assert sandbox.environment == active
+
+
+ ("operation", "requirement", "expected_error"),
+ [
+ ("sync", "==2.7.*", SandboxRestartRequired),
+ ("remove", "==2.7.*", SandboxRestartRequired),
+ ("sync", ">=3.0", None),
+ ("remove", ">=3.0", None),
+ ("sync", "invalid", script_metadata.ScriptMetadataError),
+ ("sync", 42, script_metadata.ScriptMetadataError),
+ ],
+)
+async def test_sync_checks_active_python_before_mutating_environment(
+ tmp_path: Path,
+ requirement: str | int,
+ operation: str,
+ expected_error: type[Exception] | None,
+) -> None:
+ from unittest.mock import AsyncMock, MagicMock
+
+ from marimo._environments.environment import Environment
+
+ source = tmp_path / "notebook.py"
+ active = Environment(
+ python=sys.executable, root=sys.prefix, action="unchanged"
+ )
+
+ adapter = MagicMock()
+ adapter.name = "uv"
+ adapter.ensure_available_async = AsyncMock()
+ adapter.sync_async = AsyncMock(return_value=active)
+ adapter.sync.return_value = active
+ sandbox = NotebookSandbox(
+ str(source), "uv", environment=active, adapter=adapter
+ )
+ manifest = (
+ f"dependencies = []\nrequires-python = {json.dumps(requirement)}\n"
+ )
+ source.write_text(script_metadata.wrap_block(manifest))
+
+ with pytest.raises(expected_error) if expected_error else nullcontext():
+ if operation == "sync":
+ await sandbox.sync_async()
+ else:
+ await asyncio.to_thread(sandbox.remove, "requests")
+
+ sync = adapter.sync_async if operation == "sync" else adapter.sync
+ if expected_error:
+ sync.assert_not_called()
+ else:
+ sync.assert_called_once()
diff --git a/tests/_environments/test_environment.py b/tests/_environments/test_environment.py
index 6815653c7f..84e2f4e146 100644
--- a/tests/_environments/test_environment.py
+++ b/tests/_environments/test_environment.py
@@ -268,14 +268,6 @@ def test_launch_layers_over_the_activated_environment() -> None:
assert plan.start_new_session
-def test_isolated_launcher_plan_starts_a_new_session() -> None:
- isolated = environment.launch_isolated(
- ["-m", "marimo"], requirements=["marimo"], python="3.13"
- )
-
- assert isolated.start_new_session
-
-
@pytest.mark.network
@pytest.mark.skipif(not SUPPORTS_SYNC, reason="uv >= 0.7.21 required")
def test_launch_overlay_chains_without_mutating(
diff --git a/tests/_environments/test_process.py b/tests/_environments/test_process.py
new file mode 100644
index 0000000000..46630b0a2b
--- /dev/null
+++ b/tests/_environments/test_process.py
@@ -0,0 +1,204 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from typing import TYPE_CHECKING
+
+import pytest
+
+from marimo._environments.process import run_command
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+
+async def test_command_captures_output_and_exit_status(tmp_path: Path) -> None:
+ # Fill both pipes beyond their buffers so sequential reads would hang.
+ code = r"""
+import json, os, sys
+print(json.dumps([os.getcwd(), os.environ['SANDBOX_TEST_VALUE']]))
+sys.stdout.write('x' * 131072)
+sys.stdout.flush()
+sys.stderr.write('y' * 131072 + '\nfinished 🎲\n')
+sys.exit(3)
+"""
+ lines: list[str] = []
+ result = await run_command(
+ [sys.executable, "-c", code],
+ cwd=str(tmp_path),
+ env={
+ **os.environ,
+ "PYTHONIOENCODING": "utf-8",
+ "SANDBOX_TEST_VALUE": "value with spaces",
+ },
+ on_stderr=lines.append,
+ timeout=10,
+ )
+ context, stdout = result.stdout.split("\n", 1)
+ expected_cwd = str(tmp_path.resolve()) # noqa: ASYNC240
+ assert json.loads(context) == [expected_cwd, "value with spaces"]
+ assert stdout == "x" * 131072
+ assert result.stderr == "y" * 131072 + "\nfinished 🎲\n"
+ assert "".join(lines) == result.stderr
+ assert result.returncode == 3
+
+
[email protected](os.name == "nt", reason="POSIX process groups")
[email protected]("stop", ["cancel", "timeout"])
+async def test_stopping_command_cleans_up_after_launcher_exits(
+ stop: str,
+) -> None:
+ import psutil
+
+ # The child keeps the capture pipes open after its launcher exits.
+ child_code = """
+import os, signal, sys
+sys.stdin.read()
+print(f'{sys.argv[1]} {os.getpid()}', file=sys.stderr, flush=True)
+signal.pause()
+"""
+ code = f"""
+import os, subprocess, sys
+subprocess.Popen(
+ [sys.executable, '-c', {child_code!r}, str(os.getpid())],
+ stdin=subprocess.PIPE,
+)
+"""
+ ready = asyncio.Event()
+ pids: list[int] = []
+
+ def on_stderr(line: str) -> None:
+ pids.extend(map(int, line.split()))
+ ready.set()
+
+ task = asyncio.create_task(
+ run_command(
+ [sys.executable, "-c", code],
+ on_stderr=on_stderr,
+ timeout=3 if stop == "timeout" else None,
+ )
+ )
+ try:
+ await asyncio.wait_for(ready.wait(), timeout=5)
+ launcher, child = (psutil.Process(pid) for pid in pids)
+ await asyncio.to_thread(launcher.wait, timeout=5)
+ if stop == "cancel":
+ assert not task.done()
+ task.cancel()
+ with pytest.raises(
+ asyncio.CancelledError
+ if stop == "cancel"
+ else asyncio.TimeoutError
+ ):
+ await asyncio.wait_for(asyncio.shield(task), timeout=5)
+ _, alive = await asyncio.to_thread(
+ psutil.wait_procs, [child], timeout=5
+ )
+ assert not alive, "Cancelled command left its child running"
+ finally:
+ for pid in reversed(pids):
+ try:
+ psutil.Process(pid).kill()
+ except psutil.NoSuchProcess:
+ pass
+ task.cancel()
+ await asyncio.gather(task, return_exceptions=True)
+
+
+async def test_repeated_cancellation_waits_for_cleanup_without_blocking(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._utils import subprocess as subprocess_utils
+
+ loop = asyncio.get_running_loop()
+ ready = asyncio.Event()
+ stopping = asyncio.Event()
+ release = threading.Event()
+ kill = subprocess_utils.kill_subprocess
+ processes = []
+
+ def slow_kill(process, *, start_new_session):
+ processes.append(process)
+ loop.call_soon_threadsafe(stopping.set)
+ try:
+ assert release.wait(timeout=10)
+ finally:
+ kill(process, start_new_session=start_new_session)
+
+ monkeypatch.setattr(subprocess_utils, "kill_subprocess", slow_kill)
+ task = asyncio.create_task(
+ run_command(
+ [
+ sys.executable,
+ "-c",
+ "import sys,time; print('ready', file=sys.stderr, flush=True); time.sleep(60)",
+ ],
+ on_stderr=lambda _line: ready.set(),
+ )
+ )
+ try:
+ await asyncio.wait_for(ready.wait(), timeout=5)
+ task.cancel()
+ await asyncio.wait_for(stopping.wait(), timeout=5)
+ task.cancel()
+ await asyncio.sleep(0)
+ assert not task.done()
+ release.set()
+ with pytest.raises(asyncio.CancelledError):
+ await asyncio.wait_for(task, timeout=5)
+ assert processes[0].poll() is not None
+ finally:
+ release.set()
+ task.cancel()
+ await asyncio.gather(task, return_exceptions=True)
+
+
+async def test_cancellation_with_saturated_default_executor() -> None:
+ import psutil
+
+ loop = asyncio.get_running_loop()
+ ready = asyncio.Event()
+ child: psutil.Process | None = None
+
+ def on_stderr(line: str) -> None:
+ nonlocal child
+ child = psutil.Process(int(line))
+ ready.set()
+
+ # One reader per pipe occupies every worker until the child dies.
+ executor = ThreadPoolExecutor(max_workers=2)
+ loop.set_default_executor(executor)
+ task = asyncio.create_task(
+ run_command(
+ [
+ sys.executable,
+ "-c",
+ "import os,sys,time; print(os.getpid(), file=sys.stderr, flush=True); time.sleep(60)",
+ ],
+ on_stderr=on_stderr,
+ )
+ )
+ try:
+ await asyncio.wait_for(ready.wait(), timeout=5)
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await asyncio.wait_for(asyncio.shield(task), timeout=2)
+ assert child is not None
+ assert not child.is_running()
+ finally:
+ if child is not None:
+ try:
+ child.kill()
+ except psutil.NoSuchProcess:
+ pass
+ task.cancel()
+ await asyncio.gather(task, return_exceptions=True)
+ loop.set_default_executor(ThreadPoolExecutor())
+ executor.shutdown()
diff --git a/tests/_environments/test_sandbox_interface.py b/tests/_environments/test_sandbox_interface.py
index 6d09b209cd..35d1ff6432 100644
--- a/tests/_environments/test_sandbox_interface.py
+++ b/tests/_environments/test_sandbox_interface.py
@@ -115,7 +115,7 @@ class FakeBackend:
del python_override, on_output, active_environment
self.sync_targets.append(target.path)
return Environment(
- python=str(self.root / "bin" / "python"),
+ python=sys.executable,
root=str(self.root),
action="updated",
)
@@ -578,7 +578,7 @@ def test_runtime_dependency_cannot_be_removed(tmp_path: Path) -> None:
assert adapter.sync_targets == []
-def test_package_view_hides_runtime_dependency(tmp_path: Path) -> None:
+def test_package_view_includes_runtime_dependency(tmp_path: Path) -> None:
notebook = tmp_path / "notebook.py"
notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
adapter = FakeBackend(tmp_path / "environment")
@@ -607,9 +607,14 @@ def test_package_view_hides_runtime_dependency(tmp_path: Path) -> None:
state = sandbox.packages()
- assert [package.name for package in state.packages] == ["obstore"]
+ assert [(package.name, package.version) for package in state.packages] == [
+ ("obstore", "0.8.2"),
+ ("marimo", "0.24.0"),
+ ]
assert state.tree is not None
- assert [node.name for node in state.tree.dependencies] == []
+ assert [(node.name, node.version) for node in state.tree.dependencies] == [
+ ("marimo", "0.24.0")
+ ]
def test_pixi_launch_layers_the_runtime_overlay_through_uv(
diff --git a/tests/_environments/test_script_metadata.py b/tests/_environments/test_script_metadata.py
index 4166bb7cfd..535677904e 100644
--- a/tests/_environments/test_script_metadata.py
+++ b/tests/_environments/test_script_metadata.py
@@ -392,9 +392,14 @@ pyproject: |
with script_metadata.materialized_for_environment(str(notebook)) as second:
assert second.path == first.path
+ assert list(tmp_path.iterdir()) == [notebook]
-def _enter_carrier(notebook, attempting, entered):
+def _enter_carrier(notebook, attempting, entered, temporary_directory):
+ if temporary_directory is not None:
+ import tempfile
+
+ tempfile.tempdir = temporary_directory
attempting.set()
with script_metadata.materialized_for_environment(notebook):
entered.set()
@@ -415,8 +420,16 @@ def test_stable_carrier_lifetime_is_serialized(
attempting = context.Event()
entered = context.Event()
worker_type = context.Process if separate_process else threading.Thread
+ temporary_directory = tmp_path / "worker-tmp"
+ temporary_directory.mkdir()
worker = worker_type(
- target=_enter_carrier, args=(str(notebook), attempting, entered)
+ target=_enter_carrier,
+ args=(
+ str(notebook),
+ attempting,
+ entered,
+ str(temporary_directory) if separate_process else None,
+ ),
)
with script_metadata.materialized_for_environment(
str(notebook)
@@ -447,35 +460,78 @@ def test_old_active_carriers_are_preserved(tmp_path: Path) -> None:
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")
+ worker = subprocess.Popen(
+ [
+ sys.executable,
+ "-c",
+ (
+ "import sys, time\n"
+ "from marimo._environments import script_metadata\n"
+ "with script_metadata.materialized_for_environment(sys.argv[1]) as target:\n"
+ " print(target.path, flush=True)\n"
+ " time.sleep(60)\n"
+ ),
+ str(notebook),
+ ],
+ stdout=subprocess.PIPE,
+ text=True,
+ )
+ try:
+ assert worker.stdout is not None
+ stranded = Path(worker.stdout.readline().strip())
+ assert stranded.is_file()
+ finally:
+ worker.kill()
+ worker.wait(timeout=5)
+ if worker.stdout is not None:
+ worker.stdout.close()
+ assert stranded.exists()
+ notebook.write_text(
+ '---\npyproject: |\n dependencies = ["requests"]\n---\n'
+ )
with script_metadata.materialized_for_environment(
str(notebook)
) as materialized:
- assert "dependencies = []" in Path(materialized.path).read_text()
+ assert (
+ 'dependencies = ["requests"]'
+ in Path(materialized.path).read_text()
+ )
assert not stranded.exists()
[email protected]("suffix", [".py", ".lock"])
[email protected]("kind", ["carrier", "lock"])
def test_carrier_symlinks_do_not_modify_target(
- tmp_path: Path, suffix: str
+ tmp_path: Path,
+ kind: 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}"
+ link = (
+ tmp_path / ".marimo-v1-notebook.md.py"
+ if kind == "carrier"
+ else script_metadata._notebook_lock_path(str(notebook)).with_suffix(
+ ".carrier.lock"
+ )
+ )
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"
+ try:
+ 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"
+ finally:
+ link.unlink()
@pytest.mark.skipif(
@@ -503,3 +559,90 @@ def test_readonly_notebook_directory_fails_clearly(
pytest.fail("must preserve adjacent path semantics")
finally:
os.chmod(tmp_path, 0o700)
+
+
[email protected]("suffix", [".py", ".md", ".qmd"])
[email protected]("newline", ["\n", "\r\n"])
+def test_replace_whole_manifest_preserves_custom_tables_and_notebook(
+ tmp_path: Path, suffix: str, newline: str
+) -> None:
+ path = tmp_path / f"notebook{suffix}"
+ original = 'dependencies = ["numpy==0.0.0"]\n'
+ replacement = '''# Keep this comment and the user's table order.
+notes = """
+/// example
+"""
+
+[tool.custom]
+label = "my experiment"
+
+[tool.uv.sources]
+numpy = { path = "../numpy", editable = true }
+
+[tool.pixi.dependencies]
+python = ">=3.12"
+'''
+ body = "\n# Notebook content\nprint('unchanged')\n"
+ if suffix == ".py":
+ source = script_metadata.wrap_block(original) + "\n" + body
+ else:
+ source = (
+ "---\ntitle: My notebook\npyproject: |\n"
+ ' dependencies = ["numpy==0.0.0"]\n---\n' + body
+ )
+ path.write_bytes(source.replace("\n", newline).encode())
+ previous = script_metadata.read_manifest(str(path))
+ saved = script_metadata.write_manifest(
+ str(path), replacement, previous=previous
+ )
+ assert saved == replacement
+ assert path.read_bytes().endswith(body.replace("\n", newline).encode())
+ if suffix != ".py":
+ assert "title: My notebook" in path.read_text()
+
+
+def test_manifest_repair_rejects_stale_edits_but_preserves_new_code(
+ tmp_path: Path,
+) -> None:
+ path = tmp_path / "notebook.py"
+ broken = "dependencies = [\n"
+ path.write_text(script_metadata.wrap_block(broken) + "\nprint('old')\n")
+ previous = script_metadata.read_manifest(str(path))
+ path.write_text(path.read_text().replace("print('old')", "print('new')"))
+ script_metadata.write_manifest(
+ str(path), "[tool.custom]\nvalue = 1\n", previous=previous
+ )
+ saved = path.read_text()
+ with pytest.raises(script_metadata.ManifestConflictError):
+ script_metadata.write_manifest(
+ str(path), "dependencies = []\n", previous=previous
+ )
+ with pytest.raises(ValueError):
+ script_metadata.write_manifest(str(path), broken, previous=previous)
+ with pytest.raises(
+ script_metadata.ScriptMetadataError, match="script markers"
+ ):
+ script_metadata.write_manifest(
+ str(path),
+ 'value = """\n///\n"""\n',
+ previous=script_metadata.read_manifest(str(path)),
+ )
+ assert path.read_text() == saved
+ assert saved.endswith("print('new')\n")
+
+
+def test_manifest_replacement_preserves_crlf_notebook_code(
+ tmp_path: Path,
+) -> None:
+ path = tmp_path / "notebook.py"
+ path.write_bytes(
+ b'# /// script\r\n# dependencies = []\r\n# ///\r\nprint("keep")\r\n'
+ )
+ previous = script_metadata.read_manifest(str(path))
+ script_metadata.write_manifest(
+ str(path), "[tool.custom]\nvalue = 1\n", previous=previous
+ )
+ assert (
+ path.read_bytes()
+ == b'# /// script\r\n# [tool.custom]\r\n# value = 1\r\n# ///\r\nprint("keep")\r\n'
+ )
diff --git a/tests/_server/api/endpoints/test_packages.py b/tests/_server/api/endpoints/test_packages.py
index 7a3736df91..23d0ba50be 100644
--- a/tests/_server/api/endpoints/test_packages.py
+++ b/tests/_server/api/endpoints/test_packages.py
@@ -850,14 +850,13 @@ def test_remove_package_with_dev_dependency(
def test_get_package_manager_uses_ipc_venv_python() -> None:
"""Test that _get_package_manager uses venv Python from IPC kernel."""
from marimo._server.api.endpoints.packages import _get_package_manager
+ from marimo._session.managers.ipc import IPCKernelManagerImpl
+ from marimo._session.session import SessionImpl
- # Mock the session with an IPC kernel manager having venv_python set
- mock_kernel_manager = MagicMock()
+ mock_kernel_manager = MagicMock(spec=IPCKernelManagerImpl)
mock_kernel_manager.venv_python = "/custom/venv/python"
- mock_kernel_manager.script_environment = None
-
- mock_session = MagicMock()
+ mock_session = MagicMock(spec=SessionImpl)
mock_session._kernel_manager = mock_kernel_manager
mock_session.notebook_sandbox = None
@@ -876,19 +875,6 @@ def test_get_package_manager_uses_ipc_venv_python() -> None:
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: (
- cls.__name__ == "SessionImpl"
- if hasattr(cls, "__name__") and cls.__name__ == "SessionImpl"
- else (
- cls.__name__ == "IPCKernelManagerImpl"
- if hasattr(cls, "__name__")
- and cls.__name__ == "IPCKernelManagerImpl"
- else isinstance(obj, cls)
- )
- ),
- ),
):
_get_package_manager(mock_request)
@@ -896,49 +882,6 @@ def test_get_package_manager_uses_ipc_venv_python() -> None:
mock_create_pm.assert_called_once_with(
"pip",
python_exe="/custom/venv/python",
- script_path=None,
- sandbox_environment=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.notebook_sandbox = None
- 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: cls.__name__ != "NotebookSandbox",
- ),
- ):
- _get_package_manager(MagicMock())
-
- mock_create_pm.assert_called_once_with(
- "uv",
- python_exe="/env/bin/python",
- script_path="/nb/notebook.py",
- sandbox_environment=mock_kernel_manager.script_environment,
)
@@ -971,9 +914,7 @@ 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, script_path=None, sandbox_environment=None
- )
+ mock_create_pm.assert_called_once_with("uv", python_exe=None)
def test_get_package_manager_no_session() -> None:
@@ -1002,35 +943,122 @@ def test_get_package_manager_no_session() -> None:
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
[email protected]("backend", ["uv", "pixi"])
+def test_repair_manifest_without_a_kernel(
+ client: TestClient, tmp_path, monkeypatch: pytest.MonkeyPatch, backend: str
) -> None:
- from marimo._config.settings import GLOBAL_SETTINGS
- from marimo._server.api.endpoints.packages import _get_package_manager
- from marimo._session.session import SessionImpl
+ from marimo._server.workspace import SingleFileWorkspace
+ from marimo._utils.marimo_path import MarimoPath
- monkeypatch.setattr(GLOBAL_SETTINGS, "SANDBOX_MODE", mode)
- session = MagicMock(spec=SessionImpl)
- session.notebook_sandbox = None
- 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,
- sandbox_environment=None,
+ path = tmp_path / "notebook.py"
+ path.write_text(
+ '# /// script\n# dependencies = ["numpy==0.0.0"]\n# ///\n'
+ "import marimo\napp = marimo.App()\n"
+ )
+ manager = client.app.state.session_manager
+ manager.sandbox = True
+ manager.workspace = SingleFileWorkspace.from_path(MarimoPath(str(path)))
+ monkeypatch.setattr(
+ "marimo._server.api.endpoints.packages.current_backend",
+ lambda: backend,
+ )
+ request = {"fileKey": str(path)}
+ response = client.post(
+ "/api/packages/sandbox", headers=HEADERS, json=request
+ )
+ assert response.status_code == 200
+ assert response.json() == {
+ "backend": backend,
+ "filename": str(path),
+ "manifest": 'dependencies = ["numpy==0.0.0"]\n',
+ }
+ update = {
+ **request,
+ "previous": response.json()["manifest"],
+ "contents": '[tool.custom]\nmessage = "whole manifest"\n',
+ }
+ response = client.post(
+ "/api/packages/manifest", headers=HEADERS, json=update
+ )
+ assert response.status_code == 200
+ assert response.json()["manifest"] == update["contents"]
+ assert path.read_text().endswith("import marimo\napp = marimo.App()\n")
+ response = client.post(
+ "/api/packages/manifest", headers=HEADERS, json=update
+ )
+ assert response.status_code == 409
+ response = client.post("/api/packages/sync", headers=HEADERS, json=request)
+ assert response.json() == {
+ "success": True,
+ "error": None,
+ "restartRequired": False,
+ "reconnect": True,
+ }
+
+
+def test_manifest_access_uses_workspace_permissions(
+ client: TestClient, tmp_path
+) -> None:
+ from marimo._server.workspace import SingleFileWorkspace
+ from marimo._utils.marimo_path import MarimoPath
+
+ allowed = tmp_path / "allowed.py"
+ denied = tmp_path / "denied.py"
+ allowed.write_text("import marimo\napp = marimo.App()\n")
+ denied.write_text("private = True\n")
+ manager = client.app.state.session_manager
+ manager.sandbox = True
+ manager.workspace = SingleFileWorkspace.from_path(MarimoPath(str(allowed)))
+ response = client.post(
+ "/api/packages/manifest",
+ headers=HEADERS,
+ json={
+ "fileKey": str(denied),
+ "contents": "value = 1",
+ "previous": "",
+ },
+ )
+ assert response.status_code == 404
+ assert denied.read_text() == "private = True\n"
+
+
+ ("endpoint", "operation"),
+ [("sandbox", "read_manifest"), ("manifest", "write_manifest")],
+)
+def test_manifest_file_errors_are_reported(
+ client: TestClient,
+ tmp_path,
+ monkeypatch: pytest.MonkeyPatch,
+ endpoint: str,
+ operation: str,
+) -> None:
+ from marimo._server.workspace import SingleFileWorkspace
+ from marimo._utils.marimo_path import MarimoPath
+
+ path = tmp_path / "notebook.py"
+ path.write_text("import marimo\napp = marimo.App()\n")
+ manager = client.app.state.session_manager
+ manager.sandbox = True
+ manager.workspace = SingleFileWorkspace.from_path(MarimoPath(str(path)))
+ monkeypatch.setattr(
+ "marimo._server.api.endpoints.packages.current_backend", lambda: "uv"
+ )
+
+ def denied(*_args: Any, **_kwargs: Any) -> None:
+ raise PermissionError("Permission denied for notebook manifest")
+
+ monkeypatch.setattr(
+ f"marimo._environments.script_metadata.{operation}", denied
+ )
+ response = client.post(
+ f"/api/packages/{endpoint}",
+ headers=HEADERS,
+ json={
+ "fileKey": str(path),
+ "contents": "dependencies = []",
+ "previous": "",
+ },
)
+ assert response.status_code == 400
+ assert "Permission denied for notebook manifest" in response.text
diff --git a/tests/_server/api/endpoints/test_sse.py b/tests/_server/api/endpoints/test_sse.py
index 1c9542c693..4441a7663a 100644
--- a/tests/_server/api/endpoints/test_sse.py
+++ b/tests/_server/api/endpoints/test_sse.py
@@ -3,14 +3,18 @@ from __future__ import annotations
import asyncio
import json
+import sys
import threading
from functools import partial
from typing import TYPE_CHECKING, Any
-from unittest.mock import MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
import pytest
-from marimo._messaging.notification import AlertNotification
+from marimo._messaging.notification import (
+ AlertNotification,
+ StartupProgressNotification,
+)
from marimo._messaging.serde import serialize_kernel_message
from marimo._server.api.endpoints.ws.sse_handler import SSESessionHandler
from marimo._server.api.endpoints.ws.ws_connection_validator import (
@@ -30,6 +34,8 @@ from tests._server.api.endpoints.ws_helpers import (
from tests._server.mocks import get_session_manager
if TYPE_CHECKING:
+ from pathlib import Path
+
from starlette.applications import Starlette
from starlette.testclient import TestClient
from typing_extensions import Self
@@ -290,6 +296,80 @@ async def test_sse_kernel_startup_error(client: TestClient) -> None:
)
[email protected]("outcome", ["ready", "error", "disconnect"])
+async def test_sandbox_progress_during_preparation(
+ client: TestClient,
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+ outcome: str,
+) -> None:
+ from marimo._session.managers import ipc
+
+ release = asyncio.Event()
+ cleaned_up = asyncio.Event()
+
+ async def check_environment(_python: str) -> bool:
+ try:
+ await release.wait()
+ return True
+ finally:
+ cleaned_up.set()
+
+ # A configured interpreter that disappears before launch lets the test
+ # observe both phases and a real launch failure without spawning a kernel.
+ monkeypatch.setattr(
+ ipc,
+ "get_configured_venv_python",
+ lambda *_args, **_kwargs: (
+ sys.executable
+ if outcome == "ready"
+ else str(tmp_path / "missing-python")
+ ),
+ )
+ monkeypatch.setattr(ipc, "has_marimo_installed", check_environment)
+ manager = get_session_manager(client)
+ manager.sandbox = True
+
+ async with _connect(client) as connection:
+ event = await connection.next_event()
+ assert json.loads(event["data"]) == {
+ "op": "startup-progress",
+ "data": {
+ "op": "startup-progress",
+ "phase": "preparing-environment",
+ },
+ }
+ assert not manager.sessions
+ if outcome == "disconnect":
+ connection.disconnect()
+ await asyncio.wait_for(cleaned_up.wait(), timeout=5)
+ else:
+ release.set()
+ event = await connection.next_event()
+ assert json.loads(event["data"]) == {
+ "op": "startup-progress",
+ "data": {
+ "op": "startup-progress",
+ "phase": "starting-kernel",
+ },
+ }
+ event = await connection.next_event()
+ message = json.loads(event["data"])
+ if outcome == "ready":
+ assert_kernel_ready_response(message)
+ else:
+ assert message["op"] == "kernel-startup-error"
+ assert (
+ "Failed to start kernel subprocess"
+ in message["data"]["error"]
+ )
+ await _expect_close(
+ connection, 1011, "MARIMO_KERNEL_STARTUP_ERROR"
+ )
+ if outcome != "ready":
+ assert not manager.sessions
+
+
async def test_sse_kiosk_without_session(client: TestClient) -> None:
async with _connect(client, f"{SSE_QUERY}&kiosk=true") as connection:
await _expect_close(connection, 1000, "MARIMO_NO_SESSION")
@@ -364,8 +444,18 @@ def _make_handler(
# Bypass SessionConnector; unit tests drive the handler directly
session = MagicMock()
session.room.main_consumer = handler
- handler._connect_session = MagicMock( # type: ignore[method-assign]
- return_value=(session, ConnectionType.NEW)
+ session.ttl_seconds = 120
+ session.disconnect_consumer.side_effect = lambda consumer: (
+ consumer.on_detach()
+ )
+ handler.manager.get_session.return_value = session
+
+ async def connect(_request: Any) -> tuple[Any, ConnectionType]:
+ handler.on_attach(session, MagicMock())
+ return session, ConnectionType.NEW
+
+ handler._connect_session = AsyncMock( # type: ignore[method-assign]
+ side_effect=connect
)
return handler
@@ -416,6 +506,27 @@ async def test_stream_does_not_connect_until_iterated() -> None:
handler._connect_session.assert_not_called()
+async def test_disconnect_during_startup_progress_detaches_session() -> None:
+ request = MagicMock()
+ request._receive = _never_receive()
+ handler = _make_handler(request)
+ session = handler.manager.get_session.return_value
+ handler.notify(
+ serialize_kernel_message(
+ StartupProgressNotification(phase="starting-kernel")
+ )
+ )
+
+ stream = handler.stream()
+ assert "startup-progress" in await anext(stream)
+ await asyncio.sleep(0) # Complete attachment while the yield is suspended.
+ await stream.aclose()
+
+ session.disconnect_consumer.assert_called_once_with(handler)
+ assert handler.connection_state() == ConnectionState.CLOSED
+ assert not handler._is_transport_connected()
+
+
async def test_stream_flushes_pending_messages_before_close() -> None:
"""Messages enqueued before a server close are sent, then the close."""
request = MagicMock()
diff --git a/tests/_server/api/endpoints/test_ws.py b/tests/_server/api/endpoints/test_ws.py
index 97b1f45d02..1cecb2aa4b 100644
--- a/tests/_server/api/endpoints/test_ws.py
+++ b/tests/_server/api/endpoints/test_ws.py
@@ -5,17 +5,23 @@ import asyncio
from contextlib import contextmanager
from pathlib import Path
from typing import TYPE_CHECKING, Any
-from unittest.mock import MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from starlette.websockets import WebSocketDisconnect
from marimo._config.config import ExperimentalConfig
from marimo._config.manager import UserConfigManager
-from marimo._messaging.notification import KernelReadyNotification
+from marimo._messaging.notification import (
+ KernelReadyNotification,
+ StartupProgressNotification,
+)
+from marimo._messaging.serde import serialize_kernel_message
from marimo._server.api.endpoints.ws.ws_connection_validator import (
ConnectionParams,
)
+from marimo._server.api.endpoints.ws.ws_session_connector import ConnectionType
+from marimo._server.api.endpoints.ws_endpoint import WebSocketHandler
from marimo._server.codes import WebSocketCodes
from marimo._server.session_manager import SessionManager
from marimo._session.model import ConnectionState, SessionMode
@@ -51,6 +57,63 @@ def test_ws(client: TestClient) -> None:
assert_kernel_ready_response(data)
[email protected]("failure", ["disconnect", "cancel"])
+async def test_failed_startup_progress_delivery_detaches_session(
+ failure: str,
+) -> None:
+ websocket = MagicMock()
+ websocket.accept = AsyncMock()
+ websocket.close = AsyncMock()
+ sending = asyncio.Event()
+
+ async def send(_text: str) -> None:
+ sending.set()
+ await asyncio.sleep(0)
+ if failure == "disconnect":
+ raise WebSocketDisconnect(1006)
+ await asyncio.Event().wait()
+
+ websocket.send_text = send
+ manager = MagicMock()
+ session = manager.get_session.return_value
+ session.ttl_seconds = 120
+ session.disconnect_consumer.side_effect = lambda consumer: (
+ consumer.on_detach()
+ )
+ handler = WebSocketHandler(
+ websocket=websocket,
+ manager=manager,
+ params=ConnectionParams(
+ session_id=SessionId("s1"),
+ file_key="test.py",
+ kiosk=False,
+ auto_instantiate=False,
+ rtc_enabled=False,
+ ),
+ mode=SessionMode.RUN,
+ )
+
+ async def connect(_connection: Any) -> tuple[Any, ConnectionType]:
+ handler.on_attach(session, MagicMock())
+ handler.status = ConnectionState.OPEN
+ handler.notify(
+ serialize_kernel_message(
+ StartupProgressNotification(phase="starting-kernel")
+ )
+ )
+ return session, ConnectionType.NEW
+
+ with patch.object(handler, "_connect_session", side_effect=connect):
+ task = asyncio.create_task(handler.start())
+ await asyncio.wait_for(sending.wait(), timeout=5)
+ if failure == "cancel":
+ task.cancel()
+ await asyncio.wait_for(task, timeout=5)
+
+ session.disconnect_consumer.assert_called_once_with(handler)
+ assert handler.connection_state() == ConnectionState.CLOSED
+
+
def test_without_session(client: TestClient) -> None:
with pytest.raises(WebSocketDisconnect) as exc_info:
with client.websocket_connect("/ws?access_token=fake-token"):
@@ -577,68 +640,6 @@ async def test_ttl_close_does_not_kill_session_owned_by_new_consumer(
ws_a.__exit__(None, None, None)
-def test_ttl_close_skips_when_session_has_active_consumer() -> None:
- """Unit test: _close() must not kill session when another consumer has taken over.
-
- Patches call_later to fire the TTL callback immediately after setup,
- simulating the bug scenario where Consumer A's timer fires while
- Consumer B owns the session.
- """
- from marimo._server.api.endpoints.ws_endpoint import WebSocketHandler
-
- captured_callback: list[tuple[float, Callable[[], None]]] = []
-
- def capture_call_later(
- delay: float, callback: Callable[[], None]
- ) -> MagicMock:
- captured_callback.append((delay, callback))
- return MagicMock()
-
- # Session with active consumer (Consumer B has taken over)
- session_with_consumer = MagicMock()
- session_with_consumer.connection_state.return_value = ConnectionState.OPEN
- session_with_consumer.ttl_seconds = 0.1
-
- manager = MagicMock(spec=SessionManager)
- manager.ttl_seconds = 120
- manager.get_session.return_value = session_with_consumer
- manager.close_session = MagicMock()
-
- params = ConnectionParams(
- session_id="123",
- file_key="test.py",
- kiosk=False,
- auto_instantiate=False,
- rtc_enabled=False,
- )
-
- handler = WebSocketHandler(
- websocket=MagicMock(),
- manager=manager,
- params=params,
- mode=SessionMode.RUN,
- )
- handler.status = ConnectionState.CLOSED # Consumer A disconnected
-
- cleanup_fn = MagicMock()
-
- with patch(
- "marimo._server.api.endpoints.ws_endpoint.asyncio.get_running_loop"
- ) as mock_loop:
- mock_loop.return_value.call_later = capture_call_later
- handler._on_disconnect(Exception("disconnect"), cleanup_fn)
-
- assert len(captured_callback) == 1
- _, ttl_callback = captured_callback[0]
-
- # Fire the TTL callback (simulates timer firing)
- ttl_callback()
-
- # With the fix: session has active consumer, so close_session must NOT be called
- manager.close_session.assert_not_called()
- cleanup_fn.assert_not_called()
-
-
@pytest.mark.parametrize(
("mode", "manager_ttl"),
[
@@ -685,67 +686,6 @@ async def test_session_ttl_expiration(
task.join()
-def test_run_mode_ttl_close_with_manager_ttl_none() -> None:
- """Unit test: RUN mode must schedule TTL cleanup even when
- manager.ttl_seconds is None (the default for create_asgi_app).
-
- This was a regression from #7863 where the condition only checked
- manager.ttl_seconds, causing ASGI sessions to never be cleaned up.
- """
- from marimo._server.api.endpoints.ws_endpoint import WebSocketHandler
-
- captured_callback: list[tuple[float, Callable[[], None]]] = []
-
- def capture_call_later(
- delay: float, callback: Callable[[], None]
- ) -> MagicMock:
- captured_callback.append((delay, callback))
- return MagicMock()
-
- # Session exists but no active consumer (disconnected)
- session = MagicMock()
- session.connection_state.return_value = ConnectionState.ORPHANED
- session.ttl_seconds = 120
-
- manager = MagicMock(spec=SessionManager)
- manager.ttl_seconds = None # ASGI default
- manager.get_session.return_value = session
-
- params = ConnectionParams(
- session_id="123",
- file_key="test.py",
- kiosk=False,
- auto_instantiate=False,
- rtc_enabled=False,
- )
-
- handler = WebSocketHandler(
- websocket=MagicMock(),
- manager=manager,
- params=params,
- mode=SessionMode.RUN,
- )
- handler.status = ConnectionState.CLOSED
-
- cleanup_fn = MagicMock()
-
- with patch(
- "marimo._server.api.endpoints.ws_endpoint.asyncio.get_running_loop"
- ) as mock_loop:
- mock_loop.return_value.call_later = capture_call_later
- handler._on_disconnect(Exception("disconnect"), cleanup_fn)
-
- # Must schedule TTL cleanup even though manager.ttl_seconds is None
- assert len(captured_callback) == 1
- delay, ttl_callback = captured_callback[0]
- assert delay == 120 # session.ttl_seconds
-
- # Fire the callback — session has no active consumer, so it should close
- ttl_callback()
- manager.close_session.assert_called_once_with("123")
- cleanup_fn.assert_called_once()
-
-
async def test_edit_mode_without_session_ttl_no_delayed_cleanup(
client: TestClient,
) -> None:
@@ -870,3 +810,67 @@ async def test_websocket_message_queue_delivery(client: TestClient) -> None:
messages = flush_messages(websocket, at_least=1)
assert len(messages) >= 1
+
+
+def test_disconnect_cancels_pending_startup(
+ client: TestClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ import asyncio
+ import threading
+
+ from marimo._session.session import SessionImpl
+
+ started = threading.Event()
+ cleaned_up = threading.Event()
+
+ async def create(**_kwargs: object) -> None:
+ started.set()
+ try:
+ await asyncio.Event().wait()
+ finally:
+ cleaned_up.set()
+
+ monkeypatch.setattr(SessionImpl, "create", create)
+ with client.websocket_connect(WS_URL) as websocket:
+ assert started.wait(timeout=5)
+ websocket.close()
+ # Stay in the client context: its teardown cancels the server task,
+ # which would hide a failure to notice the actual disconnect.
+ assert cleaned_up.wait(timeout=5)
+ assert not get_session_manager(client).sessions
+
+
+def test_sandbox_progress_before_preparation_failure(
+ client: TestClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from marimo._environments.errors import EnvironmentManagerError
+ from marimo._environments.sandbox import NotebookSandbox
+
+ release = asyncio.Event()
+
+ async def prepare(*_args: object, **_kwargs: object) -> None:
+ try:
+ await asyncio.wait_for(release.wait(), timeout=5)
+ except asyncio.TimeoutError:
+ pass
+ raise EnvironmentManagerError("Could not resolve dependencies")
+
+ monkeypatch.setattr(NotebookSandbox, "launch_async", prepare)
+ get_session_manager(client).sandbox = True
+
+ with client.websocket_connect(WS_URL) as websocket:
+ assert websocket.receive_json() == {
+ "op": "startup-progress",
+ "data": {
+ "op": "startup-progress",
+ "phase": "preparing-environment",
+ },
+ }
+ assert not get_session_manager(client).sessions
+ websocket.portal.call(release.set)
+ error = websocket.receive_json()
+ assert error["op"] == "kernel-startup-error"
+ assert "Could not resolve dependencies" in error["data"]["error"]
+ with pytest.raises(WebSocketDisconnect) as closed:
+ websocket.receive_json()
+ assert closed.value.reason == "MARIMO_KERNEL_STARTUP_ERROR"
diff --git a/tests/_server/api/test_middleware.py b/tests/_server/api/test_middleware.py
index 71bbe983e4..addd7bfc47 100644
--- a/tests/_server/api/test_middleware.py
+++ b/tests/_server/api/test_middleware.py
@@ -1,6 +1,7 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+import asyncio
import io
import json
import socket
@@ -241,7 +242,7 @@ def read_app() -> Starlette:
yield app
try:
- join_kernel_thread_tasks(session_manager)
+ asyncio.run(join_kernel_thread_tasks(session_manager))
finally:
sys.modules["__main__"] = main
@@ -279,7 +280,7 @@ def no_auth_read_app() -> Starlette:
yield app
try:
- join_kernel_thread_tasks(session_manager)
+ asyncio.run(join_kernel_thread_tasks(session_manager))
finally:
sys.modules["__main__"] = main
diff --git a/tests/_server/conftest.py b/tests/_server/conftest.py
index 1307636a0a..ae7c186a3e 100644
--- a/tests/_server/conftest.py
+++ b/tests/_server/conftest.py
@@ -1,6 +1,7 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+import asyncio
import sys
import threading
from pathlib import Path
@@ -41,20 +42,20 @@ def get_kernel_tasks(
return kernel_tasks
-def join_kernel_thread_tasks(session_manager: SessionManager) -> None:
+async def join_kernel_thread_tasks(session_manager: SessionManager) -> None:
# Kernels started in run mode run in their own threads; if these kernels
# execute code, they may patch and restore their own main modules.
# To ensure that this fixture correctly restores the original saved
# main module, we wait for threads to finish before restoring the module.
kernel_tasks = get_kernel_tasks(session_manager)
- session_manager.shutdown()
+ await session_manager.shutdown()
for task in kernel_tasks:
# At least some tests are flaky with processes (edit tasks)
# not joining for a long time; orphaned edit tasks
# won't affect other tests, but they are somewhat concerning
# ...
if isinstance(task, threading.Thread):
- task.join()
+ await asyncio.to_thread(task.join)
@pytest.fixture(scope="session", autouse=True)
@@ -117,7 +118,7 @@ def client(user_config_manager: UserConfigManager) -> Iterator[TestClient]:
yield client
try:
- join_kernel_thread_tasks(client.app.state.session_manager)
+ asyncio.run(join_kernel_thread_tasks(client.app.state.session_manager))
finally:
sys.modules["__main__"] = main
diff --git a/tests/_server/test_session_manager.py b/tests/_server/test_session_manager.py
index ce7f34b0ff..f0ad254e9c 100644
--- a/tests/_server/test_session_manager.py
+++ b/tests/_server/test_session_manager.py
@@ -1,5 +1,6 @@
from __future__ import annotations
+import asyncio
import sys
from textwrap import dedent
from typing import TYPE_CHECKING
@@ -96,7 +97,7 @@ async def test_start_lsp_server(session_manager: SessionManager) -> None:
async def test_create_session_new(
session_manager: SessionManager, mock_session_consumer: SessionConsumer
) -> None:
- session = session_manager.create_session(
+ session = await session_manager.create_session(
session_id,
mock_session_consumer,
query_params={},
@@ -114,7 +115,7 @@ async def test_create_session_absolute_url(
mock_session_consumer: SessionConsumer,
temp_marimo_file: str,
) -> None:
- session = session_manager.create_session(
+ session = await session_manager.create_session(
session_id,
mock_session_consumer,
query_params={},
@@ -225,13 +226,13 @@ def test_close_all_sessions(
assert mock_session.close.call_count == 2
-def test_shutdown(
+async def test_shutdown(
session_manager: SessionManager, mock_session: Session
) -> None:
add_session(session_manager, SessionId("session1"), mock_session)
add_session(session_manager, SessionId("session2"), mock_session)
- session_manager.shutdown()
+ await session_manager.shutdown()
session_manager.lsp_server.stop.assert_called_once()
assert len(session_manager.sessions) == 0
assert mock_session.close.call_count == 2
@@ -254,7 +255,7 @@ async def test_create_session_with_script_config_overrides(
)
)
- session = session_manager.create_session(
+ session = await session_manager.create_session(
session_id,
mock_session_consumer,
query_params={},
@@ -461,7 +462,7 @@ async def test_recents_touch_called_on_session_create(
session_manager.recents.touch = mock_touch # type: ignore
# Create a session
- session = session_manager.create_session(
+ session = await session_manager.create_session(
SessionId("recents_test_session"),
mock_session_consumer,
query_params={},
@@ -479,3 +480,165 @@ async def test_recents_touch_called_on_session_create(
assert str(tmp_file) in touched_files[0]
session.close()
+
+
+async def test_concurrent_startup_survives_disconnected_waiter(
+ session_manager: SessionManager,
+ mock_session: Session,
+ mock_session_consumer: SessionConsumer,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._session.session import SessionImpl
+
+ entered = asyncio.Event()
+ release = asyncio.Event()
+ launches = 0
+ mock_session.app_file_manager = AppFileManager(filename=None)
+
+ async def create(**_kwargs: object) -> Session:
+ nonlocal launches
+ launches += 1
+ entered.set()
+ await release.wait()
+ return mock_session
+
+ monkeypatch.setattr(SessionImpl, "create", create)
+
+ async def connect() -> Session:
+ return await session_manager.create_session(
+ session_id, mock_session_consumer, {}, NEW_FILE, False
+ )
+
+ first = asyncio.create_task(connect())
+ try:
+ await asyncio.wait_for(entered.wait(), 5)
+ assert not session_manager.sessions
+ second_entered = asyncio.Event()
+
+ async def reconnect() -> Session:
+ second_entered.set()
+ return await connect()
+
+ second = asyncio.create_task(reconnect())
+ await asyncio.wait_for(second_entered.wait(), 5)
+ first.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await first
+ release.set()
+ assert await asyncio.wait_for(second, 5) is mock_session
+ assert launches == 1
+ finally:
+ await session_manager.shutdown()
+
+
+async def test_shutdown_waits_for_pending_startup_cleanup(
+ session_manager: SessionManager,
+ mock_session_consumer: SessionConsumer,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._session.managers.ipc import KernelStartupError
+ from marimo._session.session import SessionImpl
+
+ entered = asyncio.Event()
+ cleaning_up = asyncio.Event()
+ release = asyncio.Event()
+
+ async def create(**_kwargs: object) -> Session:
+ entered.set()
+ try:
+ await asyncio.Event().wait()
+ finally:
+ cleaning_up.set()
+ await release.wait()
+ raise AssertionError("unreachable")
+
+ monkeypatch.setattr(SessionImpl, "create", create)
+ startup = asyncio.create_task(
+ session_manager.create_session(
+ session_id, mock_session_consumer, {}, NEW_FILE, False
+ )
+ )
+ await asyncio.wait_for(entered.wait(), 5)
+ shutdown = asyncio.create_task(session_manager.shutdown())
+ try:
+ await asyncio.wait_for(cleaning_up.wait(), 5)
+ assert not shutdown.done()
+ assert not session_manager.sessions
+ with pytest.raises(KernelStartupError, match="shut down"):
+ await session_manager.create_session(
+ session_id, mock_session_consumer, {}, NEW_FILE, False
+ )
+ finally:
+ release.set()
+ await asyncio.wait_for(shutdown, 5)
+ with pytest.raises(asyncio.CancelledError):
+ await startup
+ assert not session_manager.sessions
+
+
+async def test_connections_share_starting_notebook(
+ session_manager: SessionManager,
+ mock_session: Session,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from starlette.requests import HTTPConnection
+
+ from marimo._server.api.endpoints.ws.ws_connection_validator import (
+ ConnectionParams,
+ )
+ from marimo._server.api.endpoints.ws.ws_session_connector import (
+ ConnectionType,
+ SessionConnector,
+ )
+ from marimo._session.session import SessionImpl
+
+ entered = asyncio.Event()
+ release = asyncio.Event()
+ mock_session.initialization_id = NEW_FILE
+ mock_session.room = MagicMock()
+ mock_session.room.get_consumer.return_value = None
+ mock_session.app_file_manager = AppFileManager(filename=None)
+ launches = 0
+
+ async def create(**_kwargs: object) -> Session:
+ nonlocal launches
+ launches += 1
+ entered.set()
+ await release.wait()
+ return mock_session
+
+ monkeypatch.setattr(SessionImpl, "create", create)
+
+ def connector(sid: str) -> SessionConnector:
+ return SessionConnector(
+ manager=session_manager,
+ handler=MagicMock(),
+ params=ConnectionParams(
+ session_id=SessionId(sid),
+ file_key=NEW_FILE,
+ kiosk=False,
+ auto_instantiate=False,
+ rtc_enabled=True,
+ ),
+ connection=HTTPConnection({"type": "http", "query_string": b""}),
+ )
+
+ first = asyncio.create_task(connector("first").connect())
+ try:
+ await asyncio.wait_for(entered.wait(), 5)
+ second = asyncio.create_task(connector("second").connect())
+ # Scheduling the second connection before releasing preparation
+ # exercises its decision against an initially empty repository.
+ release.set()
+ assert await asyncio.wait_for(first, 5) == (
+ mock_session,
+ ConnectionType.NEW,
+ )
+ assert await asyncio.wait_for(second, 5) == (
+ mock_session,
+ ConnectionType.RTC_EXISTING,
+ )
+ assert launches == 1
+ finally:
+ release.set()
+ await session_manager.shutdown()
diff --git a/tests/_server/test_sessions.py b/tests/_server/test_sessions.py
index d58c568b0b..9e0bed695d 100644
--- a/tests/_server/test_sessions.py
+++ b/tests/_server/test_sessions.py
@@ -15,7 +15,7 @@ from pathlib import Path
from tempfile import NamedTemporaryFile
from textwrap import dedent
from typing import Any
-from unittest.mock import MagicMock, patch
+from unittest.mock import MagicMock
import pytest
@@ -24,7 +24,10 @@ from marimo._ast.app_config import _AppConfig
from marimo._config.manager import (
get_default_config_manager,
)
+from marimo._messaging.errors import MarimoInterruptionError
from marimo._messaging.notification import (
+ CellNotification,
+ CompletedRunNotification,
NotebookDocumentTransactionNotification,
NotificationMessage,
)
@@ -59,40 +62,6 @@ from marimo._utils.marimo_path import MarimoPath
initialize_asyncio()
[email protected]("inherited_mode", ["single", None])
-def test_single_sandbox_edit_uses_notebook_bound_kernel(
- inherited_mode: str | None, monkeypatch: pytest.MonkeyPatch
-) -> None:
- from marimo._cli.sandbox import SandboxMode
- from marimo._config.settings import GLOBAL_SETTINGS
- from marimo._session.managers.ipc import IPCKernelManagerImpl
-
- monkeypatch.setattr(GLOBAL_SETTINGS, "SANDBOX_MODE", inherited_mode)
- # Inspect the factory without starting a process or attaching consumers.
- with patch.object(
- SessionImpl, "__init__", return_value=None
- ) as initialize:
- SessionImpl.create(
- initialization_id="sandbox-restart",
- session_consumer=MagicMock(),
- mode=SessionMode.EDIT,
- app_metadata=app_metadata,
- app_file_manager=AppFileManager.from_app(InternalApp(App())),
- config_manager=get_default_config_manager(current_path=None),
- virtual_file_storage="shared_memory",
- redirect_console_to_browser=False,
- ttl_seconds=None,
- auto_instantiate=False,
- sandbox_mode=None if inherited_mode else SandboxMode.SINGLE,
- )
- manager = initialize.call_args.kwargs["kernel_manager"]
- try:
- assert isinstance(manager, IPCKernelManagerImpl)
- assert manager.sandbox_mode is SandboxMode.SINGLE
- finally:
- manager.queue_manager.close_queues()
-
-
app_metadata = AppMetadata(
query_params={"some_param": "some_value"},
filename="test.py",
@@ -140,7 +109,7 @@ def test_queue_manager() -> None:
assert isinstance(queue_manager_thread.input_queue, queue.Queue)
-def test_kernel_manager_run_mode() -> None:
+async def test_kernel_manager_run_mode() -> None:
# Mock objects and data for testing
queue_manager = QueueManagerImpl(use_multiprocessing=False)
mode = SessionMode.RUN
@@ -156,7 +125,7 @@ def test_kernel_manager_run_mode() -> None:
redirect_console_to_browser=False,
)
- kernel_manager.start_kernel()
+ await kernel_manager.start_kernel()
# Assert startup
assert kernel_manager.kernel_task is not None
@@ -173,7 +142,7 @@ def test_kernel_manager_run_mode() -> None:
assert queue_manager.control_queue.empty()
-def test_kernel_manager_edit_mode() -> None:
+async def test_kernel_manager_edit_mode() -> None:
# Mock objects and data for testing
queue_manager = QueueManagerImpl(use_multiprocessing=True)
mode = SessionMode.EDIT
@@ -189,7 +158,7 @@ def test_kernel_manager_edit_mode() -> None:
redirect_console_to_browser=False,
)
- kernel_manager.start_kernel()
+ await kernel_manager.start_kernel()
# Assert startup
assert kernel_manager.kernel_task is not None
@@ -206,113 +175,74 @@ def test_kernel_manager_edit_mode() -> None:
queue_manager.control_queue.join_thread() # type: ignore
-def test_kernel_manager_interrupt(tmp_path: Path) -> None:
+async def test_kernel_manager_interrupt() -> None:
queue_manager = QueueManagerImpl(use_multiprocessing=True)
- mode = SessionMode.EDIT
-
kernel_manager = KernelManagerImpl(
queue_manager=queue_manager,
- mode=mode,
+ mode=SessionMode.EDIT,
configs={},
app_metadata=app_metadata,
config_manager=get_default_config_manager(current_path=None),
virtual_file_storage="shared_memory",
redirect_console_to_browser=False,
)
+ await kernel_manager.start_kernel()
- # Assert startup
- kernel_manager.start_kernel()
- assert kernel_manager.kernel_task is not None
- assert kernel_manager._read_conn is not None
- assert kernel_manager.is_alive()
- if sys.platform == "win32":
- import random
- import string
-
- # Having trouble persisting the write to a temp file on Windows
- file = Path(
- "".join(random.choice(string.ascii_uppercase) for _ in range(10))
- + ".txt"
- )
- else:
- file = tmp_path / "output.txt"
-
- Path(file).write_text("-1")
+ def interrupt_running_cell() -> bool:
+ interrupted = False
+ while True:
+ message = deserialize_kernel_message(
+ kernel_manager.kernel_connection.recv()
+ )
+ if isinstance(message, CompletedRunNotification):
+ return interrupted
+ if (
+ not isinstance(message, CellNotification)
+ or message.output is None
+ ):
+ continue
+ output = message.output.data
+ if isinstance(output, str) and "ready-to-interrupt" in output:
+ kernel_manager.interrupt_kernel()
+ elif isinstance(output, list):
+ interrupted |= any(
+ isinstance(error, MarimoInterruptionError)
+ for error in output
+ )
- queue_manager.control_queue.put(
- CreateNotebookCommand(
- execution_requests=(
- ExecuteCellCommand(
- cell_id="1",
- code=inspect.cleandoc(
- f"""
- import time
- with open("{file}", 'w') as f:
- f.write('0')
- time.sleep(2)
- with open("{file}", 'w') as f:
- f.write('1')
- """
+ try:
+ queue_manager.put_control_request(
+ CreateNotebookCommand(
+ execution_requests=(
+ ExecuteCellCommand(
+ cell_id="1",
+ code=inspect.cleandoc("""
+ import marimo as mo
+ mo.output.append("ready-to-interrupt")
+ while True:
+ pass
+ """),
),
),
- ),
- cell_ids=("1",),
- set_ui_element_value_request=UpdateUIElementCommand(
- object_ids=[], values=[]
- ),
- auto_run=True,
+ cell_ids=("1",),
+ set_ui_element_value_request=UpdateUIElementCommand(
+ object_ids=[], values=[]
+ ),
+ auto_run=True,
+ )
+ )
+ assert await asyncio.wait_for(
+ asyncio.to_thread(interrupt_running_cell), timeout=5
)
- )
-
- timeout = 5
- # Wait for the file to be written to 0
- start_time = time.time()
- while time.time() < start_time + timeout / 2:
- time.sleep(0.1)
- if file.read_text() == "0":
- break
- kernel_manager.interrupt_kernel()
-
- try:
- assert file.read_text() == "0"
- # if kernel failed to interrupt, f will read as "1"
- time.sleep(1.5)
- assert file.read_text() == "0"
finally:
- if sys.platform == "win32":
- os.remove(file)
-
- # Wait for queues to be empty with timeout
- # This makes the test more resilient to timing issues in CI
- start_time = time.time()
- timeout = 5 # 5-second timeout for queues to be empty
-
- # Give some time for queues to be processed first
- time.sleep(0.5)
-
- while time.time() - start_time < timeout:
- if (
- queue_manager.input_queue.empty()
- and queue_manager.control_queue.empty()
- ):
- break
- time.sleep(0.2) # slightly longer interval
-
- # Now check if queues are empty
- assert queue_manager.input_queue.empty()
- assert queue_manager.control_queue.empty()
-
- # Assert shutdown
kernel_manager.close_kernel()
- kernel_manager.kernel_task.join(timeout=5)
- assert not kernel_manager.is_alive()
@pytest.mark.skipif(
sys.platform == "win32",
reason="interrupts don't reach subprocesses on Windows",
)
-def test_kernel_manager_interrupt_reaches_subprocesses(
+async def test_kernel_manager_interrupt_reaches_subprocesses(
tmp_path: Path,
) -> None:
queue_manager = QueueManagerImpl(use_multiprocessing=True)
@@ -326,7 +256,7 @@ def test_kernel_manager_interrupt_reaches_subprocesses(
redirect_console_to_browser=False,
)
- kernel_manager.start_kernel()
+ await kernel_manager.start_kernel()
assert kernel_manager.kernel_task is not None
assert kernel_manager.is_alive()
@@ -371,7 +301,7 @@ def test_kernel_manager_interrupt_reaches_subprocesses(
int(pid) for pid in pid_file.read_text().split()
)
break
- time.sleep(0.1)
+ await asyncio.sleep(0.1)
def terminated(pid: int) -> bool:
# An interrupted child of the kernel may linger as a zombie until
@@ -389,8 +319,8 @@ def test_kernel_manager_interrupt_reaches_subprocesses(
kernel_manager.interrupt_kernel()
deadline = time.time() + 10
- while time.time() < deadline and not terminated(child_pid):
- time.sleep(0.1)
+ while time.time() < deadline and not terminated(child_pid): # noqa: ASYNC110
+ await asyncio.sleep(0.1)
# The interrupt reaches subprocesses in the kernel's process group
assert terminated(child_pid)
# ... but spares subprocesses that detached into their own session
@@ -424,6 +354,8 @@ async def test_session() -> None:
redirect_console_to_browser=False,
)
+ await kernel_manager.start_kernel()
+
# Instantiate a Session
session = SessionImpl(
initialization_id=session_id,
@@ -455,7 +387,7 @@ async def test_session() -> None:
assert session.connection_state() == ConnectionState.CLOSED
-def test_session_disconnect_reconnect() -> None:
+async def test_session_disconnect_reconnect() -> None:
session_consumer: Any = MagicMock()
session_consumer.connection_state.return_value = ConnectionState.OPEN
queue_manager = QueueManagerImpl(use_multiprocessing=False)
@@ -469,6 +401,8 @@ def test_session_disconnect_reconnect() -> None:
redirect_console_to_browser=False,
)
+ await kernel_manager.start_kernel()
+
# Instantiate a Session
session = SessionImpl(
initialization_id=session_id,
@@ -512,7 +446,7 @@ def test_session_disconnect_reconnect() -> None:
assert session.connection_state() == ConnectionState.CLOSED
-def test_session_with_kiosk_consumers() -> None:
+async def test_session_with_kiosk_consumers() -> None:
session_consumer: Any = MagicMock()
session_consumer.connection_state.return_value = ConnectionState.OPEN
queue_manager = QueueManagerImpl(use_multiprocessing=False)
@@ -526,6 +460,8 @@ def test_session_with_kiosk_consumers() -> None:
redirect_console_to_browser=False,
)
+ await kernel_manager.start_kernel()
+
# Instantiate a Session
session = SessionImpl(
initialization_id=session_id,
@@ -620,7 +556,7 @@ def __():
session_consumer = MockSessionConsumer()
# Create a session
- session_manager.create_session(
+ await session_manager.create_session(
session_id=session_id,
session_consumer=session_consumer,
query_params={},
@@ -657,7 +593,7 @@ def __():
# Create another session for the same file
session_consumer2 = MockSessionConsumer()
- session_manager.create_session(
+ await session_manager.create_session(
session_id=SessionId("test2"),
session_consumer=session_consumer2,
query_params={},
@@ -728,10 +664,10 @@ def __():
assert len(update_ops2) >= 1
finally:
# Cleanup
- session_manager.shutdown()
+ await session_manager.shutdown()
-def test_watch_mode_does_not_override_config(tmp_path: Path) -> None:
+async def test_watch_mode_does_not_override_config(tmp_path: Path) -> None:
"""Test that watch mode does not override config settings."""
# Create a temporary file
tmp_file = tmp_path / "test_watch_mode_config_override.py"
@@ -780,8 +716,8 @@ def test_watch_mode_does_not_override_config(tmp_path: Path) -> None:
finally:
# Cleanup
- session_manager.shutdown()
- session_manager_no_watch.shutdown()
+ await session_manager.shutdown()
+ await session_manager_no_watch.shutdown()
@pytest.mark.flaky(reruns=3)
@@ -834,7 +770,7 @@ async def test_watch_mode_with_watcher_on_save_autorun(tmp_path: Path) -> None:
session_consumer = MockSessionConsumer()
# Create a session
- session = session_manager.create_session(
+ session = await session_manager.create_session(
session_id=session_id,
session_consumer=session_consumer,
query_params={},
@@ -891,7 +827,7 @@ async def test_watch_mode_with_watcher_on_save_autorun(tmp_path: Path) -> None:
finally:
# Cleanup
if session_manager:
- session_manager.shutdown()
+ await session_manager.shutdown()
async def test_watch_mode_with_watcher_on_save_lazy(tmp_path: Path) -> None:
@@ -943,7 +879,7 @@ async def test_watch_mode_with_watcher_on_save_lazy(tmp_path: Path) -> None:
session_consumer = MockSessionConsumer()
# Create a session
- session = session_manager.create_session(
+ session = await session_manager.create_session(
session_id=session_id,
session_consumer=session_consumer,
query_params={},
@@ -989,7 +925,7 @@ async def test_watch_mode_with_watcher_on_save_lazy(tmp_path: Path) -> None:
finally:
# Cleanup
if session_manager:
- session_manager.shutdown()
+ await session_manager.shutdown()
async def test_session_manager_file_rename() -> None:
@@ -1039,7 +975,7 @@ def __():
)
# Create a session
- session_manager.create_session(
+ await session_manager.create_session(
session_id=session_id,
session_consumer=session_consumer,
query_params={},
@@ -1104,14 +1040,14 @@ def __():
finally:
# Cleanup
- session_manager.shutdown()
+ await session_manager.shutdown()
if new_path.exists():
os.remove(new_path)
if tmp_path1.exists(): # noqa: ASYNC240
os.remove(tmp_path1)
-def test_session_with_script_config_overrides(
+async def test_session_with_script_config_overrides(
tmp_path: Path,
) -> None:
session_consumer = MagicMock()
@@ -1134,7 +1070,7 @@ def test_session_with_script_config_overrides(
app_file_manager = AppFileManager(filename=str(tmp_file))
# Create session with the file that has script config
- session = SessionImpl.create(
+ session = await SessionImpl.create(
initialization_id="test_id",
session_consumer=session_consumer,
mode=SessionMode.RUN,
@@ -1172,7 +1108,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:
session_consumer = MagicMock()
session_consumer.connection_state.return_value = ConnectionState.OPEN
- def create_session(
+ async def create_session(
mode: SessionMode,
auto_instantiate: bool,
*,
@@ -1187,7 +1123,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:
}
}
)
- return SessionImpl.create(
+ return await SessionImpl.create(
initialization_id="test_session",
session_consumer=session_consumer,
mode=mode,
@@ -1212,7 +1148,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:
return extension[0]
# Test 1: EDIT mode with auto_instantiate=False -> caching enabled/read-write
- session_edit = create_session(SessionMode.EDIT, False)
+ session_edit = await create_session(SessionMode.EDIT, False)
# Find the CachingExtension
caching_extension_edit = find_caching_extension(session_edit)
@@ -1220,7 +1156,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:
assert caching_extension_edit.mode is CacheMode.READ_WRITE
# Test 2: EDIT mode with auto_instantiate=True -> caching disabled
- session_edit_disabled = create_session(SessionMode.EDIT, True)
+ session_edit_disabled = await create_session(SessionMode.EDIT, True)
caching_extension_edit_disabled = find_caching_extension(
session_edit_disabled
)
@@ -1228,7 +1164,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:
assert caching_extension_edit_disabled.mode is CacheMode.READ_WRITE
# Test 3: RUN mode with config disabled -> caching disabled/read-only
- session_run_disabled = create_session(
+ session_run_disabled = await create_session(
SessionMode.RUN, True, serve_cached_sessions_in_apps=False
)
@@ -1240,7 +1176,7 @@ async def test_caching_extension_respects_mode_and_config() -> None:
assert caching_extension_run_disabled.mode is CacheMode.READ
# Test 4: RUN mode with config enabled -> caching enabled/read-only
- session_run_enabled = create_session(
+ session_run_enabled = await create_session(
SessionMode.RUN, True, serve_cached_sessions_in_apps=True
)
caching_extension_run_enabled = find_caching_extension(session_run_enabled)
diff --git a/tests/_session/app_host/test_app_host.py b/tests/_session/app_host/test_app_host.py
index cb49897076..138100be22 100644
--- a/tests/_session/app_host/test_app_host.py
+++ b/tests/_session/app_host/test_app_host.py
@@ -333,7 +333,7 @@ class TestAppHostQueueManager:
@pytest.mark.requires("zmq")
class TestAppHostMultipleClients:
- def test_create_session_uses_per_client_session_id(self) -> None:
+ async def test_create_session_uses_per_client_session_id(self) -> None:
"""SessionImpl.create() must pass the per-client session_id — not
the shared initialization_id (file_key) — to the AppHost managers.
@@ -361,7 +361,7 @@ class TestAppHostMultipleClients:
"AppHostKernelManager.start_kernel"
):
for sid in ("session-1", "session-2"):
- SessionImpl.create(
+ await SessionImpl.create(
initialization_id=file_key,
session_consumer=Mock(),
mode=SessionMode.RUN,
diff --git a/tests/_session/managers/test_app_host_kernel_manager.py b/tests/_session/managers/test_app_host_kernel_manager.py
index d2cdb7d276..ad78946c86 100644
--- a/tests/_session/managers/test_app_host_kernel_manager.py
+++ b/tests/_session/managers/test_app_host_kernel_manager.py
@@ -98,32 +98,7 @@ class TestAppHostLike:
@pytest.mark.requires("zmq")
class TestAppHostKernelManagerStartAndClose:
- def test_start_kernel_sets_kernel_task(self) -> None:
- app_host = Mock()
- app_host.create_kernel.return_value = KernelCreatedResponse(
- session_id="s1", success=True
- )
-
- config_manager = Mock()
- config_manager.get_config.return_value = {}
-
- mgr = AppHostKernelManager(
- app_host=app_host,
- session_id="s1",
- queue_manager=Mock(),
- mode=SessionMode.RUN,
- configs={},
- app_metadata=Mock(),
- config_manager=config_manager,
- redirect_console_to_browser=True,
- )
-
- mgr.start_kernel()
-
- app_host.create_kernel.assert_called_once()
- assert isinstance(mgr.kernel_task, _AppHostLike)
-
- def test_start_kernel_failure_raises(self) -> None:
+ async def test_start_kernel_failure_raises(self) -> None:
app_host = Mock()
app_host.create_kernel.return_value = KernelCreatedResponse(
session_id="s1", success=False, error="boom"
@@ -144,7 +119,7 @@ class TestAppHostKernelManagerStartAndClose:
)
with pytest.raises(RuntimeError, match="boom"):
- mgr.start_kernel()
+ await mgr.start_kernel()
assert mgr.kernel_task is None
diff --git a/tests/_session/managers/test_ipc.py b/tests/_session/managers/test_ipc.py
index 4cc43cbd75..75fb7ec678 100644
--- a/tests/_session/managers/test_ipc.py
+++ b/tests/_session/managers/test_ipc.py
@@ -1,10 +1,13 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+import asyncio
import os
+import subprocess
+import sys
import time
from pathlib import Path
-from unittest.mock import MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock
import pytest
@@ -303,49 +306,6 @@ def _make_manager(filename: str | None = None) -> object:
)
[email protected]("saved", [False, True])
-def test_single_launch_preserves_manifest_binding_and_precedence(
- saved: bool, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-) -> None:
- from marimo._cli.sandbox import SandboxMode
- from marimo._environments.sandbox import MANIFEST_SOURCE, NotebookSandbox
- from marimo._session.managers import ipc
-
- temporary_manifest = tmp_path / "temporary.py"
- temporary_manifest.write_text(
- '# /// script\n# dependencies = ["six"]\n# ///\n'
- )
- saved_manifest = tmp_path / "saved.py"
- saved_manifest.write_text(temporary_manifest.read_text())
- monkeypatch.setenv(MANIFEST_SOURCE, str(temporary_manifest))
- manager = _make_manager(str(saved_manifest) if saved else None)
- manager.sandbox_mode = SandboxMode.SINGLE
- configured_venv = MagicMock(
- side_effect=AssertionError("SINGLE must retain its sandbox precedence")
- )
- monkeypatch.setattr(ipc, "get_configured_venv_python", configured_venv)
-
- # Stop at the launch boundary: the selected source must be the original
- # unnamed manifest or the newly saved path, never a fresh empty manifest.
- class LaunchObserved(Exception):
- pass
-
- def observe(
- sandbox: NotebookSandbox, *_args: object, **_kwargs: object
- ) -> None:
- assert sandbox.source == str(
- saved_manifest if saved else temporary_manifest
- )
- assert "six" in Path(sandbox.source).read_text()
- raise LaunchObserved
-
- monkeypatch.setattr(NotebookSandbox, "launch", observe)
- with pytest.raises(LaunchObserved):
- manager.start_kernel()
- configured_venv.assert_not_called()
- assert temporary_manifest.exists()
-
-
class TestProfilePath:
def test_none_without_profile_dir(
self, monkeypatch: pytest.MonkeyPatch
@@ -415,107 +375,6 @@ class TestCloseKernel:
)
-class TestFailedStartCleanup:
- def test_kills_process_and_closes_sandbox(self) -> None:
- from marimo._session.managers import ipc
-
- manager = _make_manager("nb.py")
- manager._process = MagicMock()
- manager._process.poll.return_value = None
- manager._notebook_sandbox = MagicMock()
- sandbox = manager._notebook_sandbox
-
- with patch.object(ipc, "try_kill_process_and_group") as kill:
- manager._cleanup_failed_start()
-
- kill.assert_called_once()
- sandbox.close.assert_called_once()
- assert manager.notebook_sandbox is None
-
-
-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
@@ -566,3 +425,153 @@ def test_launch_kernel_handshake_reports_identity() -> None:
pid, exe = _parse_kernel_info(lines[1])
assert pid is not None
assert exe is not None
+
+
+ ("outcome", "configured"),
+ [
+ ("exit", False),
+ ("timeout", False),
+ ("cancel", False),
+ ("cancel", True),
+ ("output", False),
+ ],
+)
+async def test_startup_owns_kernel_process_and_pipes(
+ outcome: str,
+ configured: bool,
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+) -> None:
+ from marimo._ast.app_config import _AppConfig
+ from marimo._config.manager import get_default_config_manager
+ from marimo._environments.environment import ProcessPlan
+ from marimo._ipc import QueueManager
+ from marimo._runtime.commands import AppMetadata
+ from marimo._session.managers.ipc import (
+ IPCKernelManagerImpl,
+ IPCQueueManagerImpl,
+ KernelStartupError,
+ )
+ from marimo._session.model import SessionMode
+
+ started = asyncio.Event()
+
+ async def ready(
+ reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+ ) -> None:
+ await reader.read(1)
+ started.set()
+ writer.close()
+ await writer.wait_closed()
+
+ server = await asyncio.start_server(ready, "127.0.0.1", 0)
+ port = server.sockets[0].getsockname()[1]
+ code = (
+ "import socket, sys, time, signal; sys.stdin.read(); "
+ "signal.signal(signal.SIGTERM, signal.SIG_IGN); "
+ f"socket.create_connection(('127.0.0.1', {port})).send(b'x'); "
+ + ("" if configured else "print('KERNEL_READY', flush=True); ")
+ + (
+ # The launcher exits, but a descendant still holds its pipes.
+ "import subprocess; "
+ "subprocess.Popen([sys.executable, '-c', 'import time; time.sleep(60)']); "
+ "sys.exit(3)"
+ if outcome == "exit"
+ else "time.sleep(60)"
+ )
+ )
+ output_ready = tmp_path / "output-ready"
+ if outcome == "output":
+ child_code = "import sys; sys.stdout.write('x' * 131072)"
+ code = (
+ "import socket, sys, os, subprocess, time\n"
+ "from pathlib import Path\n"
+ "sys.stdin.read()\n"
+ f"socket.create_connection(('127.0.0.1', {port})).send(b'x')\n"
+ "print('KERNEL_READY', flush=True)\n"
+ "print(f'KERNEL_INFO {os.getpid()} {sys.executable}', flush=True)\n"
+ f"while not Path({str(output_ready)!r}).exists(): time.sleep(0.01)\n"
+ # Inherit the kernel's stdout and fill more than the pipe buffer.
+ f"result = subprocess.run([sys.executable, '-c', {child_code!r}], stdout=sys.stdout)\n"
+ "sys.exit(result.returncode)\n"
+ )
+ sandbox = MagicMock()
+ sandbox.launch_async = AsyncMock(
+ return_value=ProcessPlan(
+ argv=(sys.executable, "-c", code),
+ env=os.environ.copy(),
+ start_new_session=True,
+ )
+ )
+ monkeypatch.setattr(
+ "marimo._environments.sandbox.NotebookSandbox", lambda *_: sandbox
+ )
+ if configured:
+ monkeypatch.setattr(
+ "marimo._session.managers.ipc.get_configured_venv_python",
+ lambda *_args, **_kwargs: sys.executable,
+ )
+ monkeypatch.setattr(
+ "marimo._session.managers.ipc.has_marimo_installed",
+ AsyncMock(return_value=True),
+ )
+ popen = subprocess.Popen
+ # Windows cleanup also uses Popen for taskkill; only replace the kernel.
+ monkeypatch.setattr(
+ "marimo._session.managers.ipc.subprocess.Popen",
+ lambda cmd, **kwargs: popen(
+ [sys.executable, "-c", code]
+ if cmd == [sys.executable, "-m", "marimo._ipc.launch_kernel"]
+ else cmd,
+ **kwargs,
+ ),
+ )
+ monkeypatch.setenv(
+ "MARIMO_KERNEL_STARTUP_TIMEOUT", "1" if outcome == "timeout" else "30"
+ )
+ queues, connection_info = QueueManager.create()
+ manager = IPCKernelManagerImpl(
+ queue_manager=IPCQueueManagerImpl.from_ipc(queues),
+ connection_info=connection_info,
+ mode=SessionMode.EDIT,
+ configs={},
+ app_metadata=AppMetadata(
+ query_params={},
+ filename=None,
+ cli_args={},
+ argv=None,
+ app_config=_AppConfig(),
+ ),
+ config_manager=get_default_config_manager(current_path=None),
+ )
+ startup = asyncio.create_task(manager.start_kernel())
+ try:
+ await asyncio.wait_for(started.wait(), 5)
+ if outcome == "output":
+ await asyncio.wait_for(startup, 5)
+ output_ready.touch() # noqa: ASYNC240
+ assert manager.kernel_task is not None
+ await asyncio.to_thread(manager.kernel_task.join, 5)
+ assert manager.kernel_task.exitcode == 0
+ elif outcome == "cancel":
+ startup.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await asyncio.wait_for(startup, 5)
+ else:
+ message = (
+ "exit code 3" if outcome == "exit" else "did not become ready"
+ )
+ with pytest.raises(KernelStartupError, match=message):
+ await asyncio.wait_for(startup, 5)
+ assert not manager.is_alive()
+ if outcome != "output":
+ assert manager.notebook_sandbox is None
+ finally:
+ startup.cancel()
+ await asyncio.gather(startup, return_exceptions=True)
+ await manager._cleanup_failed_start()
+ manager.queue_manager.close_queues()
+ server.close()
+ await server.wait_closed()
diff --git a/tests/_session/notebook/test_app_file_manager.py b/tests/_session/notebook/test_app_file_manager.py
index d86323603a..a4faa647fd 100644
--- a/tests/_session/notebook/test_app_file_manager.py
+++ b/tests/_session/notebook/test_app_file_manager.py
@@ -2,6 +2,8 @@
from __future__ import annotations
import os
+import threading
+from concurrent.futures import ThreadPoolExecutor, wait
from typing import TYPE_CHECKING
import pytest
@@ -88,3 +90,105 @@ def test_new_notebook_returns_unbacked_manager() -> None:
def test_new_notebook_advances_document_version() -> None:
fm = new_notebook()
assert fm.app.cell_manager.document.version > 0
+
+
[email protected]("suffix", [".py", ".md"])
[email protected]("first_writer", ["manifest", "cells"])
+def test_manifest_and_cell_saves_preserve_each_other(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ suffix: str,
+ first_writer: str,
+) -> None:
+ from marimo._environments import script_metadata
+ from marimo._server.models.models import SaveNotebookRequest
+ from marimo._session.notebook.serializer import get_notebook_serializer
+
+ path = tmp_path / f"notebook{suffix}"
+ serializer = get_notebook_serializer(path)
+ notebook = get_notebook_serializer(tmp_path / "notebook.py").deserialize(
+ script_metadata.dumps({"dependencies": []}) + "\n" + _NOTEBOOK_SOURCE
+ )
+ path.write_text(serializer.serialize(notebook))
+ manager = load_notebook(path)
+ previous = script_metadata.read_manifest(str(path))
+ read = threading.Event()
+ release = threading.Event()
+ second_started = threading.Event()
+
+ def pause_after_read(value):
+ read.set()
+ assert release.wait(timeout=5)
+ return value
+
+ if first_writer == "manifest":
+ wrap_block = script_metadata.wrap_block
+ monkeypatch.setattr(
+ script_metadata,
+ "wrap_block",
+ lambda contents: pause_after_read(wrap_block(contents)),
+ )
+ else:
+ serializer_type = type(serializer)
+ extract_header = serializer_type.extract_header
+ monkeypatch.setattr(
+ serializer_type,
+ "extract_header",
+ lambda self, path: pause_after_read(extract_header(self, path)),
+ )
+
+ def save_manifest():
+ return script_metadata.write_manifest(
+ str(path), 'dependencies = ["requests"]\n', previous=previous
+ )
+
+ def save_cells():
+ return manager.save(
+ SaveNotebookRequest(
+ cell_ids=list(manager.app.cell_manager.cell_ids()),
+ codes=["x = 2"],
+ names=["__"],
+ configs=[{}],
+ filename=str(path),
+ layout=None,
+ persist=True,
+ )
+ )
+
+ first, second = (
+ (save_manifest, save_cells)
+ if first_writer == "manifest"
+ else (save_cells, save_manifest)
+ )
+
+ def second_save():
+ second_started.set()
+ return second()
+
+ # An in-flight environment operation can retain its carrier while saves
+ # proceed; it must not own the notebook's read-modify-write lock.
+ with (
+ script_metadata.materialized_for_environment(str(path)),
+ ThreadPoolExecutor(max_workers=2) as executor,
+ ):
+ first_task = executor.submit(first)
+ try:
+ assert read.wait(timeout=5)
+ second_task = executor.submit(second_save)
+ assert second_started.wait(timeout=5)
+ # Give the second writer a chance to finish if saves don't
+ # serialize; the final contents must preserve both edits either way.
+ wait([second_task], timeout=0.1)
+ finally:
+ release.set()
+ first_task.result(timeout=5)
+ second_task.result(timeout=5)
+
+ assert (
+ script_metadata.read_manifest(str(path))
+ == 'dependencies = ["requests"]\n'
+ )
+ saved = load_notebook(path)
+ assert [cell.code for cell in saved.app.cell_manager.cell_data()] == [
+ "x = 2"
+ ]
diff --git a/tests/_session/test_venv.py b/tests/_session/test_venv.py
index f8adf717f6..d1dd00469b 100644
--- a/tests/_session/test_venv.py
+++ b/tests/_session/test_venv.py
@@ -187,7 +187,7 @@ def test_get_kernel_pythonpath_deduplicates(
assert paths.count(os.path.normpath("/shared/site-packages")) == 1
-def test_has_marimo_installed_returns_true_when_imports_succeed(
+async def test_has_marimo_installed_returns_true_when_imports_succeed(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Test returns True when marimo and deps can be imported."""
@@ -195,7 +195,7 @@ def test_has_marimo_installed_returns_true_when_imports_succeed(
from marimo._version import __version__
- def mock_run(
+ async def mock_run(
*args: Any, **_kwargs: Any
) -> subprocess.CompletedProcess[str]:
return subprocess.CompletedProcess(
@@ -205,17 +205,17 @@ def test_has_marimo_installed_returns_true_when_imports_succeed(
stderr="",
)
- monkeypatch.setattr(subprocess, "run", mock_run)
- assert has_marimo_installed("/fake/python") is True
+ monkeypatch.setattr("marimo._session._venv.run_command", mock_run)
+ assert await has_marimo_installed("/fake/python") is True
-def test_has_marimo_installed_returns_false_when_import_fails(
+async def test_has_marimo_installed_returns_false_when_import_fails(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Test returns False when imports fail."""
import subprocess
- def mock_run(
+ async def mock_run(
*args: Any, **_kwargs: Any
) -> subprocess.CompletedProcess[str]:
return subprocess.CompletedProcess(
@@ -225,17 +225,17 @@ def test_has_marimo_installed_returns_false_when_import_fails(
stderr="ModuleNotFoundError: No module named 'marimo'",
)
- monkeypatch.setattr(subprocess, "run", mock_run)
- assert has_marimo_installed("/fake/python") is False
+ monkeypatch.setattr("marimo._session._venv.run_command", mock_run)
+ assert await has_marimo_installed("/fake/python") is False
-def test_has_marimo_installed_returns_true_on_version_mismatch(
+async def test_has_marimo_installed_returns_true_on_version_mismatch(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Test returns True even when venv has different marimo version."""
import subprocess
- def mock_run(
+ async def mock_run(
*args: Any, **_kwargs: Any
) -> subprocess.CompletedProcess[str]:
return subprocess.CompletedProcess(
@@ -245,12 +245,12 @@ def test_has_marimo_installed_returns_true_on_version_mismatch(
stderr="",
)
- monkeypatch.setattr(subprocess, "run", mock_run)
+ monkeypatch.setattr("marimo._session._venv.run_command", mock_run)
# Should return True even with version mismatch (warning is logged)
- assert has_marimo_installed("/fake/python") is True
+ assert await has_marimo_installed("/fake/python") is True
-def test_check_python_version_compatibility_returns_true_when_match(
+async def test_check_python_version_compatibility_returns_true_when_match(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Test returns True when Python versions match."""
@@ -258,7 +258,7 @@ def test_check_python_version_compatibility_returns_true_when_match(
current_version = f"{sys.version_info.major}.{sys.version_info.minor}"
- def mock_run(
+ async def mock_run(
*args: Any, **_kwargs: Any
) -> subprocess.CompletedProcess[str]:
return subprocess.CompletedProcess(
@@ -268,17 +268,17 @@ def test_check_python_version_compatibility_returns_true_when_match(
stderr="",
)
- monkeypatch.setattr(subprocess, "run", mock_run)
- assert check_python_version_compatibility("/fake/python") is True
+ monkeypatch.setattr("marimo._session._venv.run_command", mock_run)
+ assert await check_python_version_compatibility("/fake/python") is True
-def test_check_python_version_compatibility_returns_false_when_mismatch(
+async def test_check_python_version_compatibility_returns_false_when_mismatch(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Test returns False when Python versions differ."""
import subprocess
- def mock_run(
+ async def mock_run(
*args: Any, **_kwargs: Any
) -> subprocess.CompletedProcess[str]:
return subprocess.CompletedProcess(
@@ -288,5 +288,5 @@ def test_check_python_version_compatibility_returns_false_when_mismatch(
stderr="",
)
- monkeypatch.setattr(subprocess, "run", mock_run)
- assert check_python_version_compatibility("/fake/python") is False
+ monkeypatch.setattr("marimo._session._venv.run_command", mock_run)
+ assert await check_python_version_compatibility("/fake/python") is False
diff --git a/tests/_utils/test_inline_script_metadata.py b/tests/_utils/test_inline_script_metadata.py
index 1ee786d8b6..622c637060 100644
--- a/tests/_utils/test_inline_script_metadata.py
+++ b/tests/_utils/test_inline_script_metadata.py
@@ -738,3 +738,23 @@ def test_pin_for_wasm_falls_back_to_installed_on_fetch_failure(
out = pin_pep723_dependencies_for_wasm(_WASM_SRC, _wasm_path(tmp_path))
# Fall-through path pins to whatever's installed.
assert "numpy==1.99.0" in out
+
+
+ "contents",
+ [
+ '# A comment\ndependencies = ["numpy"]\n',
+ '# /// script-example\ndependencies = ["numpy"]\n',
+ '# /// script\n# dependencies = ["numpy"]\n# ///',
+ ],
+)
+def test_markdown_manifest_accepts_comments_and_wrapped_metadata(
+ contents: str,
+) -> None:
+ from marimo._environments import script_metadata
+ from marimo._utils.inline_script_metadata import (
+ get_headers_from_frontmatter,
+ )
+
+ header = get_headers_from_frontmatter({"pyproject": contents})["pyproject"]
+ assert script_metadata.loads(header) == {"dependencies": ["numpy"]}