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.

Own sandbox environments by notebook (#10728)

Trevor Manz1793fe560831
diff --git a/docs/guides/package_management/inlining_dependencies.md b/docs/guides/package_management/inlining_dependencies.md
index f57b5d015d..8f7955680d 100644
--- a/docs/guides/package_management/inlining_dependencies.md
+++ b/docs/guides/package_management/inlining_dependencies.md
@@ -51,10 +51,49 @@ uv run notebook.py
!!! note "Requires uv"
- Sandboxed notebooks require the uv package manager
+ The default `--sandbox` backend requires the uv package manager
([installation
instructions](https://docs.astral.sh/uv/getting-started/installation/)).
+## Pixi sandboxes
+
+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.
+
+```bash
+marimo edit --sandbox=pixi notebook.py
+```
+
+Pixi sandboxes resolve conda dependencies (declared under `[tool.pixi]`
+tables in the inline metadata) alongside PyPI dependencies, and require
+only pixi — uv is fetched through `pixi exec` when needed. A pixi
+notebook also runs standalone with `pixi run --script notebook.py`.
+
+```python
+# /// script
+# dependencies = ["marimo", "polars"]
+#
+# [tool.pixi.workspace]
+# channels = ["conda-forge"]
+#
+# [tool.pixi.dependencies]
+# gdal = "*"
+# ///
+```
+
+!!! warning "Pixi limitations"
+
+ - Pixi activation scripts and activation environment variables are not
+ applied when marimo launches the notebook sandbox.
+ - `marimo export html-wasm --execute` runs notebooks under
+ [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.
+
!!! tip "Solving the notebook reproducibility crisis"
marimo's support for package sandboxing is only possible because marimo
@@ -276,5 +315,3 @@ pyproject: |
- altair==<version>
---
```
-
-
diff --git a/frontend/src/__mocks__/requests.ts b/frontend/src/__mocks__/requests.ts
index 49fa93f9ac..af55930bc3 100644
--- a/frontend/src/__mocks__/requests.ts
+++ b/frontend/src/__mocks__/requests.ts
@@ -136,8 +136,13 @@ export const MockRequestClient = {
updateCellOutputs: vi.fn().mockResolvedValue({}),
addPackage: vi.fn().mockResolvedValue({}),
removePackage: vi.fn().mockResolvedValue({}),
- getPackageList: vi.fn().mockResolvedValue({ packages: [] }),
- getDependencyTree: vi.fn().mockResolvedValue({}),
+ getPackageList: vi.fn().mockResolvedValue({
+ packages: [],
+ }),
+ getDependencyTree: vi.fn().mockResolvedValue({
+ tree: null,
+ context: { kind: "package-manager", name: "pip" },
+ }),
listSecretKeys: vi.fn().mockResolvedValue({ keys: [] }),
writeSecret: vi.fn().mockResolvedValue({}),
invokeAiTool: vi.fn().mockResolvedValue({}),
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
new file mode 100644
index 0000000000..c6f81cb6c9
--- /dev/null
+++ b/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx
@@ -0,0 +1,143 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { fireEvent, render, screen } from "@testing-library/react";
+import { Provider } from "jotai";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MockRequestClient } from "@/__mocks__/requests";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import { requestClientAtom } from "@/core/network/requests";
+import type {
+ DependencyTreeNode,
+ DependencyTreeResponse,
+} from "@/core/network/types";
+import { store } from "@/core/state/jotai";
+import PackagesPanel from "../packages-panel";
+
+const { openSettings } = vi.hoisted(() => ({
+ openSettings: vi.fn(),
+}));
+
+vi.mock("@/components/app-config/state", () => ({
+ useOpenSettingsToTab: () => ({ handleClick: openSettings }),
+}));
+
+const emptyTree: DependencyTreeNode = {
+ name: "<root>",
+ version: null,
+ tags: [],
+ dependencies: [],
+};
+
+const populatedTree: DependencyTreeNode = {
+ ...emptyTree,
+ dependencies: [
+ {
+ name: "polars",
+ version: "1.44.1",
+ tags: [],
+ dependencies: [
+ {
+ name: "numpy",
+ version: "2.5.2",
+ tags: [{ kind: "dedupe", value: "true" }],
+ dependencies: [],
+ },
+ ],
+ },
+ ],
+};
+
+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 }),
+ }),
+ );
+
+ return {
+ getPackageList,
+ ...render(
+ <Provider store={store}>
+ <TooltipProvider>
+ <PackagesPanel />
+ </TooltipProvider>
+ </Provider>,
+ ),
+ };
+}
+
+describe("PackagesPanel", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it.each(["pixi", "uv"] as const)(
+ "shows the effective %s sandbox backend as a fixed context",
+ async (backend) => {
+ const { getPackageList } = renderPanel({ kind: "sandbox", backend });
+
+ expect(
+ await screen.findByPlaceholderText(
+ `Add packages to ${backend} sandbox...`,
+ ),
+ ).toBeInTheDocument();
+ expect(screen.getByText(`${backend} sandbox`)).toBeInTheDocument();
+ expect(
+ screen.queryByRole("button", { name: "Change package manager" }),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByRole("button", { name: "List" }),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByRole("button", { name: "Tree" }),
+ ).not.toBeInTheDocument();
+ expect(getPackageList).not.toHaveBeenCalled();
+ },
+ );
+
+ it("explains the filtered empty state for a Pixi sandbox", async () => {
+ renderPanel({ kind: "sandbox", backend: "pixi" });
+
+ expect(await screen.findByText("No PyPI dependencies")).toBeInTheDocument();
+ expect(
+ screen.getByText("Conda dependencies are not shown in this panel."),
+ ).toBeInTheDocument();
+ });
+
+ it("labels a dependency whose subtree was already displayed", async () => {
+ renderPanel({ kind: "sandbox", backend: "pixi" }, populatedTree);
+
+ fireEvent.click(await screen.findByRole("treeitem", { name: /polars/ }));
+
+ expect(screen.getByText("already in tree")).toBeInTheDocument();
+ expect(screen.queryByText("cycle")).not.toBeInTheDocument();
+ });
+
+ it("keeps the configured package manager changeable outside a sandbox", async () => {
+ const { getPackageList } = renderPanel({
+ kind: "package-manager",
+ name: "pip",
+ });
+
+ expect(
+ await screen.findByPlaceholderText("Install packages with pip..."),
+ ).toBeInTheDocument();
+ const changeManager = screen.getByRole("button", {
+ name: "Change package manager",
+ });
+
+ fireEvent.click(changeManager);
+
+ expect(openSettings).toHaveBeenCalledWith("packageManagementAndData");
+ expect(screen.getByText("environment")).toBeInTheDocument();
+ expect(screen.getByRole("button", { name: "List" })).toBeInTheDocument();
+ expect(screen.getByRole("button", { name: "Tree" })).toBeInTheDocument();
+ expect(getPackageList).toHaveBeenCalledOnce();
+ });
+});
diff --git a/frontend/src/components/editor/chrome/panels/packages-panel.tsx b/frontend/src/components/editor/chrome/panels/packages-panel.tsx
index b7ffbdb860..9f3b03e9ff 100644
--- a/frontend/src/components/editor/chrome/panels/packages-panel.tsx
+++ b/frontend/src/components/editor/chrome/panels/packages-panel.tsx
@@ -22,9 +22,13 @@ 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 type { DependencyTreeNode } from "@/core/network/types";
+import type {
+ DependencyTreeNode,
+ DependencyTreeResponse,
+} from "@/core/network/types";
import { stripPackageManagerPrefix } from "@/core/packages/package-input-utils";
import {
+ showPackageRestartToast,
showRemovePackageToast,
showUpgradePackageToast,
} from "@/core/packages/toast-components";
@@ -39,6 +43,7 @@ import { PanelEmptyState } from "./empty-state";
import { PACKAGES_INPUT_ID, packagesToInstallAtom } from "./packages-utils";
type ViewMode = "tree" | "list";
+type PackageInstallationContext = DependencyTreeResponse["context"];
const PackageActionButton: React.FC<{
onClick: () => void;
@@ -77,12 +82,22 @@ const PackagesPanel: React.FC = () => {
refetch,
isPending,
} = useAsyncData(async () => {
- const [listPackagesResponse, dependencyTreeResponse] = await Promise.all([
- getPackageList(),
- getDependencyTree(),
- ]);
+ // 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]);
@@ -97,48 +112,66 @@ const PackagesPanel: React.FC = () => {
}
const isTreeSupported = dependencies.tree != null;
- const viewMode = resolveViewMode(userViewMode, isTreeSupported);
const name = dependencies.tree?.name;
const version = dependencies?.tree?.version;
- const isSandbox = name === "<root>"; // name is the project name otherwise
+ const sandboxBackend =
+ dependencies.context.kind === "sandbox"
+ ? dependencies.context.backend
+ : null;
+ const isSandbox = sandboxBackend !== null;
+ 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;
return (
<div className="flex-1 flex flex-col overflow-hidden">
- <InstallPackageForm packageManager={packageManager} onSuccess={refetch} />
- {isTreeSupported && (
+ <InstallPackageForm context={dependencies.context} onSuccess={refetch} />
+ {(isTreeSupported || isSandbox) && (
<div className="flex items-center justify-between px-2 py-1 border-b">
- <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>
+ {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 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={isSandbox ? "sandbox" : "project"}
+ title={scopeTitle}
>
- {isSandbox ? "sandbox" : "project"}
+ {scopeLabel}
</div>
{name && !isSandbox && (
<span className="text-xs text-muted-foreground">
@@ -155,6 +188,7 @@ const PackagesPanel: React.FC = () => {
<DependencyTree
tree={dependencies.tree}
error={error}
+ sandboxBackend={sandboxBackend}
onSuccess={refetch}
/>
)}
@@ -165,11 +199,13 @@ const PackagesPanel: React.FC = () => {
export default PackagesPanel;
const InstallPackageForm: React.FC<{
- packageManager: string;
+ context: PackageInstallationContext;
onSuccess: () => void;
-}> = ({ onSuccess, packageManager }) => {
+}> = ({ onSuccess, context }) => {
const [input, setInput] = React.useState("");
const { handleClick: openSettings } = useOpenSettingsToTab();
+ const isSandbox = context.kind === "sandbox";
+ const packageManager = isSandbox ? context.backend : context.name;
// Get the packages to install from the atom
const packagesToInstall = useAtomValue(packagesToInstallAtom);
@@ -201,7 +237,11 @@ const InstallPackageForm: React.FC<{
return (
<div className="flex items-center w-full border-b">
<SearchInput
- placeholder={`Install packages with ${packageManager}...`}
+ placeholder={
+ isSandbox
+ ? `Add packages to ${packageManager} sandbox...`
+ : `Install packages with ${packageManager}...`
+ }
id={PACKAGES_INPUT_ID}
icon={
loading ? (
@@ -209,12 +249,23 @@ const InstallPackageForm: React.FC<{
size="small"
className="mr-2 h-4 w-4 shrink-0 opacity-50"
/>
+ ) : isSandbox ? (
+ <BoxIcon
+ aria-hidden="true"
+ className="mr-2 h-4 w-4 shrink-0 opacity-50"
+ />
) : (
- <Tooltip content="Change package manager">
- <BoxIcon
+ <Tooltip
+ content={`Change package manager (currently ${packageManager})`}
+ >
+ <button
+ type="button"
+ aria-label="Change package manager"
onClick={() => openSettings("packageManagementAndData")}
- className="mr-2 h-4 w-4 shrink-0 opacity-50 hover:opacity-80 cursor-pointer"
- />
+ className="pointer-events-auto mr-2 rounded-sm opacity-50 hover:opacity-80 focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring"
+ >
+ <BoxIcon aria-hidden="true" className="h-4 w-4 shrink-0" />
+ </button>
</Tooltip>
)
}
@@ -234,9 +285,21 @@ const InstallPackageForm: React.FC<{
align="start"
content={
<div className="text-sm flex flex-col w-full max-w-[360px]">
- Packages are installed using the package manager specified in your
- user configuration. Depending on your package manager, you can
- install packages with various formats:
+ {isSandbox ? (
+ <span>
+ Packages are recorded in this notebook&apos;s inline metadata
+ and synchronized with its {packageManager} sandbox. To switch
+ backends, restart marimo with a different --sandbox option.
+ </span>
+ ) : (
+ <span>
+ Packages are installed using {packageManager}, selected in your
+ user configuration.
+ </span>
+ )}
+ <span className="mt-2">
+ You can install packages with various formats:
+ </span>
<div className="flex flex-col gap-2 mt-2">
<div>
<span className="font-bold tracking-wide">Package name:</span> A
@@ -379,7 +442,9 @@ const UpgradeButton: React.FC<{
upgrade: true,
group,
});
- if (response.success) {
+ if (response.restartRequired) {
+ showPackageRestartToast();
+ } else if (response.success) {
onSuccess();
showUpgradePackageToast(packageName);
} else {
@@ -413,7 +478,9 @@ const RemoveButton: React.FC<{
package: packageName,
group,
});
- if (response.success) {
+ if (response.restartRequired) {
+ showPackageRestartToast();
+ } else if (response.success) {
onSuccess();
showRemovePackageToast(packageName);
} else {
@@ -434,8 +501,9 @@ const RemoveButton: React.FC<{
const DependencyTree: React.FC<{
tree: DependencyTreeNode | null;
error?: Error | null;
+ sandboxBackend: "uv" | "pixi" | null;
onSuccess: () => void;
-}> = ({ tree, error, onSuccess }) => {
+}> = ({ tree, error, sandboxBackend, onSuccess }) => {
const [expandedNodes, setExpandedNodes] = React.useState<Set<string>>(
new Set(),
);
@@ -450,10 +518,25 @@ const DependencyTree: React.FC<{
}
if (!tree) {
- return <Spinner size="medium" centered={true} />;
+ return (
+ <PanelEmptyState
+ title="Dependency tree unavailable"
+ description="The sandbox did not return a dependency tree."
+ icon={<BoxIcon />}
+ />
+ );
}
if (tree.dependencies.length === 0) {
+ if (sandboxBackend === "pixi") {
+ return (
+ <PanelEmptyState
+ title="No PyPI dependencies"
+ description="Conda dependencies are not shown in this panel."
+ icon={<BoxIcon />}
+ />
+ );
+ }
return (
<PanelEmptyState
title="No dependencies"
@@ -575,6 +658,17 @@ const DependencyTreeNode: React.FC<{
{/* Tags */}
<div className="flex items-center gap-1 ml-2">
{node.tags.map((tag, index) => {
+ if (tag.kind === "dedupe") {
+ return (
+ <div
+ key={index}
+ 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-muted-foreground rounded-sm text-ellipsis block overflow-hidden max-w-fit font-medium"
+ title="Package tree already displayed"
+ >
+ already in tree
+ </div>
+ );
+ }
if (tag.kind === "cycle") {
return (
<div
diff --git a/frontend/src/components/editor/package-alert.tsx b/frontend/src/components/editor/package-alert.tsx
index 00d060b657..ebc945480c 100644
--- a/frontend/src/components/editor/package-alert.tsx
+++ b/frontend/src/components/editor/package-alert.tsx
@@ -10,6 +10,7 @@ import {
PackageCheckIcon,
PackageXIcon,
PlusIcon,
+ RotateCwIcon,
XIcon,
} from "lucide-react";
import type React from "react";
@@ -32,6 +33,7 @@ import {
import { useResolvedMarimoConfig } from "@/core/config/config";
import type { PackageInstallationStatus } from "@/core/kernel/messages";
import { useRequestClient } from "@/core/network/requests";
+import { RESTART_REQUIRED_DESCRIPTION } from "@/core/packages/toast-components";
import { isWasm } from "@/core/wasm/utils";
import { usePackageMetadata } from "@/hooks/usePackageMetadata";
import { Banner } from "@/plugins/impl/common/error-banner";
@@ -55,6 +57,12 @@ import {
import { ExternalLink } from "../ui/links";
import { NativeSelect } from "../ui/native-select";
import { Tooltip } from "../ui/tooltip";
+import { useRestartKernel } from "./actions/useRestartKernel";
+
+const RestartKernelButton = () => {
+ const restartKernel = useRestartKernel();
+ return <Button onClick={restartKernel}>Restart Kernel</Button>;
+};
function parsePackageSpecifier(spec: string): {
name: string;
@@ -251,6 +259,10 @@ export const PackageAlert: React.FC = () => {
)}
>
<p>{description}</p>
+ {status !== "installing" &&
+ Object.values(packageAlert.packages).includes(
+ "restart-required",
+ ) && <RestartKernelButton />}
<ul className="list-disc ml-2 mt-1">
{Object.entries(packageAlert.packages).map(([pkg, st], index) => (
<li
@@ -290,7 +302,9 @@ function getInstallationStatusElements(packages: PackageInstallationStatus) {
? "installing"
: statuses.has("failed")
? "failed"
- : "installed";
+ : statuses.has("restart-required")
+ ? "restart-required"
+ : "installed";
if (status === "installing") {
return {
@@ -300,6 +314,14 @@ function getInstallationStatusElements(packages: PackageInstallationStatus) {
description: "Installing packages:",
};
}
+ if (status === "restart-required") {
+ return {
+ status,
+ title: "Changes saved — restart required",
+ titleIcon: <RotateCwIcon className="w-5 h-5 inline-block mr-2" />,
+ description: RESTART_REQUIRED_DESCRIPTION,
+ };
+ }
if (status === "installed") {
return {
status: "installed",
@@ -330,6 +352,8 @@ const ProgressIcon = ({
return <CheckIcon size="1rem" />;
case "failed":
return <XIcon size="1rem" />;
+ case "restart-required":
+ return <RotateCwIcon size="1rem" />;
default:
logNever(status);
return null;
diff --git a/frontend/src/core/packages/__tests__/useInstallPackage.test.tsx b/frontend/src/core/packages/__tests__/useInstallPackage.test.tsx
index e04cdadd97..16f93a2887 100644
--- a/frontend/src/core/packages/__tests__/useInstallPackage.test.tsx
+++ b/frontend/src/core/packages/__tests__/useInstallPackage.test.tsx
@@ -1,10 +1,22 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import { act, renderHook } from "@testing-library/react";
+import {
+ act,
+ fireEvent,
+ render,
+ renderHook,
+ screen,
+} from "@testing-library/react";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { useInstallPackages } from "../useInstallPackage";
+import { Toast, ToastProvider, ToastViewport } from "@/components/ui/toast";
const toast = vi.fn();
const addPackage = vi.fn();
+const restartKernel = vi.fn();
+
+vi.mock("@/components/editor/actions/useRestartKernel", () => ({
+ useRestartKernel: () => restartKernel,
+}));
vi.mock("@/components/ui/use-toast", () => ({
toast: (...args: unknown[]) => toast(...args),
@@ -20,6 +32,7 @@ describe("useInstallPackages", () => {
beforeEach(() => {
toast.mockClear();
addPackage.mockClear();
+ restartKernel.mockClear();
});
it("batches all packages into a single install call", async () => {
@@ -109,6 +122,39 @@ describe("useInstallPackages", () => {
);
});
+ it("reports saved changes requiring restart without claiming installation", async () => {
+ addPackage.mockResolvedValue({
+ success: false,
+ error: null,
+ restartRequired: true,
+ });
+ const { result } = renderHook(() => useInstallPackages());
+ await act(async () => {
+ await result.current.handleInstallPackages(["boltons", "six"]);
+ });
+ expect(toast).toHaveBeenCalledTimes(1);
+ expect(toast).toHaveBeenCalledWith(
+ expect.objectContaining({
+ title: "Changes saved — restart required",
+ description: expect.stringContaining(
+ "Restarting clears in-memory variables",
+ ),
+ duration: Infinity,
+ action: expect.anything(),
+ }),
+ );
+ expect(toast.mock.calls[0][0].variant).not.toBe("danger");
+ render(
+ <ToastProvider>
+ <Toast>{toast.mock.calls[0][0].action}</Toast>
+ <ToastViewport />
+ </ToastProvider>,
+ );
+ expect(restartKernel).not.toHaveBeenCalled();
+ fireEvent.click(screen.getByRole("button", { name: "Restart Kernel" }));
+ expect(restartKernel).toHaveBeenCalledTimes(1);
+ });
+
it("calls onSuccess after a successful install", async () => {
addPackage.mockResolvedValue({ success: true, error: null });
const onSuccess = vi.fn();
diff --git a/frontend/src/core/packages/toast-components.tsx b/frontend/src/core/packages/toast-components.tsx
index e8fef5e384..04bf76f252 100644
--- a/frontend/src/core/packages/toast-components.tsx
+++ b/frontend/src/core/packages/toast-components.tsx
@@ -1,8 +1,34 @@
/* Copyright 2026 Marimo. All rights reserved. */
+import { useRestartKernel } from "@/components/editor/actions/useRestartKernel";
import { Kbd } from "@/components/ui/kbd";
+import { ToastAction } from "@/components/ui/toast";
import { toast } from "@/components/ui/use-toast";
+export const RESTART_REQUIRED_DESCRIPTION =
+ "Your dependency changes are saved. Restart the kernel to use the updated environment. Restarting clears in-memory variables.";
+
+const RestartKernelAction = () => {
+ const restartKernel = useRestartKernel();
+ return (
+ <ToastAction
+ altText="Restart the kernel to use the updated dependencies"
+ onClick={restartKernel}
+ >
+ Restart Kernel
+ </ToastAction>
+ );
+};
+
+export const showPackageRestartToast = () => {
+ toast({
+ title: "Changes saved — restart required",
+ description: RESTART_REQUIRED_DESCRIPTION,
+ duration: Infinity,
+ action: <RestartKernelAction />,
+ });
+};
+
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 b641eb811a..9d25188c27 100644
--- a/frontend/src/core/packages/useInstallPackage.ts
+++ b/frontend/src/core/packages/useInstallPackage.ts
@@ -3,7 +3,10 @@
import { useState } from "react";
import { Logger } from "@/utils/Logger";
import { useRequestClient } from "../network/requests";
-import { showAddPackageToast } from "./toast-components";
+import {
+ showAddPackageToast,
+ showPackageRestartToast,
+} from "./toast-components";
export function useInstallPackages(): {
handleInstallPackages: (
@@ -30,7 +33,9 @@ export function useInstallPackages(): {
// response only carries an aggregate success/error. Report a single
// toast covering all requested packages rather than implying a
// per-package outcome we don't actually have.
- if (response.success) {
+ if (response.restartRequired) {
+ showPackageRestartToast();
+ } else if (response.success) {
showAddPackageToast(packages);
} else {
showAddPackageToast(packages, response.error);
diff --git a/frontend/src/core/wasm/bridge.ts b/frontend/src/core/wasm/bridge.ts
index 8a053f3f81..0d375ae20a 100644
--- a/frontend/src/core/wasm/bridge.ts
+++ b/frontend/src/core/wasm/bridge.ts
@@ -649,6 +649,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
tags: [],
version: null,
},
+ context: { kind: "package-manager", name: "micropip" },
};
};
diff --git a/marimo/_cli/cli.py b/marimo/_cli/cli.py
index 224738e046..a37e99881d 100644
--- a/marimo/_cli/cli.py
+++ b/marimo/_cli/cli.py
@@ -21,10 +21,12 @@ from marimo._cli.config.commands import config
from marimo._cli.convert.commands import convert
from marimo._cli.development.commands import development
from marimo._cli.envinfo import get_system_info
-from marimo._cli.errors import MarimoCLIRuntimeError
+from marimo._cli.errors import (
+ MarimoCLIRuntimeError,
+)
from marimo._cli.export.commands import export
from marimo._cli.files.file_path import validate_name
-from marimo._cli.help_formatter import ColoredGroup, RunCommand
+from marimo._cli.help_formatter import ColoredCommand, ColoredGroup, RunCommand
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
@@ -148,7 +150,7 @@ token_password_message = (
sandbox_message = (
"Run the notebook in an isolated environment, with dependencies tracked "
"via PEP 723 inline metadata. If already declared, dependencies will "
- "install automatically. Requires uv."
+ "install automatically. Choose uv (default) or pixi."
)
check_message = "Disable a static check of the notebook before running."
@@ -281,7 +283,36 @@ class _OptionalValueOption(click.Option):
self.flag_value = opt_flag_value
[email protected](help=edit_help_msg)
+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)
@click.option(
"-p",
"--port",
@@ -347,12 +378,18 @@ class _OptionalValueOption(click.Option):
help="Don't check if a new version of marimo is available for download.",
)
@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,
+ type=bool,
+ help="Never run in a sandbox, and never prompt to.",
+)
@click.option(
"--trusted/--untrusted",
is_flag=True,
@@ -451,7 +488,8 @@ def edit(
base_url: str,
allow_origins: tuple[str, ...] | None,
skip_update_check: bool,
- sandbox: bool | None,
+ sandbox: str | None,
+ no_sandbox: bool,
trusted: bool | None,
profile_dir: str | None,
watch: bool,
@@ -467,7 +505,7 @@ def edit(
name: str | None,
args: tuple[str, ...],
) -> None:
- from marimo._cli.sandbox import SandboxMode, resolve_sandbox_mode
+ from marimo._cli.sandbox import SandboxMode, resolve_sandbox
pass_on_stdin = token_password_file == "-"
# We support unix-style piping, e.g. cat notebook.py | marimo edit
@@ -531,15 +569,20 @@ def edit(
# URLs into local file paths
# Resolve sandbox mode: None, SandboxMode.SINGLE, or SandboxMode.MULTI
- sandbox_mode = resolve_sandbox_mode(sandbox=sandbox, name=name)
+ sandbox_mode, sandbox_backend = resolve_sandbox(
+ sandbox=sandbox, no_sandbox=no_sandbox, name=name
+ )
- # Single-file sandbox: wrap with uv run
+ # 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, additional_features=["lsp"]
+ sys.argv[1:],
+ name=name,
+ extras=["lsp"],
+ backend=sandbox_backend,
)
)
@@ -550,6 +593,8 @@ def edit(
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
# Check shared memory availability early (required for edit mode to
# communicate between the server process and kernel subprocess)
@@ -648,7 +693,7 @@ new_help_msg = "\n".join(
)
[email protected](help=new_help_msg)
[email protected](cls=_SandboxCommand, help=new_help_msg)
@click.option(
"-p",
"--port",
@@ -701,12 +746,18 @@ new_help_msg = "\n".join(
callback=validators.base_url,
)
@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,
+ type=bool,
+ help="Never run in a sandbox, and never prompt to.",
+)
@click.option(
"--skew-protection/--no-skew-protection",
is_flag=True,
@@ -731,18 +782,22 @@ def new(
token_password: str | None,
token_password_file: str | None,
base_url: str,
- sandbox: bool | None,
+ sandbox: str | None,
+ no_sandbox: bool,
skew_protection: bool,
timeout: float | None,
prompt: str | None,
) -> None:
- if sandbox:
- from marimo._cli.sandbox import run_in_sandbox
+ if sandbox and not no_sandbox:
+ from marimo._cli.sandbox import backend_from_flag, run_in_sandbox
# TODO: consider adding recommended as well
sys.exit(
run_in_sandbox(
- sys.argv[1:], name=None, additional_features=["lsp"]
+ sys.argv[1:],
+ name=None,
+ extras=["lsp"],
+ backend=backend_from_flag(sandbox),
)
)
@@ -953,7 +1008,7 @@ def _create_run_workspace(
@main.command(
- cls=RunCommand,
+ cls=_SandboxRunCommand,
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.
@@ -1064,12 +1119,18 @@ Example:
help="Redirect console logs to the browser console.",
)
@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,
+ type=bool,
+ help="Never run in a sandbox, and never prompt to.",
+)
@click.option(
"--check/--no-check",
is_flag=True,
@@ -1133,7 +1194,8 @@ def run(
base_url: str,
allow_origins: tuple[str, ...],
redirect_console_to_browser: bool,
- sandbox: bool | None,
+ sandbox: str | None,
+ no_sandbox: bool,
check: bool,
trusted: bool | None,
server_startup_command: str | None,
@@ -1145,7 +1207,8 @@ def run(
) -> None:
from marimo._cli.sandbox import (
SandboxMode,
- resolve_sandbox_mode,
+ backend_from_flag,
+ resolve_sandbox,
run_in_sandbox,
)
@@ -1224,13 +1287,29 @@ def run(
# URLs into local file paths
if is_multi:
# Gallery mode: use MULTI sandbox (IPC kernels) or None
- sandbox_mode = SandboxMode.MULTI if sandbox else None
+ sandbox_mode = (
+ SandboxMode.MULTI if sandbox and not no_sandbox else None
+ )
+ sandbox_backend = backend_from_flag(sandbox)
else:
- sandbox_mode = resolve_sandbox_mode(
- sandbox=sandbox, name=validated_paths[0]
+ 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]))
+ 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)
diff --git a/marimo/_cli/export/_common.py b/marimo/_cli/export/_common.py
index 4619d794f4..ff57efea9e 100644
--- a/marimo/_cli/export/_common.py
+++ b/marimo/_cli/export/_common.py
@@ -70,7 +70,7 @@ class SandboxVenvPool:
self._targets: dict[str, SandboxTarget] = {}
def get_target(self, notebook_path: str) -> SandboxTarget:
- from marimo._environments.environment import sync_notebook
+ from marimo._environments.backends import sync_notebook
from marimo._environments.uv import UvMissingScriptMetadataError
key = str(Path(notebook_path).resolve())
@@ -79,7 +79,9 @@ class SandboxVenvPool:
return existing
try:
- target = SandboxTarget(environment=sync_notebook(key))
+ target = SandboxTarget(
+ environment=sync_notebook(key, backend="uv")
+ )
except UvMissingScriptMetadataError:
target = SandboxTarget(environment=None)
self._targets[key] = target
@@ -120,19 +122,15 @@ def run_python_subprocess(
payload: dict[str, Any],
action: str,
) -> str:
- import platform
-
- from marimo._environments.environment import launch, launch_isolated
+ from marimo._environments.backends import launch_fallback
+ from marimo._environments.environment import launch
from marimo._environments.overlay import runtime_overlay
args = ["-c", script, json.dumps(payload)]
- overlay = runtime_overlay()
if sandbox.environment is not None:
- plan = launch(sandbox.environment, args, overlay=overlay)
+ plan = launch(sandbox.environment, args, overlay=runtime_overlay())
else:
- plan = launch_isolated(
- args, overlay=overlay, python=platform.python_version()
- )
+ plan = launch_fallback(args)
with (
_export_termination_signals(),
subprocess.Popen(
diff --git a/marimo/_cli/export/commands.py b/marimo/_cli/export/commands.py
index d3f3176285..487eb93871 100644
--- a/marimo/_cli/export/commands.py
+++ b/marimo/_cli/export/commands.py
@@ -571,7 +571,7 @@ def ipynb(
run_in_sandbox(
sys.argv[1:],
name=name,
- additional_deps=["nbformat"],
+ command_deps=["nbformat"],
)
)
@@ -762,7 +762,7 @@ def pdf(
run_in_sandbox(
sys.argv[1:],
name=name,
- additional_deps=export_deps,
+ command_deps=export_deps,
)
)
diff --git a/marimo/_cli/export/thumbnail.py b/marimo/_cli/export/thumbnail.py
index 04dc3104fe..a33d349843 100644
--- a/marimo/_cli/export/thumbnail.py
+++ b/marimo/_cli/export/thumbnail.py
@@ -109,7 +109,7 @@ def _bootstrap_thumbnail_sandbox(
run_in_sandbox(
args,
name=name,
- additional_deps=_thumbnail_sandbox_deps,
+ command_deps=_thumbnail_sandbox_deps,
extra_env={
_sandbox_bootstrapped_env: "1",
_sandbox_mode_env: sandbox_mode.value,
diff --git a/marimo/_cli/sandbox.py b/marimo/_cli/sandbox.py
index 7af52d34ed..7e6ab05b89 100644
--- a/marimo/_cli/sandbox.py
+++ b/marimo/_cli/sandbox.py
@@ -10,7 +10,6 @@ import sys
import tempfile
from enum import Enum
from pathlib import Path
-from typing import Literal
import click
@@ -19,15 +18,13 @@ from marimo._cli.errors import MarimoCLIMissingDependencyError
from marimo._cli.print import bold, echo, green, muted
from marimo._config.settings import GLOBAL_SETTINGS
from marimo._environments import environment, script_metadata
-from marimo._environments.overlay import runtime_overlay
+from marimo._environments.overlay import DepExtras, runtime_overlay
+from marimo._environments.sandbox import Backend as SandboxBackend
from marimo._environments.uv import (
UvCommandError,
- UvError,
UvMissingScriptMetadataError,
- UvNotFoundError,
find_uv_bin,
is_uv_available,
- require_uv_bin,
uv,
)
from marimo._utils.inline_script_metadata import (
@@ -53,13 +50,18 @@ class SandboxMode(Enum):
LOGGER = _loggers.marimo_logger()
-DepFeatures = Literal["lsp", "recommended"]
-
-
def maybe_prompt_run_in_sandbox(name: str | None) -> bool:
if GLOBAL_SETTINGS.MANAGE_SCRIPT_METADATA:
return False
+ # This process was already launched inside a sandbox; re-wrapping
+ # it would nest a second environment inside the first.
+ if (
+ GLOBAL_SETTINGS.SANDBOX_MODE is not None
+ or GLOBAL_SETTINGS.SANDBOX_BACKEND is not None
+ ):
+ return False
+
if name is None:
return False
@@ -138,6 +140,33 @@ def resolve_sandbox_mode(
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
+ 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)
+
+
+def backend_from_flag(sandbox: str | None) -> SandboxBackend:
+ """The backend named by a `--sandbox[=<backend>]` flag value."""
+ return "pixi" if sandbox == "pixi" else "uv"
+
+
def _is_versioned(dependency: str) -> bool:
return any(c in dependency for c in ("==", ">=", "<=", ">", "<", "~"))
@@ -145,7 +174,7 @@ def _is_versioned(dependency: str) -> bool:
def _normalize_sandbox_dependencies(
dependencies: list[str],
marimo_version: str,
- additional_features: list[DepFeatures],
+ additional_features: list[DepExtras],
) -> list[str]:
"""Normalize marimo dependencies to have only one version.
@@ -153,7 +182,7 @@ def _normalize_sandbox_dependencies(
Add version to the remaining one if not already versioned.
"""
- def include_features(dep: str, features: list[DepFeatures]) -> str:
+ def include_features(dep: str, features: list[DepExtras]) -> str:
if not features:
return dep
@@ -163,7 +192,7 @@ def _normalize_sandbox_dependencies(
return dep.replace("marimo", f"marimo[{','.join(features)}]")
- def editable_marimo_dependency(features: list[DepFeatures]) -> str:
+ def editable_marimo_dependency(features: list[DepExtras]) -> str:
path = str(get_marimo_dir())
if features:
path = f"{path}[{','.join(features)}]"
@@ -269,7 +298,7 @@ def get_marimo_dir() -> Path:
def construct_uv_flags(
pyproject: PyProjectReader,
temp_file: "tempfile._TemporaryFileWrapper[str]", # noqa: UP037
- additional_features: list[DepFeatures],
+ additional_features: list[DepExtras],
additional_deps: list[str],
python_version_override: str | None = None,
) -> list[str]:
@@ -345,7 +374,7 @@ def construct_uv_flags(
def construct_uv_command(
args: list[str],
name: str | None,
- additional_features: list[DepFeatures],
+ additional_features: list[DepExtras],
additional_deps: list[str],
python_version_override: str | None = None,
) -> list[str]:
@@ -386,11 +415,12 @@ def run_in_sandbox(
args: list[str],
*,
name: str | None = None,
- additional_features: list[DepFeatures] | None = None,
- additional_deps: list[str] | None = None,
+ extras: list[DepExtras] | None = None,
+ command_deps: list[str] | None = None,
extra_env: dict[str, str] | None = None,
python_version_override: str | None = None,
pyodide_constraints: bool = False,
+ backend: SandboxBackend = "uv",
) -> int:
"""Runs marimo inside the notebook's script environment.
@@ -404,33 +434,38 @@ 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.sandbox import NotebookSandbox
+
try:
- require_uv_bin()
- except UvNotFoundError as e:
+ 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(
- "uv must be installed to use --sandbox.",
- "uv",
- additional_tip="Install uv from https://github.com/astral-sh/uv",
+ f"{backend} must be installed to use {option}.",
+ backend,
+ additional_tip=f"Install {backend} from {install_url}",
) from e
-
- # Ensure marimo and the python version are in the script metadata before
- # running. Adding marimo is best-effort: the sandbox still runs without
- # it, since the runtime overlay carries marimo.
- if name is not None and name.endswith(".py"):
- try:
- script_metadata.ensure_marimo(name)
- except script_metadata.ScriptMetadataError as e:
- if isinstance(e.__cause__, subprocess.TimeoutExpired):
- LOGGER.warning("Timed out adding marimo to script metadata")
- else:
- LOGGER.warning("%s", e)
- except Exception as e:
- LOGGER.warning(f"Failed to add marimo to script metadata: {e}")
+ except EnvironmentManagerError as e:
+ # e.g. an environment manager too old for script environments.
+ echo(str(e), err=True)
+ return 1
+
+ # NotebookSandbox prepares the runtime dependency through its backend
+ # Adapter. The Python requirement remains a structural Manifest concern.
+ if name is not None and name.endswith(".py") and backend == "uv":
script_metadata.ensure_requires_python(name)
- cmd = ["-m", "marimo", *args]
- if "--sandbox" in cmd:
- cmd.remove("--sandbox")
+ cmd = _strip_sandbox_args(["-m", "marimo", *args])
env = os.environ.copy()
env["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"
@@ -465,7 +500,7 @@ def run_in_sandbox(
atexit.register(cleanup_constraint_file)
- overlay = runtime_overlay(additional_features or [], additional_deps or [])
+ overlay = runtime_overlay(extras or [], command_deps or [])
# Explicit override > metadata requires-python (uv reads it) > host.
pyproject = (
@@ -483,46 +518,86 @@ def run_in_sandbox(
overridden = python_version_override is not None or pyodide_constraints
plan: environment.ProcessPlan | None = None
- if name is not None and not overridden and os.path.isfile(name):
+ notebook_sandbox: NotebookSandbox | None = None
+ if not overridden and (name is None or os.path.isfile(name)):
+ notebook_sandbox = NotebookSandbox(name, backend)
try:
- handle = environment.sync_notebook(
- name,
- python_override=python_request,
- # Stream uv's progress to the terminal; a first
- # synchronization can install for a while.
+ plan = notebook_sandbox.launch(
+ 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
echo(
f"Using script environment: {muted(handle.root)}",
err=True,
)
# Only a server whose kernel runs in the script environment
# may route package changes through it.
- env["MARIMO_SANDBOX_MODE"] = "single"
- plan = environment.launch(
- handle, cmd, overlay=overlay, base_env=env
- )
- except UvMissingScriptMetadataError:
- # No metadata block yet; run ephemerally below.
- pass
- except UvError as e:
+ plan.env["MARIMO_SANDBOX_MODE"] = "single"
+ plan.env["MARIMO_SANDBOX_BACKEND"] = backend
+ except EnvironmentManagerError as e:
+ notebook_sandbox.close()
echo(str(e), err=True)
return getattr(e, "returncode", None) or 1
if plan is None:
+ if backend == "pixi":
+ echo(
+ "pixi sandboxes do not support interpreter overrides",
+ err=True,
+ )
+ return 1
+ requirements = list(overlay.requirements)
if overridden and name is not None and os.path.isfile(name):
- overlay = [
+ requirements = [
line
for line in _resolve_requirements_txt_lines(pyproject)
if line.strip() and not is_marimo_dependency(line)
- ] + overlay
- plan = environment.launch_isolated(
+ ] + requirements
+ from marimo._environments.environment import launch_isolated
+
+ # The one resolve the parent environment cannot serve: an
+ # overridden interpreter under external constraints.
+ plan = launch_isolated(
cmd,
- overlay=overlay,
+ requirements=requirements,
python=python_request or platform.python_version(),
base_env=env,
)
+ try:
+ return _wait_on_plan(plan)
+ finally:
+ if notebook_sandbox is not None:
+ notebook_sandbox.close()
+
+
+def _strip_sandbox_args(cmd: list[str]) -> list[str]:
+ """Drop the outer sandbox option without touching notebook arguments."""
+ stripped: list[str] = []
+ index = 0
+ while index < len(cmd):
+ token = cmd[index]
+ if token == "--":
+ stripped.extend(cmd[index:])
+ break
+ if token.startswith("--sandbox="):
+ index += 1
+ continue
+ if token == "--sandbox":
+ index += 1
+ continue
+ stripped.append(token)
+ index += 1
+ return stripped
+
+
+def _wait_on_plan(plan: environment.ProcessPlan) -> int:
+ """Runs the plan, forwarding signals, and returns its exit code."""
echo(f"Running in a sandbox: {muted(' '.join(plan.argv))}", err=True)
if sys.platform == "win32":
diff --git a/marimo/_cli/tips.py b/marimo/_cli/tips.py
index 4cd45dc133..fcf382befb 100644
--- a/marimo/_cli/tips.py
+++ b/marimo/_cli/tips.py
@@ -197,7 +197,9 @@ def _explicitly_set_option_names(ctx: click.Context) -> list[str]:
if source is None or source == ParameterSource.DEFAULT:
continue
value = ctx.params.get(param.name)
- if isinstance(value, bool) and not value:
+ if isinstance(value, bool) and (
+ not value or all(opt.startswith("--no-") for opt in param.opts)
+ ):
continue
options.append(param.name)
return options
diff --git a/marimo/_code_mode/_context.py b/marimo/_code_mode/_context.py
index 3b364e5ae4..3689185f35 100644
--- a/marimo/_code_mode/_context.py
+++ b/marimo/_code_mode/_context.py
@@ -40,9 +40,9 @@ from marimo._ast.compiler import compile_cell
from marimo._ast.names import SETUP_CELL_NAME
from marimo._code_mode._better_inspect import _HelpableEnumMeta, helpable
from marimo._code_mode._packages import (
+ PackageResult,
Packages,
_AddPackage,
- _RemovePackage,
)
from marimo._code_mode._plan import (
_AddOp,
@@ -838,14 +838,28 @@ class AsyncCodeModeContext:
def _print_summary(
self,
ops: list[_Op],
- package_ops: list[_AddPackage | _RemovePackage],
+ package_ops: list[PackageResult],
ui_updates: list[tuple[UIElementId, Any]],
cells_to_run: set[CellId_t] | None = None,
) -> None:
"""Print a human-readable summary of applied operations."""
lines: list[str] = []
- for pkg_op in package_ops:
+ for result in package_ops:
+ pkg_op = result.op
+ if result.outcome == "restart-required":
+ lines.append(
+ f"changes saved for {pkg_op.package}; restart the kernel to use them"
+ )
+ continue
+ if result.outcome == "failed":
+ action = (
+ "install"
+ if isinstance(pkg_op, _AddPackage)
+ else "uninstall"
+ )
+ lines.append(f"failed to {action} {pkg_op.package}")
+ continue
if isinstance(pkg_op, _AddPackage):
lines.append(f"installed {pkg_op.package}")
else:
diff --git a/marimo/_code_mode/_packages.py b/marimo/_code_mode/_packages.py
index 3e8e1a6d83..f5e5764079 100644
--- a/marimo/_code_mode/_packages.py
+++ b/marimo/_code_mode/_packages.py
@@ -10,7 +10,7 @@ from __future__ import annotations
import asyncio
from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Literal, Union
+from typing import TYPE_CHECKING, Literal, Union
from marimo._config.settings import GLOBAL_SETTINGS
from marimo._messaging.notification import (
@@ -18,7 +18,10 @@ from marimo._messaging.notification import (
PackageStatusType,
)
from marimo._messaging.notification_utils import broadcast_notification
-from marimo._runtime.packages.package_manager import PackageDescription
+from marimo._runtime.packages.package_manager import (
+ PackageDescription,
+ PackageManager,
+)
from marimo._runtime.packages.utils import split_packages
if TYPE_CHECKING:
@@ -36,9 +39,29 @@ class _RemovePackage:
PackageOp = Union[_AddPackage, _RemovePackage]
-# Alias for `list` used in `Packages` annotations; `Packages.list` shadows the
-# builtin inside the class scope.
-PackageOpList = list[PackageOp]
+PackageOutcome = Literal["success", "failed", "restart-required"]
+
+
+@dataclass(frozen=True, slots=True)
+class PackageResult:
+ op: PackageOp
+ outcome: PackageOutcome
+
+ @classmethod
+ def succeeded(cls, op: PackageOp) -> PackageResult:
+ return cls(op, "success")
+
+ @classmethod
+ def failed(cls, op: PackageOp) -> PackageResult:
+ return cls(op, "failed")
+
+ @classmethod
+ def restart_required(cls, op: PackageOp) -> PackageResult:
+ return cls(op, "restart-required")
+
+
+# `Packages.list` shadows the builtin in method annotations.
+PackageResultList = list[PackageResult]
def _flatten_packages(
@@ -148,8 +171,8 @@ class Packages:
def _reset(self) -> None:
self._ops = []
- async def _flush(self) -> PackageOpList:
- """Execute queued ops in order. Returns the ops that ran."""
+ async def _flush(self) -> PackageResultList:
+ """Execute queued ops in order and retain their actual outcomes."""
if not self._ops:
return []
@@ -158,11 +181,11 @@ class Packages:
pm = self._ctx._kernel.packages_callbacks.package_manager
if pm is None:
- return ops
+ return [PackageResult.failed(op) for op in ops]
if not pm.is_manager_installed():
pm.alert_not_installed()
- return ops
+ return [PackageResult.failed(op) for op in ops]
source: Literal["kernel", "server"] = "kernel"
statuses: PackageStatusType = {}
@@ -184,22 +207,31 @@ class Packages:
and filename is not None
)
+ results: PackageResultList = []
for op in ops:
if isinstance(op, _AddPackage):
- await self._run_add(op, pm, statuses, source, manage_metadata)
+ success = await self._run_add(
+ op, pm, statuses, source, manage_metadata
+ )
+ else:
+ success = await self._run_remove(op, pm, manage_metadata)
+ if success:
+ results.append(PackageResult.succeeded(op))
+ elif pm.restart_required:
+ results.append(PackageResult.restart_required(op))
else:
- await self._run_remove(op, pm, manage_metadata)
+ results.append(PackageResult.failed(op))
- return ops
+ return results
async def _run_add(
self,
op: _AddPackage,
- pm: Any,
+ pm: PackageManager,
statuses: PackageStatusType,
source: Literal["kernel", "server"],
manage_metadata: bool,
- ) -> None:
+ ) -> bool:
pkg = op.package
statuses[pkg] = "installing"
broadcast_notification(
@@ -235,13 +267,17 @@ class Packages:
if success:
statuses[pkg] = "installed"
final_log = f"Successfully installed {pkg}\n"
- if manage_metadata:
+ filename = self._ctx._kernel.app_metadata.filename
+ if manage_metadata and filename is not None:
await asyncio.to_thread(
pm.update_notebook_script_metadata,
- filepath=self._ctx._kernel.app_metadata.filename,
+ filepath=filename,
packages_to_add=split_packages(pkg),
upgrade=False,
)
+ elif pm.restart_required:
+ statuses[pkg] = "restart-required"
+ final_log = f"Dependency changes saved for {pkg}; restart the kernel to use them.\n"
else:
statuses[pkg] = "failed"
final_log = f"Failed to install {pkg}\n"
@@ -255,18 +291,21 @@ class Packages:
),
stream=self._ctx._kernel.stream,
)
+ return success
async def _run_remove(
self,
op: _RemovePackage,
- pm: Any,
+ pm: PackageManager,
manage_metadata: bool,
- ) -> None:
+ ) -> bool:
success = await pm.uninstall(op.package)
- if success and manage_metadata:
+ filename = self._ctx._kernel.app_metadata.filename
+ if success and manage_metadata and filename is not None:
await asyncio.to_thread(
pm.update_notebook_script_metadata,
- filepath=self._ctx._kernel.app_metadata.filename,
+ filepath=filename,
packages_to_remove=split_packages(op.package),
upgrade=False,
)
+ return success
diff --git a/marimo/_config/settings.py b/marimo/_config/settings.py
index bcc61a7ed3..77caceb58b 100644
--- a/marimo/_config/settings.py
+++ b/marimo/_config/settings.py
@@ -21,6 +21,10 @@ class GlobalSettings:
# "single" or "multi" when this process belongs to a sandbox whose
# dependencies live in script environments; None otherwise.
SANDBOX_MODE: str | None = os.environ.get("MARIMO_SANDBOX_MODE") or None
+ # The environment manager behind SANDBOX_MODE: "uv" or "pixi".
+ SANDBOX_BACKEND: str | None = (
+ os.environ.get("MARIMO_SANDBOX_BACKEND") or None
+ )
IN_SECURE_ENVIRONMENT: bool = is_env_true("MARIMO_IN_SECURE_ENVIRONMENT")
# Mark the session cookie as `Secure` so browsers only send it over HTTPS.
# Enable when serving marimo behind TLS / a TLS-terminating proxy. Default
diff --git a/marimo/_environments/backends.py b/marimo/_environments/backends.py
new file mode 100644
index 0000000000..31ce32837a
--- /dev/null
+++ b/marimo/_environments/backends.py
@@ -0,0 +1,525 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""The uv and pixi environment-manager adapters.
+
+`UvBackendAdapter` and `PixiBackendAdapter` supply the notebook sandbox's
+backend operations; `adapter_for` selects one. The module-level
+verbs plan launches for callers that must not edit a manifest (an app
+host serving notebooks); they dispatch through the same adapters, so
+backend policy lives in one place.
+
+Both managers honor the runtime overlay: uv layers it directly via
+`uv run --with`, while pixi routes the same layering through
+`pixi exec uv run`, whose ephemeral environment chains the conda
+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
+
+import os
+import sys
+from typing import TYPE_CHECKING
+
+from marimo import _loggers
+
+if TYPE_CHECKING:
+ from collections.abc import Callable, Mapping, Sequence
+
+ from marimo._environments.environment import Environment, ProcessPlan
+ from marimo._environments.overlay import RuntimeOverlay
+ from marimo._environments.sandbox import (
+ Backend,
+ BackendAdapter,
+ LogCallback,
+ PackageState,
+ ResolvedPackage,
+ SandboxOperation,
+ SandboxReporter,
+ )
+ from marimo._environments.script_metadata import MaterializedScript
+ from marimo._utils.uv_tree import DependencyTreeNode
+
+LOGGER = _loggers.marimo_logger()
+
+
+def current_backend() -> Backend:
+ """The backend this process was sandboxed with; uv when unset."""
+ from marimo._config.settings import GLOBAL_SETTINGS
+
+ return "pixi" if GLOBAL_SETTINGS.SANDBOX_BACKEND == "pixi" else "uv"
+
+
+def adapter_for(
+ backend: Backend, reporter: SandboxReporter | None = None
+) -> BackendAdapter:
+ """The adapter managing `backend`'s environments.
+
+ Constructing an adapter is backend-pure: selecting pixi does not
+ import or probe the uv implementation, and vice versa.
+ """
+ if backend == "pixi":
+ return PixiBackendAdapter(reporter)
+ return UvBackendAdapter(reporter)
+
+
+def ensure_available(backend: Backend) -> None:
+ """Raise unless the backend's executable is usable and supported.
+
+ uv raises `UvNotFoundError` or `UvUnsupportedVersionError`; pixi
+ raises `PixiNotFoundError` or `PixiUnsupportedVersionError`.
+ """
+ adapter_for(backend).ensure_available()
+
+
+def sync_notebook(
+ path: str,
+ *,
+ backend: Backend,
+ python_override: str | None = None,
+ on_output: Callable[[str], None] | None = None,
+) -> Environment:
+ """Synchronizes a notebook's script environment.
+
+ Raises the backend's error type on failure; both derive from the
+ backend's base error (`UvError`, `PixiError`).
+ """
+ from marimo._environments import script_metadata
+
+ adapter = adapter_for(backend)
+ with script_metadata.materialized_for_environment(path) as target:
+ return adapter.sync(
+ target, python_override=python_override, on_output=on_output
+ )
+
+
+def launch(
+ environment: Environment,
+ args: Sequence[str],
+ *,
+ backend: Backend,
+ overlay: RuntimeOverlay,
+ base_env: Mapping[str, str] | None = None,
+) -> ProcessPlan:
+ """Plans `python <args...>` inside a synchronized environment."""
+ return adapter_for(backend).launch(
+ environment, args, overlay=overlay, base_env=base_env
+ )
+
+
+def launch_fallback(
+ args: Sequence[str],
+ *,
+ base_env: Mapping[str, str] | None = None,
+) -> ProcessPlan:
+ """Plans `python <args...>` for a target without a manifest.
+
+ No manifest means nothing to sandbox: the process runs from this
+ interpreter, which has marimo by definition. No environment manager
+ selects the interpreter here, so the inherited activation state
+ must describe this interpreter: a stale VIRTUAL_ENV from an
+ enclosing shell must not leak, and a virtualenv interpreter names
+ its own prefix.
+ """
+ from marimo._environments.environment import ProcessPlan
+
+ env = dict(os.environ if base_env is None else base_env)
+ env.pop("VIRTUAL_ENV", None)
+ env.pop("UV_PROJECT_ENVIRONMENT", None)
+ if sys.prefix != sys.base_prefix:
+ env["VIRTUAL_ENV"] = sys.prefix
+ return ProcessPlan(argv=(sys.executable, *args), env=env)
+
+
+class _ReportingBackendAdapter:
+ name: Backend
+
+ def __init__(self, reporter: SandboxReporter | None = None) -> None:
+ if reporter is None:
+ from marimo._environments.sandbox import NullSandboxReporter
+
+ reporter = NullSandboxReporter()
+ self._reporter = reporter
+
+ def _report(
+ self, operation: SandboxOperation, command: Sequence[str]
+ ) -> None:
+ from marimo._environments.sandbox import SandboxCommand
+
+ self._reporter.report(
+ SandboxCommand(
+ backend=self.name,
+ operation=operation,
+ argv=tuple(command),
+ )
+ )
+
+
+class UvBackendAdapter(_ReportingBackendAdapter):
+ """uv implementation of the notebook sandbox backend."""
+
+ name: Backend = "uv"
+
+ def ensure_available(self) -> None:
+ from marimo._environments.environment import ensure_supported_uv
+
+ ensure_supported_uv()
+
+ def prepare_source(self, source: str) -> None:
+ import subprocess
+
+ from marimo._environments import script_metadata
+
+ try:
+ script_metadata.ensure_marimo(
+ source,
+ on_command=lambda command: self._report("prepare", command),
+ )
+ except subprocess.TimeoutExpired:
+ LOGGER.warning("Timed out adding marimo to script metadata")
+ except Exception as error:
+ LOGGER.warning(
+ "Failed to add marimo to script metadata: %s", error
+ )
+
+ def add(
+ self,
+ target: MaterializedScript,
+ package: str,
+ *,
+ upgrade: bool,
+ on_output: LogCallback | None,
+ ) -> None:
+ from marimo._environments.uv import script_command_env, uv, uv_stream
+
+ command = [
+ "add",
+ "--script",
+ target.path,
+ *(["--upgrade"] if upgrade else []),
+ package,
+ ]
+
+ def report(argv: Sequence[str]) -> None:
+ self._report("upgrade" if upgrade else "add", argv)
+
+ if on_output is None:
+ uv(
+ ["--quiet", *command],
+ env=script_command_env(),
+ cwd=target.directory,
+ on_command=report,
+ )
+ else:
+ uv_stream(
+ command,
+ on_output,
+ env=script_command_env(),
+ cwd=target.directory,
+ on_command=report,
+ )
+
+ def remove(
+ self,
+ target: MaterializedScript,
+ package: str,
+ *,
+ on_output: LogCallback | None,
+ ) -> None:
+ from marimo._environments.uv import script_command_env, uv, uv_stream
+
+ command = ["remove", "--script", target.path, package]
+
+ def report(argv: Sequence[str]) -> None:
+ self._report("remove", argv)
+
+ if on_output is None:
+ uv(
+ ["--quiet", *command],
+ env=script_command_env(),
+ cwd=target.directory,
+ on_command=report,
+ )
+ else:
+ uv_stream(
+ command,
+ on_output,
+ env=script_command_env(),
+ cwd=target.directory,
+ on_command=report,
+ )
+
+ def sync(
+ self,
+ target: MaterializedScript,
+ *,
+ python_override: str | None,
+ on_output: LogCallback | None,
+ active_environment: Environment | None = None,
+ ) -> Environment:
+ from marimo._environments.environment import sync
+
+ return sync(
+ 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 packages(
+ self,
+ target: MaterializedScript,
+ environment: Environment | None,
+ ) -> PackageState:
+ del environment
+ from marimo._environments.sandbox import PackageState
+ from marimo._environments.uv import UvError, script_command_env, uv
+ from marimo._utils.uv_tree import parse_uv_tree
+
+ try:
+ completed = uv(
+ ["tree", "--script", target.path],
+ env=script_command_env(),
+ cwd=target.directory,
+ )
+ except UvError:
+ return PackageState(packages=(), tree=None)
+ tree = parse_uv_tree(completed.stdout)
+ return PackageState(packages=_flatten_tree(tree), tree=tree)
+
+ def launch(
+ self,
+ environment: Environment,
+ args: Sequence[str],
+ *,
+ overlay: RuntimeOverlay,
+ base_env: Mapping[str, str] | None,
+ ) -> ProcessPlan:
+ from marimo._environments.environment import launch
+
+ return launch(
+ environment,
+ args,
+ overlay=overlay,
+ base_env=base_env,
+ )
+
+
+class PixiBackendAdapter(_ReportingBackendAdapter):
+ """pixi implementation of the notebook sandbox backend."""
+
+ name: Backend = "pixi"
+
+ def ensure_available(self) -> None:
+ from marimo._environments import pixi
+
+ pixi.require_pixi_bin()
+ pixi.ensure_supported_pixi()
+
+ def prepare_source(self, source: str) -> None:
+ import subprocess
+
+ from marimo._environments import pixi
+
+ try:
+ pixi.ensure_marimo(
+ source,
+ on_command=lambda command: self._report("prepare", command),
+ )
+ except subprocess.TimeoutExpired:
+ LOGGER.warning("Timed out adding marimo to script metadata")
+ except Exception as error:
+ LOGGER.warning(
+ "Failed to add marimo to script metadata: %s", error
+ )
+
+ def add(
+ self,
+ target: MaterializedScript,
+ package: str,
+ *,
+ upgrade: bool,
+ on_output: LogCallback | None,
+ ) -> None:
+ from marimo._environments import pixi
+
+ pixi.add(
+ target.path,
+ package,
+ cwd=target.directory,
+ upgrade=upgrade,
+ on_output=on_output,
+ on_command=lambda command: self._report(
+ "upgrade" if upgrade else "add", command
+ ),
+ )
+
+ def remove(
+ self,
+ target: MaterializedScript,
+ package: str,
+ *,
+ on_output: LogCallback | None,
+ ) -> None:
+ from marimo._environments import pixi
+
+ pixi.remove(
+ target.path,
+ package,
+ cwd=target.directory,
+ on_output=on_output,
+ on_command=lambda command: self._report("remove", command),
+ )
+
+ def sync(
+ 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 = pixi.sync(
+ target.path,
+ cwd=target.directory,
+ on_output=on_output,
+ on_command=lambda command: self._report("sync", command),
+ )
+ if active_environment is not None and os.path.realpath(
+ environment.root
+ ) != os.path.realpath(active_environment.root):
+ # Renaming a notebook or first saving an unnamed one can change
+ # its script environment's cache identity. The live kernel still
+ # uses the original prefix. uv sync --active updates that retained
+ # prefix, but pixi install --script has no equivalent target-prefix
+ # option. A successful sync into the new prefix therefore needs
+ # a kernel restart before the dependency changes take effect.
+ from marimo._environments.errors import SandboxRestartRequired
+
+ raise SandboxRestartRequired(
+ "Your dependency changes are saved, but Pixi installed them "
+ "in a new environment. Restart the kernel to use the updated "
+ "dependencies. Restarting clears in-memory variables."
+ )
+ return environment
+
+ def packages(
+ self,
+ target: MaterializedScript,
+ environment: Environment | None,
+ ) -> PackageState:
+ del environment
+ from marimo._environments import pixi
+ from marimo._environments.sandbox import PackageState, ResolvedPackage
+
+ records = pixi.list_script_packages(target.path, cwd=target.directory)
+ tree = pixi.tree_script_packages(target.path, cwd=target.directory)
+ packages = tuple(
+ sorted(
+ (
+ ResolvedPackage(
+ name=str(record.get("name", "")),
+ version=(
+ str(record["version"])
+ if record.get("version") is not None
+ else ""
+ ),
+ )
+ for record in records
+ if record.get("name") and record.get("kind") == "pypi"
+ ),
+ key=lambda package: package.name,
+ )
+ )
+ return PackageState(
+ packages=packages,
+ tree=_pixi_tree(records, tree),
+ )
+
+ def launch(
+ self,
+ environment: Environment,
+ args: Sequence[str],
+ *,
+ overlay: RuntimeOverlay,
+ base_env: Mapping[str, str] | None,
+ ) -> ProcessPlan:
+ from marimo._environments import pixi
+
+ return pixi.launch(
+ environment, args, overlay=overlay, base_env=base_env
+ )
+
+
+def _flatten_tree(tree: object) -> tuple[ResolvedPackage, ...]:
+ from marimo._environments.sandbox import ResolvedPackage
+ from marimo._utils.uv_tree import DependencyTreeNode
+
+ if not isinstance(tree, DependencyTreeNode):
+ return ()
+ seen: set[str] = set()
+ packages: list[ResolvedPackage] = []
+ stack = list(tree.dependencies)
+ while stack:
+ node = stack.pop()
+ if node.name not in seen:
+ seen.add(node.name)
+ packages.append(
+ ResolvedPackage(name=node.name, version=node.version or "")
+ )
+ stack.extend(node.dependencies)
+ return tuple(sorted(packages, key=lambda package: package.name))
+
+
+def _pixi_tree(
+ records: list[dict[str, object]], text: str
+) -> DependencyTreeNode:
+ from marimo._utils.uv_tree import DependencyTreeNode, parse_pixi_tree
+
+ pypi_names = {
+ _normalize_package_name(str(record["name"]))
+ for record in records
+ if record.get("name") and record.get("kind") == "pypi"
+ }
+ parsed = parse_pixi_tree(text)
+
+ def pypi_node(node: DependencyTreeNode) -> DependencyTreeNode | None:
+ if _normalize_package_name(node.name) not in pypi_names:
+ return None
+ dependencies = [
+ filtered
+ for dependency in node.dependencies
+ if (filtered := pypi_node(dependency)) is not None
+ ]
+ return DependencyTreeNode(
+ name=node.name,
+ version=node.version,
+ tags=node.tags,
+ dependencies=dependencies,
+ )
+
+ roots = [
+ filtered
+ for node in parsed.dependencies
+ if (filtered := pypi_node(node)) is not None
+ ]
+ return DependencyTreeNode(
+ name="<root>", version=None, tags=[], dependencies=roots
+ )
+
+
+def _normalize_package_name(name: str) -> str:
+ import re
+
+ return re.sub(r"[-_.]+", "-", name).lower()
diff --git a/marimo/_environments/environment.py b/marimo/_environments/environment.py
index 7d6ed52d16..b031e966b4 100644
--- a/marimo/_environments/environment.py
+++ b/marimo/_environments/environment.py
@@ -22,6 +22,7 @@ from marimo import _loggers
from marimo._environments.uv import (
UvError,
require_uv_bin,
+ script_command_env,
uv,
uv_stream,
)
@@ -29,6 +30,8 @@ from marimo._environments.uv import (
if TYPE_CHECKING:
from collections.abc import Callable, Mapping, Sequence
+ from marimo._environments.overlay import RuntimeOverlay
+
LOGGER = _loggers.marimo_logger()
Action = Literal["created", "updated", "replaced", "unchanged"]
@@ -66,12 +69,6 @@ class Environment:
root: str
action: Action
- def requires_restart(self, previous: Environment | None) -> bool:
- """Whether a process launched from `previous` must be relaunched."""
- if previous is None:
- return False
- return self.action == "replaced" or self.python != previous.python
-
def process_env(
self, base: Mapping[str, str] | None = None
) -> dict[str, str]:
@@ -105,21 +102,23 @@ def launch(
environment: Environment,
args: Sequence[str],
*,
- overlay: Sequence[str] = (),
+ overlay: RuntimeOverlay,
base_env: Mapping[str, str] | None = None,
) -> ProcessPlan:
"""Plans running `python <args...>` inside the environment.
- With no overlay, the plan invokes the environment's interpreter
- directly. Overlay requirements (PEP 508, or `-e <path>` for an
- editable install) are layered via `uv run --with` into a cached side
- environment for this process only; the script environment and the
- manifest are never modified.
+ uv layers the overlay with `--with`, resolving it into a cached side
+ environment that chains this one, so the process sees the overlay's
+ packages first and the environment's behind them:
+
+ uv run --active --no-project --python <env>/bin/python \
+ --with marimo==<version> -- python <args...>
+
+ Neither the environment nor the manifest is modified. See
+ `RuntimeOverlay` for what the layer carries and why a launch always
+ has one.
"""
env = environment.process_env(base_env)
- if not overlay:
- return ProcessPlan(argv=(environment.python, *args), env=env)
-
return ProcessPlan(
argv=(
require_uv_bin(),
@@ -130,7 +129,7 @@ def launch(
"--no-project",
"--python",
environment.python,
- *_with_args(overlay),
+ *_with_args(overlay.requirements),
"--",
"python",
*args,
@@ -143,16 +142,20 @@ def launch(
def launch_isolated(
args: Sequence[str],
*,
- overlay: Sequence[str],
+ requirements: Sequence[str],
python: str,
base_env: Mapping[str, str] | None = None,
) -> ProcessPlan:
"""Plans `python <args...>` in an ephemeral environment.
- For targets without a manifest, such as a new notebook. uv resolves
- the overlay into a cached environment and runs the process in an
- ephemeral copy, so packages installed during the session die with
- it and nothing persists per invocation.
+ 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)
@@ -166,7 +169,7 @@ def launch_isolated(
"--compile-bytecode",
"--python",
python,
- *_with_args(overlay),
+ *_with_args(requirements),
"--",
"python",
*args,
@@ -176,10 +179,10 @@ def launch_isolated(
)
-def _with_args(overlay: Sequence[str]) -> list[str]:
- """`uv run` flags for overlay requirements; `-e <path>` is editable."""
+def _with_args(requirements: Sequence[str]) -> list[str]:
+ """`uv run` flags for layered requirements; `-e <path>` is editable."""
with_args: list[str] = []
- for requirement in overlay:
+ for requirement in requirements:
if requirement.startswith("-e "):
with_args.extend(["--with-editable", requirement[3:].strip()])
else:
@@ -192,7 +195,9 @@ def sync(
*,
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:
"""Makes the script's environment match its metadata.
@@ -200,8 +205,10 @@ def sync(
directory-scoped uv configuration applies. `python_override` wins
over the script's `requires-python` (html-wasm export pins the
Pyodide interpreter). With `on_output`, uv's progress streams to the
- callback line by line. Raises `UvCommandError` on failure and never
- mutates `script`.
+ callback line by line; `on_command` receives the exact argv about to
+ run. `active_environment` targets a live notebook's retained prefix,
+ including after rename, rather than the script's default cache entry.
+ Raises `UvCommandError` on failure and never mutates `script`.
"""
ensure_supported_uv()
args = [
@@ -214,38 +221,25 @@ def sync(
]
if python_override is not None:
args.extend(["--python", python_override])
+ env = script_command_env()
+ if active_environment is not None:
+ # A live kernel remains attached to this prefix after rename/save.
+ # 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=_sync_env(), cwd=cwd)
+ completed = uv_stream(
+ args,
+ on_output,
+ env=env,
+ cwd=cwd,
+ on_command=on_command,
+ )
else:
- completed = uv(args, env=_sync_env(), cwd=cwd)
+ completed = uv(args, env=env, cwd=cwd, on_command=on_command)
return _parse_report(completed.stdout)
-def sync_notebook(
- path: str,
- *,
- python_override: str | None = None,
- on_output: Callable[[str], None] | None = None,
-) -> Environment:
- """Synchronizes a notebook's script environment.
-
- Materializes the manifest when it lives in frontmatter. Raises
- `UvMissingScriptMetadataError` when the notebook has no metadata
- block.
- """
- from marimo._environments.script_metadata import (
- materialized_for_environment,
- )
-
- with materialized_for_environment(path) as target:
- return sync(
- target.path,
- cwd=target.directory,
- python_override=python_override,
- on_output=on_output,
- )
-
-
def ensure_supported_uv() -> None:
"""Raise `UvUnsupportedVersionError` for a uv below the minimum."""
version = _uv_version()
@@ -352,9 +346,3 @@ def _venv_python(root: str) -> str | None:
def _venv_bin_dir(root: str) -> str:
return os.path.join(root, "Scripts" if os.name == "nt" else "bin")
-
-
-def _sync_env() -> dict[str, str]:
- from marimo._environments.uv import script_command_env
-
- return script_command_env()
diff --git a/marimo/_environments/errors.py b/marimo/_environments/errors.py
index a83bab7e3f..f9f213b03f 100644
--- a/marimo/_environments/errors.py
+++ b/marimo/_environments/errors.py
@@ -11,3 +11,19 @@ from __future__ import annotations
class EnvironmentManagerError(Exception):
"""Base for failures invoking an environment manager."""
+
+
+class EnvironmentManagerNotFoundError(EnvironmentManagerError):
+ """The selected environment manager is not installed or on PATH."""
+
+
+class MissingScriptMetadataError(EnvironmentManagerError):
+ """The target script has no PEP 723 inline metadata block."""
+
+
+class SandboxRestartRequired(EnvironmentManagerError):
+ """The manifest synchronized, but not into the live kernel's prefix.
+
+ This is not a solver failure. Callers must not report the requested
+ packages as importable until the kernel launches the new environment.
+ """
diff --git a/marimo/_environments/overlay.py b/marimo/_environments/overlay.py
index 6aa6159c0c..232f37a1e0 100644
--- a/marimo/_environments/overlay.py
+++ b/marimo/_environments/overlay.py
@@ -3,8 +3,9 @@
from __future__ import annotations
+from dataclasses import dataclass
from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
from marimo import _loggers
from marimo._utils.versions import is_editable
@@ -15,27 +16,111 @@ if TYPE_CHECKING:
LOGGER = _loggers.marimo_logger()
+DepExtras = Literal["lsp", "recommended"]
+
def marimo_dir() -> Path:
"""The repository root when marimo runs from a checkout."""
return Path(__file__).parent.parent.parent
+@dataclass(frozen=True)
+class RuntimeOverlay:
+ """The requirements a launch adds on top of a script environment.
+
+ A script environment belongs to the notebook. A backend builds it from
+ the notebook's manifest, and both `uv run notebook.py` and `marimo edit
+ --sandbox notebook.py` address the same cached environment for the same
+ path. But a marimo process launched into that environment needs packages
+ the manifest does not describe -- at minimum, the marimo doing the
+ launching. An overlay is how those packages reach the process:
+
+ * The backend resolves the overlay into an ephemeral environment created
+ from the script environment's interpreter. That environment chains the
+ script environment's packages, so the notebook's dependencies are still
+ importable.
+ * An entry here wins over the same package in the script environment, so
+ a version stated in the overlay is the version the process imports.
+ * Nothing is installed into the script environment and the manifest is
+ never edited. The environment the notebook's own tool builds stays
+ byte-identical to the one marimo launches into, which is what lets the
+ two share a cache entry.
+
+ # Properties
+
+ * `runtime` is the marimo the launched process must import, either
+ `marimo[<extras>]==<version>` or `-e <path>` when marimo runs from a
+ development checkout. Every overlay has one; see below.
+ * `command` holds requirements of the marimo *command* being launched,
+ such as `nbformat` for an ipynb export or `playwright` for a
+ thumbnail. These exist only because such a command runs inside the
+ notebook's environment today, and they go away as those commands move
+ into environments marimo owns.
+
+ # What belongs in an overlay
+
+ Only marimo's own requirements. A package the notebook's code imports
+ belongs in the manifest, where a reader, a reviewer, and a plain
+ `uv run notebook.py` can all see it -- add it with `NotebookSandbox.add`
+ instead. If a package is being put here so that some notebook's cells
+ work, it is in the wrong place.
+
+ # Why every launch carries a runtime
+
+ The server and the kernel are one program in two processes: they share
+ message schemas, session semantics, and code paths, so the kernel has to
+ be the same marimo that launched it. The manifest cannot express that.
+ It says `marimo` loosely, because it is a shared file that has no way to
+ know which marimo will open it, and writing `marimo==<version>` there
+ would put one machine's state into a document meant to outlive it. So
+ the version binding lives in the overlay, and it is not optional: a
+ launch without one would run whatever marimo the manifest happened to
+ resolve. A versioned kernel protocol could someday relax this and retire
+ the injection entirely; until then, every launch goes through the layer.
+
+ # Warning
+
+ A backend resolves the overlay against PyPI without seeing what the
+ script environment already contains. For a pixi environment that means
+ the overlay's transitive dependencies arrive as PyPI wheels and shadow
+ any conda-forge build of the same package. This is acceptable for
+ marimo's own dependency tree, which is small and pure-Python; an overlay
+ is not a general bridge between conda and PyPI packaging.
+ """
+
+ runtime: str
+ command: tuple[str, ...] = ()
+
+ @property
+ def requirements(self) -> tuple[str, ...]:
+ """The overlay as requirement strings, runtime first.
+
+ Backends translate these into their own layering flags: uv passes
+ each as `--with` (or `--with-editable` for a local path), and pixi
+ borrows the same uv verb through `pixi exec`.
+ """
+ return (self.runtime, *self.command)
+
+
def runtime_overlay(
- features: Sequence[str] = (),
- additional_deps: Sequence[str] = (),
-) -> list[str]:
- """The requirements marimo layers into a sandbox launch.
-
- marimo itself rides the overlay, pinned to the running version or as
- an editable install from a development checkout, so the launched
- process matches the CLI regardless of what a manifest's `marimo`
- resolves to. Overlay entries never enter the manifest.
+ extras: Sequence[DepExtras] = (),
+ command: Sequence[str] = (),
+) -> RuntimeOverlay:
+ """The overlay binding a launch to the running marimo.
+
+ Resolves the runtime requirement from this process: the installed
+ version, or an editable install of the checkout when marimo is running
+ from source, so that a contributor's sandbox runs their working tree
+ rather than the last release. `extras` are marimo's own extras, such as
+ `lsp` for a process that hosts the language server.
+
+ Requirements are never written to the notebook's manifest; see
+ `RuntimeOverlay`.
"""
- extras = f"[{','.join(features)}]" if features else ""
+ suffix = f"[{','.join(extras)}]" if extras else ""
if is_editable("marimo"):
LOGGER.info("Using editable of marimo for sandbox")
- marimo_dep = f"-e {marimo_dir()}{extras}"
+ runtime = f"-e {marimo_dir()}{suffix}"
else:
- marimo_dep = f"marimo{extras}=={__version__}"
- return [marimo_dep, *additional_deps]
+ runtime = f"marimo{suffix}=={__version__}"
+ return RuntimeOverlay(runtime=runtime, command=tuple(command))
diff --git a/marimo/_environments/pixi.py b/marimo/_environments/pixi.py
new file mode 100644
index 0000000000..2de6a554d3
--- /dev/null
+++ b/marimo/_environments/pixi.py
@@ -0,0 +1,512 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Provision script environments with pixi.
+
+The pixi backend mirrors the uv backend's contract through pixi's
+script commands: `pixi install --script` synchronizes and reports the
+environment, `pixi add --script --pypi` edits the manifest. Launch
+overlays ride uv, invoked through `pixi exec` so pixi remains the only
+required tool: uv's ephemeral `--with` environment chains the conda
+prefix's site-packages, with overlay-first precedence.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from typing import TYPE_CHECKING, Any
+
+from marimo import _loggers
+from marimo._environments.errors import (
+ EnvironmentManagerError,
+ EnvironmentManagerNotFoundError,
+ MissingScriptMetadataError,
+)
+
+if TYPE_CHECKING:
+ from collections.abc import Callable, Mapping, Sequence
+
+ from marimo._environments.environment import Environment, ProcessPlan
+ from marimo._environments.overlay import RuntimeOverlay
+
+LOGGER = _loggers.marimo_logger()
+
+
+class PixiError(EnvironmentManagerError):
+ """Base class for pixi invocation errors."""
+
+
+class PixiNotFoundError(PixiError, EnvironmentManagerNotFoundError):
+ """No pixi executable was found."""
+
+ def __init__(self) -> None:
+ super().__init__(
+ "pixi must be installed to use --sandbox=pixi. "
+ "Install pixi from https://pixi.prefix.dev/latest/installation/"
+ )
+
+
+class PixiUnsupportedVersionError(PixiError):
+ """The installed pixi predates script environments."""
+
+ def __init__(self) -> None:
+ super().__init__(
+ "--sandbox=pixi requires a pixi with `pixi install --script` "
+ "support. Upgrade with `pixi self-update`."
+ )
+
+
+class PixiCommandError(PixiError):
+ """A pixi command exited with a failure."""
+
+ def __init__(
+ self, command: Sequence[str], returncode: int, stderr: str
+ ) -> None:
+ self.command = tuple(command)
+ self.returncode = returncode
+ self.stderr = stderr
+ super().__init__(
+ f"`{' '.join(self.command)}` failed with exit code "
+ f"{returncode}.\n{stderr.strip()}"
+ )
+
+
+class PixiMissingScriptMetadataError(
+ PixiCommandError, MissingScriptMetadataError
+):
+ """The target script has no PEP 723 inline metadata block."""
+
+
+def _command_error(
+ completed: subprocess.CompletedProcess[str],
+) -> PixiCommandError:
+ output = completed.stderr or completed.stdout
+ normalized = " ".join(output.lower().split())
+ error_type: type[PixiCommandError] = PixiCommandError
+ if "does not contain a pep 723 metadata block" in normalized:
+ error_type = PixiMissingScriptMetadataError
+ return error_type(completed.args, completed.returncode, output)
+
+
+def find_pixi_bin() -> str | None:
+ """Path to the pixi executable, or None if not found."""
+ return shutil.which("pixi")
+
+
+def is_pixi_available() -> bool:
+ return find_pixi_bin() is not None
+
+
+def require_pixi_bin() -> str:
+ """Path to the pixi executable; raises `PixiNotFoundError`."""
+ pixi_bin = find_pixi_bin()
+ if pixi_bin is None:
+ raise PixiNotFoundError()
+ return pixi_bin
+
+
+def ensure_supported_pixi() -> None:
+ """Raise unless the invoked pixi understands `install --script`.
+
+ Probe the capability rather than coupling marimo to a Pixi version.
+ """
+ completed = subprocess.run(
+ [require_pixi_bin(), "install", "--help"],
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ 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.
+_INSTALLED_AT = re.compile(r"installed at '(.+)'\.\s*$", re.MULTILINE)
+_ANSI = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+
+
+def sync(
+ script: str,
+ *,
+ cwd: str | None = None,
+ on_output: Callable[[str], None] | None = None,
+ on_command: Callable[[Sequence[str]], None] | None = None,
+) -> Environment:
+ """Makes the script's environment match its metadata.
+
+ Runs `pixi install --script` from `cwd`, normally the notebook's
+ directory. Returns the installed environment; pixi does not report
+ what changed, so the action is always `updated` and restarts hinge
+ on interpreter identity. Raises `PixiCommandError` on failure and
+ never mutates `script`.
+ """
+ from marimo._environments.environment import Environment
+
+ args = [
+ require_pixi_bin(),
+ "install",
+ "--script",
+ os.path.abspath(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",
+ )
+ 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)
+ match = _INSTALLED_AT.search(report)
+ if match is None:
+ raise PixiError(
+ "pixi installed the script environment but did not report "
+ f"its location.\n{report.strip()}"
+ )
+ root = match.group(1)
+ python = _env_python(root)
+ if python is None:
+ raise PixiError(f"No interpreter found in the environment at {root}")
+ return Environment(python=python, root=root, action="updated")
+
+
+def add(
+ script: str,
+ package: str,
+ *,
+ cwd: str,
+ upgrade: bool = False,
+ on_output: Callable[[str], None] | None = None,
+ on_command: Callable[[Sequence[str]], None] | None = None,
+) -> None:
+ """Add a PyPI dependency to a script, or refresh it when upgrading.
+
+ `pixi update` takes package names, not requirements; a constrained
+ upgrade rewrites the manifest entry through `pixi add` instead, and
+ the next solve advances within the new constraint.
+ """
+ if upgrade and re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", package):
+ args = [
+ require_pixi_bin(),
+ "update",
+ "--script",
+ os.path.abspath(script),
+ package,
+ ]
+ else:
+ args = [
+ require_pixi_bin(),
+ "add",
+ "--script",
+ os.path.abspath(script),
+ "--pypi",
+ package,
+ ]
+ _run(
+ args,
+ cwd=cwd,
+ on_output=on_output,
+ on_command=on_command,
+ )
+
+
+def remove(
+ script: str,
+ package: str,
+ *,
+ cwd: str,
+ on_output: Callable[[str], None] | None = None,
+ on_command: Callable[[Sequence[str]], None] | None = None,
+) -> None:
+ """Remove a direct PyPI dependency from a script."""
+ args = [
+ require_pixi_bin(),
+ "remove",
+ "--script",
+ os.path.abspath(script),
+ "--pypi",
+ package,
+ ]
+ _run(
+ args,
+ cwd=cwd,
+ on_output=on_output,
+ on_command=on_command,
+ )
+
+
+def list_script_packages(script: str, *, cwd: str) -> list[dict[str, Any]]:
+ """Return pixi's structured resolved package records for a script."""
+ args = [
+ require_pixi_bin(),
+ "list",
+ "--script",
+ os.path.abspath(script),
+ "--json",
+ ]
+ completed = _run(args, cwd=cwd)
+ import json
+
+ try:
+ records = json.loads(completed.stdout)
+ except json.JSONDecodeError as error:
+ raise PixiError("pixi returned an unreadable package list") from error
+ if not isinstance(records, list):
+ raise PixiError("pixi returned an invalid package list")
+ return [record for record in records if isinstance(record, dict)]
+
+
+def tree_script_packages(script: str, *, cwd: str) -> str:
+ """Return pixi's resolved dependency tree for a script."""
+ args = [
+ require_pixi_bin(),
+ "tree",
+ "--no-install",
+ "--color",
+ "never",
+ "--script",
+ os.path.abspath(script),
+ ]
+ return _run(args, cwd=cwd).stdout
+
+
+def _run(
+ args: Sequence[str],
+ *,
+ cwd: str,
+ on_output: Callable[[str], None] | None = None,
+ on_command: Callable[[Sequence[str]], None] | None = None,
+) -> subprocess.CompletedProcess[str]:
+ 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",
+ )
+ 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)
+ return completed
+
+
+def ensure_marimo(
+ path: str,
+ *,
+ on_command: Callable[[Sequence[str]], None] | None = None,
+) -> None:
+ """Add marimo to the script metadata if not already a dependency.
+
+ The manifest carries a loose requirement so
+ `pixi run --script notebook.py` works standalone; the launch overlay
+ supplies the running version (or the development checkout), never the
+ manifest. Creates the metadata block if the file has none. No-op for
+ non-`.py` targets and for missing or empty files, whose block is the
+ notebook serializer's to create.
+ """
+ from marimo._environments.script_metadata import (
+ ensure_metadata_block,
+ should_add_marimo,
+ )
+
+ if not should_add_marimo(path):
+ return
+
+ ensure_metadata_block(path)
+
+ args = [
+ require_pixi_bin(),
+ "add",
+ "--script",
+ os.path.abspath(path),
+ "--pypi",
+ "marimo",
+ ]
+ 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=os.path.dirname(os.path.abspath(path)),
+ timeout=60,
+ start_new_session=os.name != "nt",
+ )
+ if completed.returncode != 0:
+ raise _command_error(completed)
+
+
+# The uv that applies launch overlays, fetched through `pixi exec` so
+# pixi stays the only required tool. The floor is where the behavior
+# this relies on -- `uv run --python <conda-python> --with ...` chaining
+# the conda prefix's site-packages -- was verified.
+UV_OVERLAY_SPEC = "uv>=0.12"
+
+
+# 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.
+_ACTIVATE_NOTEBOOK = """\
+import json, os, sys
+root, paths = json.loads(sys.argv[1])
+for key in tuple(os.environ):
+ if key.startswith("CONDA_PREFIX_") or key in (
+ "PIXI_PROJECT_MANIFEST", "PIXI_PROJECT_ROOT", "PIXI_PROJECT_NAME",
+ "PIXI_PROJECT_VERSION", "PIXI_ENVIRONMENT_NAME", "PIXI_IN_SHELL",
+ "PIXI_PROMPT",
+ ):
+ os.environ.pop(key, None)
+os.environ.update(CONDA_PREFIX=root, CONDA_DEFAULT_ENV=os.path.basename(root), CONDA_SHLVL="1")
+overlay_bin = os.path.dirname(sys.executable)
+os.environ["PATH"] = os.pathsep.join(dict.fromkeys([
+ overlay_bin, *paths, *os.environ.get("PATH", "").split(os.pathsep)
+]))
+os.execv(sys.executable, [sys.executable, *sys.argv[2:]])
+"""
+
+
+def launch(
+ environment: Environment,
+ args: Sequence[str],
+ *,
+ overlay: RuntimeOverlay,
+ base_env: Mapping[str, str] | None = None,
+) -> ProcessPlan:
+ """Plans running `python <args...>` inside the environment.
+
+ A pixi script environment is a conda environment. Its conventional prefix
+ variables and executable paths are restored after `pixi exec` activates
+ its uv tool environment, with uv's runtime overlay first on PATH.
+ Notebook activation scripts are not evaluated by this launch path.
+
+ The overlay is layered by uv, which pixi supplies through
+ `pixi exec` so that pixi stays the only tool a pixi sandbox needs:
+
+ pixi exec --spec "uv>=0.12" uv run --no-project \
+ --python <prefix>/bin/python \
+ --with marimo==<version> -- python <args...>
+
+ uv resolves the overlay into an ephemeral environment created from
+ the conda interpreter, which chains the prefix's site-packages
+ behind it. Neither the environment nor the manifest is modified.
+ See `RuntimeOverlay`, whose warning about conda and PyPI packaging
+ applies here.
+ """
+ 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)
+ env["CONDA_PREFIX"] = environment.root
+ env["CONDA_DEFAULT_ENV"] = os.path.basename(environment.root)
+ path_entries = _activation_path_entries(environment.root)
+ path = env.get("PATH")
+ if path:
+ path_entries = (*path_entries, path)
+ env["PATH"] = os.pathsep.join(path_entries)
+ return ProcessPlan(
+ argv=(
+ require_pixi_bin(),
+ "exec",
+ "--spec",
+ UV_OVERLAY_SPEC,
+ "uv",
+ "run",
+ "--no-project",
+ "--python",
+ environment.python,
+ *_with_args(overlay.requirements),
+ "--",
+ "python",
+ "-c",
+ _ACTIVATE_NOTEBOOK,
+ json.dumps(
+ [environment.root, _activation_path_entries(environment.root)]
+ ),
+ *args,
+ ),
+ env=env,
+ start_new_session=True,
+ )
+
+
+def _activation_path_entries(root: str) -> tuple[str, ...]:
+ """Executable paths exposed by a conventional conda prefix."""
+ if os.name == "nt":
+ import ntpath
+
+ return (
+ root,
+ ntpath.join(root, "Library", "mingw-w64", "bin"),
+ ntpath.join(root, "Library", "usr", "bin"),
+ ntpath.join(root, "Library", "bin"),
+ ntpath.join(root, "Scripts"),
+ ntpath.join(root, "bin"),
+ )
+ return (os.path.join(root, "bin"),)
+
+
+def command_env() -> dict[str, str]:
+ """Environment for pixi script commands.
+
+ Drops activation state from any enclosing pixi, conda, or uv
+ environment so the script's own manifest decides everything.
+ """
+ env = os.environ.copy()
+ for variable in (
+ "VIRTUAL_ENV",
+ "UV_PROJECT_ENVIRONMENT",
+ "CONDA_PREFIX",
+ "CONDA_DEFAULT_ENV",
+ "PIXI_PROJECT_MANIFEST",
+ "PIXI_PROJECT_ROOT",
+ "PIXI_ENVIRONMENT_NAME",
+ "PIXI_IN_SHELL",
+ ):
+ env.pop(variable, None)
+ return env
+
+
+def _env_python(root: str) -> str | None:
+ """The environment's interpreter within a conda prefix layout."""
+ if os.name == "nt":
+ candidates = (
+ os.path.join(root, "python.exe"),
+ os.path.join(root, "Scripts", "python.exe"),
+ )
+ else:
+ candidates = (
+ os.path.join(root, "bin", "python"),
+ os.path.join(root, "bin", "python3"),
+ )
+ for candidate in candidates:
+ if os.path.exists(candidate):
+ return candidate
+ return None
diff --git a/marimo/_environments/sandbox.py b/marimo/_environments/sandbox.py
new file mode 100644
index 0000000000..7729cd3c76
--- /dev/null
+++ b/marimo/_environments/sandbox.py
@@ -0,0 +1,641 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""The notebook-bound interface to a sandbox environment manager.
+
+Callers use feature operations; synchronization, Manifest carriers, and
+manager-specific commands stay behind this module. A notebook sandbox retains
+only its source binding and latest Environment. Carriers remain scoped to one
+operation and are cleaned by `script_metadata`.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+import tempfile
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, Protocol
+
+from marimo._environments import script_metadata
+
+if TYPE_CHECKING:
+ from collections.abc import Mapping, Sequence
+
+ from marimo._environments.environment import Environment, ProcessPlan
+ from marimo._environments.overlay import RuntimeOverlay
+ from marimo._environments.script_metadata import MaterializedScript
+ from marimo._utils.uv_tree import DependencyTreeNode
+
+Backend = Literal["uv", "pixi"]
+SandboxOperation = Literal["prepare", "add", "upgrade", "remove", "sync"]
+LogCallback = Callable[[str], None]
+ENVIRONMENT_PYTHON = "MARIMO_SANDBOX_ENVIRONMENT_PYTHON"
+ENVIRONMENT_ROOT = "MARIMO_SANDBOX_ENVIRONMENT_ROOT"
+MANIFEST_SOURCE = "MARIMO_SANDBOX_MANIFEST_SOURCE"
+
+
+@dataclass(frozen=True)
+class ResolvedPackage:
+ """A package installed in the synchronized Environment."""
+
+ name: str
+ version: str
+
+
+@dataclass(frozen=True)
+class PackageState:
+ """The package-panel view of a synchronized notebook sandbox."""
+
+ packages: tuple[ResolvedPackage, ...]
+ tree: DependencyTreeNode | None
+
+
+@dataclass(frozen=True)
+class SandboxCommand:
+ """A backend command executed on behalf of a sandbox operation."""
+
+ backend: Backend
+ operation: SandboxOperation
+ argv: tuple[str, ...]
+
+
+class SandboxReporter(Protocol):
+ """Receives operational sandbox reports outside backend output."""
+
+ def report(self, command: SandboxCommand) -> None: ...
+
+
+class NullSandboxReporter:
+ """Suppress sandbox operational reports."""
+
+ def report(self, command: SandboxCommand) -> None:
+ del command
+
+
+class TerminalSandboxReporter:
+ """Render sandbox operations to the terminal."""
+
+ def report(self, command: SandboxCommand) -> None:
+ from marimo._cli.print import echo, muted
+
+ labels: dict[SandboxOperation, str] = {
+ "prepare": "Preparing sandbox",
+ "add": "Adding to sandbox",
+ "upgrade": "Upgrading in sandbox",
+ "remove": "Removing from sandbox",
+ "sync": "Synchronizing sandbox",
+ }
+ echo(
+ f"{labels[command.operation]}: "
+ f"{muted(shlex.join(_redact_command(command.argv)))}",
+ err=True,
+ )
+
+
+class BackendAdapter(Protocol):
+ """Operations supplied by a sandbox environment manager."""
+
+ name: Backend
+
+ def ensure_available(self) -> None: ...
+
+ def prepare_source(self, source: str) -> None: ...
+
+ def add(
+ self,
+ target: MaterializedScript,
+ package: str,
+ *,
+ upgrade: bool,
+ on_output: LogCallback | None,
+ ) -> None: ...
+
+ def remove(
+ self,
+ target: MaterializedScript,
+ package: str,
+ *,
+ on_output: LogCallback | None,
+ ) -> None: ...
+
+ def sync(
+ self,
+ target: MaterializedScript,
+ *,
+ python_override: str | None,
+ on_output: LogCallback | None,
+ active_environment: Environment | None = None,
+ ) -> Environment: ...
+
+ def packages(
+ self,
+ target: MaterializedScript,
+ environment: Environment | None,
+ ) -> PackageState: ...
+
+ def launch(
+ self,
+ environment: Environment,
+ args: Sequence[str],
+ *,
+ overlay: RuntimeOverlay,
+ base_env: Mapping[str, str] | None,
+ ) -> ProcessPlan: ...
+
+
+class NotebookSandbox:
+ """A notebook's selected environment manager and latest Environment.
+
+ `launch`, `add`, and `remove` synchronize internally. Package inspection is
+ read-only. Rebinding changes the durable source, while package mutations
+ continue to synchronize the retained Environment. The next launch acquires
+ the new source's path-derived environment identity. No Carrier is retained.
+ """
+
+ def __init__(
+ self,
+ source: str | None,
+ backend: Backend,
+ *,
+ environment: Environment | None = None,
+ adapter: BackendAdapter | None = None,
+ reporter: SandboxReporter | None = None,
+ ) -> None:
+ self._temporary_directory: tempfile.TemporaryDirectory[str] | None = (
+ None
+ )
+ self._source = self._bind_source(source)
+ self._persist_on_rebind = source is None
+ self._reporter = reporter or TerminalSandboxReporter()
+ if adapter is None:
+ from marimo._environments.backends import adapter_for
+
+ adapter = adapter_for(backend, self._reporter)
+ self._adapter = adapter
+ if self._adapter.name != backend:
+ raise ValueError(
+ f"Adapter {self._adapter.name!r} cannot manage {backend!r}"
+ )
+ self._environment = environment
+ self._environment_source = (
+ self._source if environment is not None else None
+ )
+
+ @classmethod
+ def from_running_process(
+ cls,
+ source: str | None,
+ backend: Backend,
+ *,
+ reporter: SandboxReporter | None = None,
+ ) -> NotebookSandbox:
+ """Bind to the Environment identity exported by `launch`."""
+ import os
+
+ from marimo._environments.environment import Environment
+
+ python = os.environ.get(ENVIRONMENT_PYTHON)
+ root = os.environ.get(ENVIRONMENT_ROOT)
+ environment = (
+ Environment(python=python, root=root, action="unchanged")
+ if python is not None and root is not None
+ else None
+ )
+ manifest = source or os.environ.get(MANIFEST_SOURCE)
+ if manifest is None:
+ raise RuntimeError("Running sandbox did not export its manifest")
+ sandbox = cls(
+ manifest,
+ backend,
+ environment=environment,
+ reporter=reporter,
+ )
+ # The launcher owns cleanup; the child only persists the manifest
+ # when the unnamed notebook is first saved.
+ sandbox._persist_on_rebind = source is None
+ return sandbox
+
+ @property
+ def backend(self) -> Backend:
+ return self._adapter.name
+
+ @property
+ def source(self) -> str:
+ return self._source
+
+ @property
+ def environment(self) -> Environment | None:
+ return self._environment
+
+ @property
+ def environment_source(self) -> str | None:
+ """The source that realized the current Environment, if known."""
+ return self._environment_source
+
+ def rebind(self, source: str, *, persist_manifest: bool = True) -> None:
+ """Bind future operations without changing the running Environment.
+
+ The session persists an unnamed Manifest before notifying its kernel.
+ The kernel only follows that binding (`persist_manifest=False`): the
+ session may already have released the temporary Manifest.
+ """
+ import os
+
+ absolute = os.path.abspath(source)
+ if absolute == self._source:
+ return
+ if self._persist_on_rebind:
+ if persist_manifest:
+ script_metadata.copy_metadata(self._source, absolute)
+ self._persist_on_rebind = False
+ if self._temporary_directory is not None:
+ self._temporary_directory.cleanup()
+ self._temporary_directory = None
+ self._source = absolute
+
+ def close(self) -> None:
+ """Release an owned Manifest for an unnamed notebook, if any."""
+ if self._temporary_directory is not None:
+ self._temporary_directory.cleanup()
+ self._temporary_directory = None
+
+ def _bind_source(self, source: str | None) -> str:
+ import os
+
+ if source is not None:
+ return os.path.abspath(source)
+
+ self._temporary_directory = tempfile.TemporaryDirectory(
+ prefix="marimo-sandbox-"
+ )
+ path = os.path.join(self._temporary_directory.name, "notebook.py")
+ project = script_metadata.with_python_version_requirement(
+ {"dependencies": ["marimo"]}
+ )
+ with open(path, "w", encoding="utf-8") as manifest:
+ manifest.write(script_metadata.dumps(project) + "\n")
+ return path
+
+ def launch(
+ self,
+ args: Sequence[str],
+ *,
+ overlay: RuntimeOverlay,
+ base_env: Mapping[str, str] | None = None,
+ python_override: str | None = None,
+ on_output: LogCallback | None = None,
+ ) -> ProcessPlan:
+ """Synchronize and plan `python <args...>` in the Environment."""
+ self._adapter.ensure_available()
+ script_metadata.ensure_metadata_block(self._source)
+ self._adapter.prepare_source(self._source)
+ environment = self._sync(
+ python_override=python_override, on_output=on_output
+ )
+ plan = self._adapter.launch(
+ environment,
+ args,
+ overlay=overlay,
+ base_env=base_env,
+ )
+ plan.env[ENVIRONMENT_PYTHON] = environment.python
+ plan.env[ENVIRONMENT_ROOT] = environment.root
+ plan.env[MANIFEST_SOURCE] = self._source
+ return plan
+
+ def add(
+ self,
+ package: str,
+ *,
+ upgrade: bool = False,
+ on_output: LogCallback | None = None,
+ ) -> None:
+ """Add or refresh a direct Manifest dependency and synchronize.
+
+ A bare requirement (`polars`, `duckdb[spatial]`) is pinned to the
+ version the synchronized Environment resolved (`polars==1.2.3`),
+ so a shared notebook reproduces this Environment without a
+ lockfile. Requirements the caller constrains -- version
+ specifiers, URLs, direct references -- are written as given, and
+ marimo itself is never pinned: its version belongs to the
+ launching runtime.
+ """
+ self._adapter.ensure_available()
+ bare = _bare_requirement(package)
+ if bare is not None and not bare.extras:
+ # Re-adding a package without extras must not silently remove
+ # extras already declared by the notebook when the resolved
+ # version is pinned below.
+ bare = self._declared_bare(bare) or bare
+ request = package
+ if bare is not None and upgrade:
+ # Both managers leave an existing Manifest entry alone when a
+ # bare name is re-added, so a pin written by an earlier add
+ # would hold the version forever. Reopen it to `>=current`;
+ # the pin below then records what the new solve chose.
+ reopened = self._reopened_requirement(bare)
+ if reopened is not None:
+ bare, request = reopened
+ with script_metadata.metadata_transaction(self._source):
+ with script_metadata.materialized_for_edit(self._source) as target:
+ self._adapter.add(
+ target,
+ request,
+ upgrade=upgrade,
+ on_output=on_output,
+ )
+ # Pixi can resolve a newer version than the installed one. Pin
+ # that resolution before syncing so success means the final
+ # manifest, not an intermediate constraint, was installed.
+ if bare is not None:
+ self._pin(bare)
+ self._sync(
+ on_output=on_output, active_environment=self._environment
+ )
+
+ def remove(
+ self,
+ package: str,
+ *,
+ on_output: LogCallback | None = None,
+ ) -> None:
+ """Remove a direct Manifest dependency and synchronize."""
+ package = _normalize_dependency_name(package)
+ if package == "marimo":
+ raise script_metadata.ScriptMetadataError(
+ "marimo is managed by the sandbox runtime and cannot be removed"
+ )
+ self._adapter.ensure_available()
+ with script_metadata.metadata_transaction(self._source):
+ with script_metadata.materialized_for_edit(self._source) as target:
+ self._adapter.remove(target, package, on_output=on_output)
+ self._sync(
+ on_output=on_output, active_environment=self._environment
+ )
+
+ def record_dependencies(
+ self,
+ packages: Sequence[str],
+ *,
+ runtime_versions: Mapping[str, str],
+ ) -> None:
+ """Record imported packages without reinstalling the environment.
+
+ Existing declarations retain their constraints, extras, markers, and
+ sources. Versions come from the backend or the calling kernel's
+ runtime overlay, which can supply otherwise undeclared dependencies.
+ """
+ requested = {
+ _normalize_dependency_name(package) for package in packages
+ }
+ if not requested:
+ return
+ requested -= {
+ _normalize_dependency_name(dependency)
+ for dependency in self._declared_dependencies()
+ } | {"marimo"}
+ if not requested:
+ return
+ versions = {
+ _normalize_dependency_name(package.name): package.version
+ for package in self.packages().packages
+ }
+ versions.update(
+ (_normalize_dependency_name(name), version)
+ for name, version in runtime_versions.items()
+ )
+ requirements = [
+ f"{name}=={versions[name]}"
+ for name in sorted(requested)
+ if versions.get(name)
+ ]
+ if not requirements:
+ return
+ with script_metadata.materialized_for_edit(self._source) as target:
+ for requirement in requirements:
+ self._adapter.add(
+ target, requirement, upgrade=False, on_output=None
+ )
+
+ def packages(
+ self, *, on_output: LogCallback | None = None
+ ) -> PackageState:
+ """Inspect the bound Manifest without synchronizing its Environment."""
+ del on_output
+ self._adapter.ensure_available()
+ 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)
+
+ def _reopened_requirement(
+ self, bare: _BareRequirement
+ ) -> tuple[_BareRequirement, str] | None:
+ """A `name>=current` rewrite that lets an upgrade's solve advance.
+
+ The floor comes from the Manifest's exact pin when one is
+ declared (keeping its extras), otherwise from the synchronized
+ Environment. Returns the requirement to pin afterwards and the
+ rewrite, or None when no current version is known; the Manifest
+ is then already open enough for the solve to move.
+ """
+ declared = self._declared_pin(bare)
+ if declared is not None:
+ pinned, version = declared
+ return pinned, f"{pinned.text}>={_floor(version)}"
+ resolved = self._resolved_version(bare.name)
+ if resolved is not None:
+ return bare, f"{bare.text}>={_floor(resolved)}"
+ return None
+
+ def _declared_bare(
+ self, bare: _BareRequirement
+ ) -> _BareRequirement | None:
+ """The Manifest's spelling of a package name and extras, if any."""
+ for dependency in self._declared_dependencies():
+ match = _NAMED_REQUIREMENT.match(dependency)
+ if match is None:
+ continue
+ if _normalize_dependency_name(match.group("name")) != bare.name:
+ continue
+ extras = match.group("extras") or ""
+ return _BareRequirement(
+ text=f"{match.group('name')}{extras}",
+ name=bare.name,
+ extras=extras,
+ )
+ return None
+
+ def _declared_pin(
+ self, bare: _BareRequirement
+ ) -> tuple[_BareRequirement, str] | None:
+ """The Manifest's exact pin for a package, if it declares one."""
+ for dependency in self._declared_dependencies():
+ match = _EXACT_PIN.match(dependency)
+ if match is None:
+ continue
+ if _normalize_dependency_name(match.group("name")) != bare.name:
+ continue
+ extras = (
+ bare.extras if bare.extras else (match.group("extras") or "")
+ )
+ return (
+ _BareRequirement(
+ text=f"{match.group('name')}{extras}",
+ name=bare.name,
+ extras=extras,
+ ),
+ match.group("version"),
+ )
+ return None
+
+ def _declared_dependencies(self) -> list[str]:
+ """The Manifest's direct dependency strings."""
+ with script_metadata.materialized_for_environment(
+ self._source
+ ) as target:
+ try:
+ with open(target.path, encoding="utf-8") as file:
+ project = script_metadata.loads(file.read()) or {}
+ except (OSError, ValueError):
+ return []
+ dependencies = project.get("dependencies", [])
+ if not isinstance(dependencies, list):
+ return []
+ return [str(dependency) for dependency in dependencies]
+
+ def _pin(self, bare: _BareRequirement) -> None:
+ """Record the resolved version before synchronizing the Manifest."""
+ version = self._resolved_version(bare.name)
+ if version is None:
+ # Not resolved on this platform (e.g. excluded by a marker);
+ # the open requirement stands.
+ return
+ with script_metadata.materialized_for_edit(self._source) as target:
+ self._adapter.add(
+ target,
+ f"{bare.text}=={version}",
+ upgrade=False,
+ on_output=None,
+ )
+
+ def _resolved_version(self, name: str) -> str | None:
+ """The package's version resolved from the current Manifest."""
+ with script_metadata.materialized_for_environment(
+ self._source
+ ) as target:
+ state = self._adapter.packages(target, self._environment)
+ for package in state.packages:
+ if _normalize_dependency_name(package.name) == name:
+ return package.version or None
+ return None
+
+ def _sync(
+ self,
+ *,
+ python_override: str | None = None,
+ on_output: LogCallback | None = None,
+ active_environment: Environment | None = None,
+ ) -> Environment:
+ with script_metadata.materialized_for_environment(
+ self._source
+ ) as target:
+ environment = self._adapter.sync(
+ target,
+ python_override=python_override,
+ on_output=on_output,
+ active_environment=active_environment,
+ )
+ self._environment = environment
+ self._environment_source = self._source
+ return environment
+
+
+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:
+ return requirement.lower()
+ return re.sub(r"[-_.]+", "-", match.group(0)).lower()
+
+
+@dataclass(frozen=True)
+class _BareRequirement:
+ """A requirement that names a package without constraining it."""
+
+ # The requirement as requested: name plus any extras.
+ text: str
+ # The PEP 503 normalized package name.
+ name: str
+ extras: str
+
+
+_BARE_REQUIREMENT = re.compile(
+ r"^\s*(?P<name>[A-Za-z0-9][A-Za-z0-9._-]*)\s*(?P<extras>\[[^\]]*\])?\s*$"
+)
+
+_NAMED_REQUIREMENT = re.compile(
+ r"^\s*(?P<name>[A-Za-z0-9][A-Za-z0-9._-]*)\s*(?P<extras>\[[^\]]*\])?"
+)
+
+# An exact pin holds one release: `name==1.2.3`, optionally with extras,
+# an epoch, or a local segment -- but not a wildcard (`==1.*`), which is
+# a range.
+_EXACT_PIN = re.compile(
+ r"^\s*(?P<name>[A-Za-z0-9][A-Za-z0-9._-]*)\s*(?P<extras>\[[^\]]*\])?"
+ r"\s*==\s*(?P<version>[A-Za-z0-9!+.]+)\s*$"
+)
+
+
+def _bare_requirement(package: str) -> _BareRequirement | None:
+ """Parse `name` or `name[extras]`; None for anything more specific.
+
+ marimo also returns None: its version is the runtime's to manage,
+ never the Manifest's.
+ """
+ match = _BARE_REQUIREMENT.match(package)
+ if match is None:
+ return None
+ name = _normalize_dependency_name(match.group("name"))
+ if name == "marimo":
+ return None
+ extras = match.group("extras") or ""
+ return _BareRequirement(
+ text=f"{match.group('name')}{extras}", name=name, extras=extras
+ )
+
+
+def _floor(version: str) -> str:
+ """A version usable as a `>=` floor.
+
+ PEP 440 forbids local segments (`1.2+cpu`) in ordered comparisons,
+ so the floor is the public part.
+ """
+ return version.split("+", 1)[0]
+
+
+_URL_CREDENTIALS = re.compile(
+ r"(?P<scheme>[A-Za-z][A-Za-z0-9+.-]*://)[^/@\s]+@"
+)
+
+
+def _redact_command(command: Sequence[str]) -> list[str]:
+ """Redact URL userinfo before rendering a command."""
+ return [_redact_url_credentials(argument) for argument in command]
+
+
+def _redact_url_credentials(value: str) -> str:
+ """Replace URL userinfo embedded in text with a placeholder."""
+ return _URL_CREDENTIALS.sub(r"\g<scheme>***@", value)
diff --git a/marimo/_environments/script_metadata.py b/marimo/_environments/script_metadata.py
index d5527e7766..05d9a79578 100644
--- a/marimo/_environments/script_metadata.py
+++ b/marimo/_environments/script_metadata.py
@@ -2,16 +2,16 @@
"""The PEP 723 inline script metadata block.
This module is the single reader and writer for the `# /// script` block in
-marimo notebooks. In-place edits of a user's file delegate to
-`uv ... --script` so uv owns the TOML edit and the user's formatting
+marimo notebooks. In-place edits of a user's file delegate to the selected
+environment manager so it owns the TOML edit and the user's formatting
survives; whole-block generation (converters, codegen, export) serializes
with tomlkit.
Markdown notebooks (.md/.qmd) carry the block in their frontmatter; edit
verbs round-trip the header verbatim through a carrier, a hidden sidecar
-next to the notebook, so uv anchors relative paths in the metadata
-against the notebook's directory. uv also runs from that directory, so
-directory-scoped uv configuration applies.
+next to the notebook, so the manager anchors relative paths in the metadata
+against the notebook's directory. The manager also runs from that directory,
+so directory-scoped configuration applies.
"""
from __future__ import annotations
@@ -31,7 +31,10 @@ from pathlib import Path
from typing import TYPE_CHECKING, Any
from marimo import _loggers
-from marimo._environments.errors import EnvironmentManagerError
+from marimo._environments.errors import (
+ EnvironmentManagerError,
+ SandboxRestartRequired,
+)
from marimo._environments.uv import (
UvError,
script_command_env,
@@ -98,6 +101,99 @@ def replace_block(script: str, block: str) -> str:
return re.sub(REGEX, lambda _: block, script, count=1)
+def _metadata_block(path: str) -> str:
+ with materialized_for_environment(path) as target:
+ content = Path(target.path).read_text(encoding="utf-8")
+ match = re.search(REGEX, content)
+ return match.group(0) if match is not None else ""
+
+
+def metadata_transaction(path: str) -> Iterator[None]:
+ """Restore the previous manifest if a dependency mutation fails.
+
+ Managers can save requirements before discovering they cannot solve them.
+ Restore only metadata, preserving notebook code and other frontmatter
+ edited while the manager was running. This does not undo partial changes
+ to an environment made by the manager.
+ """
+ block = _metadata_block(path)
+ try:
+ yield
+ except SandboxRestartRequired:
+ # Synchronization succeeded; the live kernel uses a different prefix.
+ raise
+ except (Exception, KeyboardInterrupt):
+ if _metadata_block(path) == block:
+ raise
+ with materialized_for_edit(path) as target:
+ file = Path(target.path)
+ current = file.read_text(encoding="utf-8")
+ restored = replace_block(current, block)
+ if restored != current:
+ file.write_text(restored, encoding="utf-8")
+ raise
+
+
+def copy_metadata(source: str, destination: str) -> None:
+ """Copy one notebook's PEP 723 block into another notebook.
+
+ This is a local Manifest operation: it does not invoke an environment
+ manager or synchronize an Environment. It is used when an unnamed
+ notebook's owned temporary Manifest becomes file-backed.
+ """
+ with materialized_for_environment(source) as source_target:
+ with open(source_target.path, encoding="utf-8") as source_file:
+ match = re.search(REGEX, source_file.read())
+ if match is None:
+ raise ScriptMetadataError(f"No script metadata found in {source}")
+ block = match.group(0)
+
+ with materialized_for_edit(destination) as destination_target:
+ with open(destination_target.path, encoding="utf-8") as target_file:
+ content = target_file.read()
+ if loads(content) is not None:
+ content = replace_block(content, block)
+ elif content.startswith("#!"):
+ shebang, _, rest = content.partition("\n")
+ content = f"{shebang}\n{block}\n{rest}"
+ else:
+ content = f"{block}\n{content}"
+ with open(
+ destination_target.path, "w", encoding="utf-8"
+ ) as target_file:
+ target_file.write(content)
+
+
+def ensure_metadata_block(path: str) -> None:
+ """Create an empty dependency manifest when a notebook has none.
+
+ The manifest module owns this structural write; environment managers
+ only edit the materialized script it gives them.
+ """
+ if path.endswith((".md", ".qmd")):
+ front = _read_frontmatter(path)
+ if loads(front.header) is None:
+ header = wrap_block("dependencies = []") + "\n" + front.header
+ _write_frontmatter(path, front, header)
+ return
+ if not path.endswith(".py"):
+ return
+ with open(path, encoding="utf-8") as f:
+ script = f.read()
+ if loads(script) is not None:
+ return
+
+ block = wrap_block("dependencies = []") + "\n"
+ if script.startswith("#!"):
+ shebang, _, rest = script.partition("\n")
+ script = shebang + "\n" + block + rest
+ else:
+ script = block + script
+ with open(path, "w", encoding="utf-8") as f:
+ f.write(script)
+
+
def with_python_version_requirement(project: dict[str, Any]) -> dict[str, Any]:
# TODO(akshayka): consider locking the Python version for greater
# reproducibility, instead of returning a lowerbound
@@ -154,23 +250,37 @@ def remove_dependencies(
_edit(path, edit)
-def ensure_marimo(path: str) -> None:
- """Add marimo to the script metadata if it is not already a dependency.
+def should_add_marimo(path: str) -> bool:
+ """Whether `ensure_marimo` has work to do.
- Creates the metadata block if the file has none. No-op for non-`.py`
- targets and for missing or empty files, whose block is the notebook
- serializer's to create.
+ False for non-`.py` targets and for missing or empty files, whose
+ block is the notebook serializer's to create, and for manifests
+ that already declare marimo.
"""
if not path.endswith(".py"):
- return
+ return False
if not os.path.exists(path) or os.path.getsize(path) == 0:
- return
+ return False
from marimo._utils.inline_script_metadata import (
has_marimo_in_script_metadata,
)
- if has_marimo_in_script_metadata(path) is True:
+ return has_marimo_in_script_metadata(path) is not True
+
+
+def ensure_marimo(
+ path: str,
+ *,
+ on_command: Callable[[Sequence[str]], None] | None = None,
+) -> None:
+ """Add marimo to the script metadata if it is not already a dependency.
+
+ Creates the metadata block if the file has none. No-op for non-`.py`
+ targets and for missing or empty files, whose block is the notebook
+ serializer's to create.
+ """
+ if not should_add_marimo(path):
return
def edit(target: str, cwd: str) -> None:
@@ -179,6 +289,7 @@ def ensure_marimo(path: str) -> None:
env=script_command_env(),
timeout=30,
cwd=cwd,
+ on_command=on_command,
)
_edit(path, edit)
@@ -217,18 +328,12 @@ def ensure_requires_python(path: str) -> None:
def _edit(path: str, edit: Callable[[str, str], None]) -> None:
"""Apply an edit and normalize expected operational failures.
- Edits receive the file uv operates on and the working directory for
- the uv invocation, which is always the notebook's own directory so
- that directory-scoped uv configuration is discovered.
+ Edits receive the materialized script and the notebook's own directory,
+ so manager-specific directory configuration is discovered.
"""
try:
- if path.endswith((".md", ".qmd")):
- _edit_frontmatter(path, edit)
- else:
- # uv resolves a relative --script target against the cwd this
- # module pins, so hand it an absolute path.
- absolute = os.path.abspath(path)
- edit(absolute, os.path.dirname(absolute))
+ with materialized_for_edit(path) as target:
+ edit(target.path, target.directory)
except (UvError, subprocess.TimeoutExpired, OSError) as error:
raise ScriptMetadataError(
f"Failed to update script metadata for {path}: {error}"
@@ -371,25 +476,10 @@ def _carrier(
LOGGER.debug("Could not remove carrier %s", target)
-def _edit_frontmatter(path: str, edit: Callable[[str, str], None]) -> None:
- """Edits metadata carried in markdown frontmatter.
-
- The header is materialized verbatim as a carrier next to the
- notebook, so uv resolves relative paths in the metadata against the
- notebook's directory. Each edit gets its own carrier, deleted when
- the edit finishes. The document is rewritten only if the edit
- succeeds.
- """
+def _write_frontmatter(path: str, front: _Frontmatter, header: str) -> None:
+ """Write a successfully edited carrier back to frontmatter."""
from marimo._utils import yaml
- front = _read_frontmatter(path)
-
- notebook_dir = os.path.dirname(os.path.abspath(path))
- with _carrier(path, front.header) as target:
- edit(target, notebook_dir)
- with open(target, encoding="utf-8") as f:
- header = f.read()
-
data = front.data
if front.is_pyproject:
# Strip '# ' and the leading/trailing /// markers
@@ -408,12 +498,42 @@ def _edit_frontmatter(path: str, edit: Callable[[str, str], None]) -> None:
@dataclass(frozen=True)
class MaterializedScript:
- """A script uv can operate on and the directory to run uv from."""
+ """A script an environment manager can operate on and its cwd."""
path: str
directory: str
+def materialized_for_edit(path: str) -> Iterator[MaterializedScript]:
+ """Materialize a notebook's manifest for one manager edit.
+
+ Python notebooks are edited directly. Markdown and Quarto frontmatter
+ use a unique carrier beside the notebook. A successful edit is written
+ back after the manager returns; an exception leaves the notebook
+ unchanged. The carrier is always removed by `_carrier`.
+ """
+ absolute = os.path.abspath(path)
+ directory = os.path.dirname(absolute)
+ if not path.endswith((".md", ".qmd")):
+ yield MaterializedScript(path=absolute, directory=directory)
+ return
+
+ front = _read_frontmatter(absolute)
+ with _carrier(absolute, front.header) as target:
+ edit_succeeded = False
+ try:
+ yield MaterializedScript(path=target, directory=directory)
+ edit_succeeded = True
+ finally:
+ # Only commit frontmatter after the caller's edit completed.
+ # `_carrier` still removes the temporary script on every exit.
+ if edit_succeeded:
+ with open(target, encoding="utf-8") as f:
+ header = f.read()
+ _write_frontmatter(absolute, front, header)
+
+
@contextlib.contextmanager
def materialized_for_environment(path: str) -> Iterator[MaterializedScript]:
"""Materializes a notebook's manifest for environment operations.
diff --git a/marimo/_environments/uv.py b/marimo/_environments/uv.py
index 91d0ded007..424a4a9c1c 100644
--- a/marimo/_environments/uv.py
+++ b/marimo/_environments/uv.py
@@ -17,7 +17,11 @@ import threading
from typing import TYPE_CHECKING
from marimo import _loggers
-from marimo._environments.errors import EnvironmentManagerError
+from marimo._environments.errors import (
+ EnvironmentManagerError,
+ EnvironmentManagerNotFoundError,
+ MissingScriptMetadataError,
+)
if TYPE_CHECKING:
from collections.abc import Callable, Mapping, Sequence
@@ -33,7 +37,7 @@ class UvError(EnvironmentManagerError):
"""Base for all failures invoking uv."""
-class UvNotFoundError(UvError):
+class UvNotFoundError(UvError, EnvironmentManagerNotFoundError):
"""uv is not installed or not on the PATH."""
def __init__(self, message: str | None = None) -> None:
@@ -65,7 +69,7 @@ class UvCommandError(UvError):
)
-class UvMissingScriptMetadataError(UvCommandError):
+class UvMissingScriptMetadataError(UvCommandError, MissingScriptMetadataError):
"""The target script has no PEP 723 inline metadata block."""
@@ -142,16 +146,21 @@ def uv(
env: Mapping[str, str] | None = None,
cwd: str | None = None,
timeout: float | None = None,
+ on_command: Callable[[Sequence[str]], None] | None = None,
) -> subprocess.CompletedProcess[str]:
"""Run a uv command and capture its output.
Raises `UvNotFoundError` if uv is not installed and `UvCommandError` (or
a refined subclass) on nonzero exit. `subprocess.TimeoutExpired`
propagates when `timeout` elapses. When `env` is given it replaces the
- inherited environment. Not for interactive or streaming use: output is
- captured, and stdin is closed so uv can never hang waiting for input.
+ inherited environment. `on_command` receives the exact argv about to
+ run, so reports never drift from the invocation. Not for interactive
+ or streaming use: output is captured, and stdin is closed so uv can
+ never hang waiting for input.
"""
command = [find_uv_bin(), *args]
+ if on_command is not None:
+ on_command(command)
try:
completed = subprocess.run(
command,
@@ -186,6 +195,7 @@ def uv_stream(
*,
env: Mapping[str, str] | None = None,
cwd: str | None = None,
+ on_command: Callable[[Sequence[str]], None] | None = None,
) -> subprocess.CompletedProcess[str]:
"""Runs a uv command, streaming its diagnostics to a callback.
@@ -193,12 +203,15 @@ def uv_stream(
stderr lines stream to `on_output` (and this process's stderr) while
stdout is captured for the caller. `on_output` runs in the calling
thread, so callbacks that rely on thread-local state, such as a
- kernel's notification context, keep working. Failures raise the same
- refined errors as `uv()`.
+ kernel's notification context, keep working. `on_command` receives
+ the exact argv about to run. Failures raise the same refined errors
+ as `uv()`.
"""
from marimo._utils.subprocess import kill_subprocess
command = [find_uv_bin(), *args]
+ if on_command is not None:
+ on_command(command)
try:
process = subprocess.Popen(
command,
diff --git a/marimo/_ipc/types.py b/marimo/_ipc/types.py
index 79e69dfc49..264a7f0283 100644
--- a/marimo/_ipc/types.py
+++ b/marimo/_ipc/types.py
@@ -35,9 +35,6 @@ class KernelArgs(msgspec.Struct):
connection_info: ConnectionInfo
# Whether to use run-mode config (autorun) vs edit-mode config (lazy)
is_run_mode: bool = False
- # Runtime behavior flags
- # virtual_files_supported is ignored, but kept for backward compatibility
- virtual_files_supported: bool = True
redirect_console_to_browser: bool = True
parent_pid: int | None = None
# None means virtual files are unsupported and content is inlined as
diff --git a/marimo/_messaging/notification.py b/marimo/_messaging/notification.py
index e9e49c7f04..3e05373e64 100644
--- a/marimo/_messaging/notification.py
+++ b/marimo/_messaging/notification.py
@@ -503,7 +503,8 @@ class MissingPackageAlertNotification(
# package name => installation status
PackageStatusType = dict[
- str, Literal["queued", "installing", "installed", "failed"]
+ str,
+ Literal["queued", "installing", "installed", "failed", "restart-required"],
]
diff --git a/marimo/_runtime/callbacks/packages.py b/marimo/_runtime/callbacks/packages.py
index 76242520d2..d500dbcc01 100644
--- a/marimo/_runtime/callbacks/packages.py
+++ b/marimo/_runtime/callbacks/packages.py
@@ -96,12 +96,27 @@ class PackagesCallbacks:
broadcast_notification(CompletedRunNotification())
def update_package_manager(self, package_manager: str) -> None:
+ if GLOBAL_SETTINGS.SANDBOX_MODE is not None:
+ from marimo._environments.backends import current_backend
+ from marimo._environments.sandbox import NotebookSandbox
+ from marimo._runtime.packages.sandbox_package_manager import (
+ SandboxPackageManager,
+ )
+
+ if not isinstance(self.package_manager, SandboxPackageManager):
+ self.package_manager = SandboxPackageManager(
+ NotebookSandbox.from_running_process(
+ self._kernel.app_metadata.filename, current_backend()
+ )
+ )
+ return
+
if (
self.package_manager is None
or package_manager != self.package_manager.name
):
self.package_manager = create_package_manager(
- package_manager, script_path=self._sandbox_script_path()
+ package_manager,
)
# All marimo notebooks depend on the marimo package; if the
@@ -110,6 +125,14 @@ class PackagesCallbacks:
# NOOP.
self._maybe_add_marimo_to_script_metadata()
+ def rename_file(self, filename: str) -> None:
+ from marimo._runtime.packages.sandbox_package_manager import (
+ SandboxPackageManager,
+ )
+
+ if isinstance(self.package_manager, SandboxPackageManager):
+ self.package_manager.rebind(filename)
+
def send_missing_packages_alert(self, missing_packages: set[str]) -> None:
if self.package_manager is None:
return
@@ -236,10 +259,13 @@ class PackagesCallbacks:
assert self.package_manager is not None, (
"Cannot install packages without a package manager"
)
- if request.manager != self.package_manager.name:
+ if (
+ request.manager != self.package_manager.name
+ and GLOBAL_SETTINGS.SANDBOX_MODE is None
+ ):
# Swap out the package manager
self.package_manager = create_package_manager(
- request.manager, script_path=self._sandbox_script_path()
+ request.manager,
)
if not self.package_manager.is_manager_installed():
@@ -345,13 +371,22 @@ class PackagesCallbacks:
),
)
else:
- package_statuses[pkg] = "failed"
+ restart_required = self.package_manager.restart_required
+ package_statuses[pkg] = (
+ "restart-required" if restart_required else "failed"
+ )
mod = self.package_manager.package_to_module(pkg)
self._kernel.module_registry.excluded_modules.add(mod)
broadcast_notification(
InstallingPackageAlertNotification(
packages=package_statuses,
- logs={pkg: f"Failed to install {pkg}\n"},
+ logs={
+ pkg: (
+ f"Dependency changes saved for {pkg}; restart the kernel to use them.\n"
+ if restart_required
+ else f"Failed to install {pkg}\n"
+ )
+ },
log_status="done",
source=request.source,
),
@@ -390,13 +425,6 @@ class PackagesCallbacks:
if cells_to_run:
await self._kernel.maybe_autorun_cells(cells_to_run)
- def _sandbox_script_path(self) -> str | None:
- """The notebook path when its dependencies live in a script
- environment; None otherwise."""
- if GLOBAL_SETTINGS.SANDBOX_MODE is None:
- return None
- return self._kernel.app_metadata.filename
-
def _maybe_add_marimo_to_script_metadata(self) -> None:
if self.should_update_script_metadata():
self.update_script_metadata(["marimo"])
diff --git a/marimo/_runtime/packages/package_manager.py b/marimo/_runtime/packages/package_manager.py
index d631d666be..9a48640d49 100644
--- a/marimo/_runtime/packages/package_manager.py
+++ b/marimo/_runtime/packages/package_manager.py
@@ -55,6 +55,11 @@ class PackageManager(abc.ABC):
def __init__(self) -> None:
self._attempted_packages: set[str] = set()
+ @property
+ def restart_required(self) -> bool:
+ """Whether the last mutation was saved but needs a kernel restart."""
+ return False
+
@abc.abstractmethod
def module_to_package(self, module_name: str) -> str:
"""Canonicalizes a module name to a package name."""
diff --git a/marimo/_runtime/packages/package_managers.py b/marimo/_runtime/packages/package_managers.py
index bfa8751065..f816885ba9 100644
--- a/marimo/_runtime/packages/package_managers.py
+++ b/marimo/_runtime/packages/package_managers.py
@@ -1,6 +1,8 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+from typing import TYPE_CHECKING
+
from marimo._runtime.packages.conda_package_manager import PixiPackageManager
from marimo._runtime.packages.package_manager import PackageManager
from marimo._runtime.packages.pypi_package_manager import (
@@ -12,6 +14,10 @@ from marimo._runtime.packages.pypi_package_manager import (
)
from marimo._utils.platform import is_pyodide
+if TYPE_CHECKING:
+ from marimo._environments.environment import Environment
+ from marimo._environments.sandbox import Backend
+
PACKAGE_MANAGERS = {
MicropipPackageManager.name: MicropipPackageManager,
PipPackageManager.name: PipPackageManager,
@@ -26,19 +32,37 @@ def create_package_manager(
name: str,
python_exe: str | None = None,
script_path: str | None = None,
+ sandbox_backend: Backend | None = None,
+ sandbox_environment: Environment | None = None,
) -> PackageManager:
"""Creates the named package manager.
- `script_path` puts uv in script mode: package changes edit the
- notebook's metadata and synchronize its script environment instead of
- installing imperatively. Other managers ignore it.
+ `script_path` selects the notebook sandbox package adapter: package
+ changes edit the Manifest and synchronize its Environment through the
+ selected backend instead of installing imperatively. The backend
+ defaults to the one this process was sandboxed with.
"""
if is_pyodide():
# user config has name "pip", but micropip's name is "micropip" ...
return MicropipPackageManager()
+ if script_path is not None:
+ from marimo._environments.backends import current_backend
+ from marimo._environments.sandbox import NotebookSandbox
+ from marimo._runtime.packages.sandbox_package_manager import (
+ SandboxPackageManager,
+ )
+
+ return SandboxPackageManager(
+ NotebookSandbox(
+ script_path,
+ sandbox_backend or current_backend(),
+ environment=sandbox_environment,
+ )
+ )
+
if name == UvPackageManager.name:
- return UvPackageManager(python_exe=python_exe, script_path=script_path)
+ return UvPackageManager(python_exe=python_exe)
if name in PACKAGE_MANAGERS:
return PACKAGE_MANAGERS[name]( # type:ignore[abstract,no-any-return]
diff --git a/marimo/_runtime/packages/pypi_package_manager.py b/marimo/_runtime/packages/pypi_package_manager.py
index 68ab54c1dc..203b82feed 100644
--- a/marimo/_runtime/packages/pypi_package_manager.py
+++ b/marimo/_runtime/packages/pypi_package_manager.py
@@ -3,7 +3,6 @@ from __future__ import annotations
import json
import os
-import re
import subprocess
import sys
from functools import cached_property
@@ -18,7 +17,6 @@ from marimo._dependencies.dependencies import DependencyManager
from marimo._environments import script_metadata
from marimo._environments.uv import (
UvCommandError,
- UvError,
find_uv_bin,
uv,
)
@@ -32,7 +30,6 @@ from marimo._runtime.packages.package_manager import (
CanonicalizingPackageManager,
LogCallback,
PackageDescription,
- _normalize_package_name,
)
from marimo._runtime.packages.utils import (
popen_package_command,
@@ -53,13 +50,6 @@ PY_EXE = sys.executable
LOGGER = _loggers.marimo_logger()
-def _normalized_requirement_name(requirement: str) -> str | None:
- match = re.match(r"[A-Za-z0-9][A-Za-z0-9._-]*", requirement.strip())
- if match is None:
- return None
- return _normalize_package_name(match.group(0))
-
-
class VersionMap:
"""
A map of package names to versions, with some extra
@@ -357,14 +347,7 @@ class UvPackageManager(PypiPackageManager):
SCRIPT_METADATA_MARKER = "# /// script"
_use_project = True
- def __init__(
- self,
- python_exe: str | None = None,
- script_path: str | None = None,
- ) -> None:
- # In script mode, package changes edit the notebook's metadata and
- # synchronize its script environment; nothing installs imperatively.
- self._script_path = script_path
+ def __init__(self, python_exe: str | None = None) -> None:
super().__init__(python_exe)
@classmethod
@@ -378,65 +361,6 @@ class UvPackageManager(PypiPackageManager):
def _uv_bin(self) -> str:
return find_uv_bin()
- def _declared_dependencies(self, script_path: str) -> set[str]:
- """Normalized names declared in the notebook's script metadata."""
- from marimo._utils.inline_script_metadata import PyProjectReader
-
- try:
- dependencies = PyProjectReader.from_filename(
- script_path
- ).dependencies
- except (OSError, ValueError):
- return set()
- return {
- name
- for dep in dependencies
- if (name := _normalized_requirement_name(str(dep))) is not None
- }
-
- def _change_script_environment(
- self,
- script_path: str,
- *,
- add: list[str] | None = None,
- remove: list[str] | None = None,
- upgrade: bool = False,
- log_callback: LogCallback | None = None,
- ) -> bool:
- """Edits the manifest and synchronizes its script environment.
-
- uv writes the constraint and resolves with the metadata's full
- semantics, streaming its output to `log_callback` line by line.
- Failures stream the solver's message rather than pointing at the
- terminal.
- """
- from marimo._environments import environment
-
- try:
- if add:
- script_metadata.add_dependencies(
- script_path,
- add,
- upgrade=upgrade,
- on_output=log_callback,
- )
- if remove:
- script_metadata.remove_dependencies(
- script_path, remove, on_output=log_callback
- )
- environment.sync_notebook(script_path, on_output=log_callback)
- return True
- except (script_metadata.ScriptMetadataError, UvError) as e:
- message = str(e.__cause__ or e)
- LOGGER.error(
- "Failed to update script environment for %s: %s",
- script_path,
- message,
- )
- if log_callback is not None:
- log_callback(message + "\n")
- return False
-
def _is_cache_write_error(self, output_text: str) -> bool:
"""Check if the output text indicates a cache write error.
@@ -488,17 +412,6 @@ class UvPackageManager(PypiPackageManager):
log_callback: LogCallback | None = None,
) -> bool:
"""Installation logic with fallback to --no-cache on cache write errors."""
- import asyncio
-
- if self._script_path is not None:
- return await asyncio.to_thread(
- self._change_script_environment,
- self._script_path,
- add=split_packages(package),
- upgrade=upgrade,
- log_callback=log_callback,
- )
-
LOGGER.info(
f"Installing in {package} with 'uv {'add' if self.is_in_uv_project else 'pip install'}'"
)
@@ -598,13 +511,6 @@ class UvPackageManager(PypiPackageManager):
import_namespaces_to_remove: List of import namespaces to remove
upgrade: Whether to upgrade the packages
"""
- if self._script_path is not None:
- # Script mode: install and uninstall already wrote these
- # packages through the script environment. Only namespace
- # changes from cell registration remain.
- packages_to_add = None
- packages_to_remove = None
-
packages_to_add = packages_to_add or []
packages_to_remove = packages_to_remove or []
import_namespaces_to_add = import_namespaces_to_add or []
@@ -617,14 +523,6 @@ class UvPackageManager(PypiPackageManager):
self.module_to_package(im) for im in import_namespaces_to_remove
]
- if self._script_path is not None and packages_to_add:
- declared = self._declared_dependencies(filepath)
- packages_to_add = [
- package
- for package in packages_to_add
- if _normalized_requirement_name(package) not in declared
- ]
-
if not packages_to_add and not packages_to_remove:
return True
@@ -735,39 +633,6 @@ class UvPackageManager(PypiPackageManager):
return uv_lock_path.exists() and pyproject_path.exists()
async def uninstall(self, package: str, group: str | None = None) -> bool:
- if self._script_path is not None:
- import asyncio
-
- requested = split_packages(package)
- declared = await asyncio.to_thread(
- self._declared_dependencies, self._script_path
- )
- undeclared = [
- pkg
- for pkg in requested
- if _normalized_requirement_name(pkg) not in declared
- ]
- if undeclared:
- # A transitive dependency is not the notebook's to remove;
- # removing it from the environment alone would be undone
- # by the next synchronization.
- LOGGER.warning(
- "%s is not declared in the notebook's script metadata "
- "(likely a dependency of another package), so it "
- "cannot be removed.",
- ", ".join(undeclared),
- )
- return False
- return await asyncio.to_thread(
- self._change_script_environment,
- self._script_path,
- remove=[
- name
- for pkg in requested
- if (name := _normalized_requirement_name(pkg)) is not None
- ],
- )
-
uninstall_cmd: list[str]
if self.is_in_uv_project:
LOGGER.info(f"Uninstalling {package} with 'uv remove'")
diff --git a/marimo/_runtime/packages/sandbox_package_manager.py b/marimo/_runtime/packages/sandbox_package_manager.py
new file mode 100644
index 0000000000..b5b7dfb909
--- /dev/null
+++ b/marimo/_runtime/packages/sandbox_package_manager.py
@@ -0,0 +1,191 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Legacy package-manager adapter for a notebook sandbox.
+
+The package endpoints and Missing packages callback still consume
+`PackageManager`. This adapter keeps that compatibility surface thin while the
+NotebookSandbox owns Manifest edits, synchronization, and inspection.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.metadata
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from marimo import _loggers
+from marimo._environments.errors import (
+ EnvironmentManagerError,
+ SandboxRestartRequired,
+)
+from marimo._environments.sandbox import _redact_url_credentials
+from marimo._runtime.packages.package_manager import PackageDescription
+from marimo._runtime.packages.pypi_package_manager import PypiPackageManager
+from marimo._runtime.packages.utils import split_packages
+
+if TYPE_CHECKING:
+ from marimo._environments.sandbox import Backend, NotebookSandbox
+ from marimo._runtime.packages.package_manager import LogCallback
+ from marimo._utils.uv_tree import DependencyTreeNode
+
+LOGGER = _loggers.marimo_logger()
+
+
+class SandboxPackageManager(PypiPackageManager):
+ """Present a NotebookSandbox through the package manager API."""
+
+ def __init__(self, sandbox: NotebookSandbox) -> None:
+ self._sandbox = sandbox
+ self.last_error: str | None = None
+ self._restart_required = False
+ self.name = sandbox.backend
+ self.docs_url = (
+ "https://pixi.sh"
+ if self.name == "pixi"
+ else "https://docs.astral.sh/uv/"
+ )
+ python = (
+ sandbox.environment.python
+ if sandbox.environment is not None
+ else None
+ )
+ super().__init__(python_exe=python)
+
+ @property
+ def restart_required(self) -> bool:
+ return self._restart_required
+
+ @property
+ def backend(self) -> Backend:
+ return self._sandbox.backend
+
+ def rebind(self, filename: str) -> None:
+ """Follow a notebook rename without replacing its package manager."""
+ self._sandbox.rebind(filename, persist_manifest=False)
+
+ def is_manager_installed(self) -> bool:
+ # A running sandbox already selected this manager. Operations retain
+ # their typed backend errors if the executable disappears later.
+ return True
+
+ async def _install(
+ self,
+ package: str,
+ *,
+ upgrade: bool,
+ group: str | None = None,
+ log_callback: LogCallback | None = None,
+ ) -> bool:
+ del group
+ self.last_error = None
+ self._restart_required = False
+ try:
+ for requirement in split_packages(package):
+ try:
+ await asyncio.to_thread(
+ self._sandbox.add,
+ requirement,
+ upgrade=upgrade,
+ on_output=log_callback,
+ )
+ except SandboxRestartRequired as error:
+ self._restart_required = True
+ if log_callback is not None:
+ log_callback(str(error) + "\n")
+ return not self.restart_required
+ except EnvironmentManagerError as error:
+ self._restart_required = False
+ self._report(error, log_callback)
+ return False
+
+ async def uninstall(self, package: str, group: str | None = None) -> bool:
+ del group
+ self.last_error = None
+ self._restart_required = False
+ try:
+ for requirement in split_packages(package):
+ try:
+ await asyncio.to_thread(self._sandbox.remove, requirement)
+ except SandboxRestartRequired:
+ self._restart_required = True
+ return not self.restart_required
+ except EnvironmentManagerError as error:
+ self._restart_required = False
+ self._report(error, None)
+ return False
+
+ def list_packages(self) -> list[PackageDescription]:
+ try:
+ state = self._sandbox.packages()
+ except EnvironmentManagerError as error:
+ self._report(error, None)
+ return []
+ return [
+ PackageDescription(name=package.name, version=package.version)
+ for package in state.packages
+ ]
+
+ def dependency_tree(
+ self, filename: str | None = None
+ ) -> DependencyTreeNode | None:
+ if filename is not None and filename != self._sandbox.source:
+ self._sandbox.rebind(filename)
+ try:
+ return self._sandbox.packages().tree
+ except EnvironmentManagerError as error:
+ self._report(error, None)
+ return None
+
+ def update_notebook_script_metadata(
+ self,
+ filepath: str,
+ *,
+ packages_to_add: list[str] | None = None,
+ packages_to_remove: list[str] | None = None,
+ import_namespaces_to_add: list[str] | None = None,
+ import_namespaces_to_remove: list[str] | None = None,
+ upgrade: bool,
+ ) -> bool:
+ del (
+ filepath,
+ packages_to_add,
+ packages_to_remove,
+ import_namespaces_to_remove,
+ upgrade,
+ )
+ # Explicit add/remove already updated the manifest. Cell registration
+ # can also discover an imported package without any preceding install.
+ try:
+ packages = [
+ self.module_to_package(namespace)
+ for namespace in import_namespaces_to_add or []
+ ]
+ runtime_versions: dict[str, str] = {}
+ environment = self._sandbox.environment
+ prefix = Path(environment.root).resolve() if environment else None
+ for package in packages:
+ try:
+ distribution = importlib.metadata.distribution(package)
+ except importlib.metadata.PackageNotFoundError:
+ continue
+ # The backend owns packages in its prefix (including conda
+ # packages). Only add metadata from the runtime overlay here.
+ location = Path(str(distribution.locate_file(""))).resolve()
+ if prefix is None or not location.is_relative_to(prefix):
+ runtime_versions[package] = distribution.version
+ self._sandbox.record_dependencies(
+ packages, runtime_versions=runtime_versions
+ )
+ return True
+ except EnvironmentManagerError as error:
+ self._report(error, None)
+ return False
+
+ def _report(
+ self, error: Exception, log_callback: LogCallback | None
+ ) -> None:
+ message = _redact_url_credentials(str(error.__cause__ or error))
+ self.last_error = message
+ LOGGER.error("Failed to update notebook sandbox: %s", message)
+ if log_callback is not None:
+ log_callback(message + "\n")
diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.py
index ea91a8f97d..ccead97387 100644
--- a/marimo/_runtime/runtime.py
+++ b/marimo/_runtime/runtime.py
@@ -1805,6 +1805,7 @@ class Kernel:
async def rename_file(self, filename: str) -> None:
self.globals["__file__"] = filename
self.app_metadata.filename = filename
+ self.packages_callbacks.rename_file(filename)
roots: set[CellId_t] = set()
for cell in self.graph.cells.values():
if "__file__" in cell.refs:
diff --git a/marimo/_schemas/generated/notifications.yaml b/marimo/_schemas/generated/notifications.yaml
index c8f13707e3..0eeee88b86 100644
--- a/marimo/_schemas/generated/notifications.yaml
+++ b/marimo/_schemas/generated/notifications.yaml
@@ -923,6 +923,7 @@ components:
- installed
- installing
- queued
+ - restart-required
type: object
source:
default: kernel
diff --git a/marimo/_server/api/endpoints/files.py b/marimo/_server/api/endpoints/files.py
index f3b32c2d76..0f2e39fe99 100644
--- a/marimo/_server/api/endpoints/files.py
+++ b/marimo/_server/api/endpoints/files.py
@@ -133,15 +133,19 @@ async def rename_file(
command = RenameNotebookCommand(filename=filename)
enforce_consumer_capability(app_state, command)
+ success, error = await app_state.session_manager.rename_session(
+ app_state.require_current_session_id(), body.filename
+ )
+ if not success:
+ raise HTTPException(status_code=400, detail=error)
+
+ # Rename-triggered cells may immediately read the file or edit its
+ # dependencies. The durable file and server binding must be ready first.
app_state.require_current_session().put_control_request(
command,
from_consumer_id=ConsumerId(app_state.require_current_session_id()),
)
- await app_state.session_manager.rename_session(
- app_state.require_current_session_id(), body.filename
- )
-
return SuccessResponse()
diff --git a/marimo/_server/api/endpoints/packages.py b/marimo/_server/api/endpoints/packages.py
index 09379bac71..567e9da2db 100644
--- a/marimo/_server/api/endpoints/packages.py
+++ b/marimo/_server/api/endpoints/packages.py
@@ -9,6 +9,9 @@ from starlette.authentication import requires
from marimo._config.settings import GLOBAL_SETTINGS
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 (
+ SandboxPackageManager,
+)
from marimo._runtime.packages.utils import split_packages
from marimo._server.api.deps import AppState
from marimo._server.api.utils import parse_request
@@ -16,8 +19,11 @@ from marimo._server.models.packages import (
AddPackageRequest,
DependencyTreeResponse,
ListPackagesResponse,
+ PackageInstallationContext,
+ PackageManagerContext,
PackageOperationResponse,
RemovePackageRequest,
+ SandboxPackageContext,
)
from marimo._server.router import APIRouter
@@ -78,8 +84,12 @@ async def add_package(request: Request) -> PackageOperationResponse:
if success:
return PackageOperationResponse.of_success()
+ if package_manager.restart_required:
+ return PackageOperationResponse(success=False, restart_required=True)
+
return PackageOperationResponse.of_failure(
- f"Failed to install {body.package}. See terminal for error logs."
+ _failure_message(package_manager)
+ or f"Failed to install {body.package}. See terminal for error logs."
)
@@ -131,11 +141,21 @@ async def remove_package(request: Request) -> PackageOperationResponse:
if success:
return PackageOperationResponse.of_success()
+ if package_manager.restart_required:
+ return PackageOperationResponse(success=False, restart_required=True)
+
return PackageOperationResponse.of_failure(
- f"Failed to uninstall {body.package}. See terminal for error logs."
+ _failure_message(package_manager)
+ or f"Failed to uninstall {body.package}. See terminal for error logs."
)
+def _failure_message(package_manager: PackageManager) -> str | None:
+ if isinstance(package_manager, SandboxPackageManager):
+ return package_manager.last_error
+ return None
+
+
@router.get("/list")
@requires("edit")
async def list_packages(request: Request) -> ListPackagesResponse:
@@ -171,6 +191,7 @@ async def dependency_tree(request: Request) -> DependencyTreeResponse:
$ref: "#/components/schemas/DependencyTreeResponse"
"""
package_manager = _get_package_manager(request)
+ context = _get_package_installation_context(package_manager)
filename = _get_filename(request)
is_sandbox = (
@@ -182,7 +203,7 @@ async def dependency_tree(request: Request) -> DependencyTreeResponse:
)
else:
tree = await asyncio.to_thread(package_manager.dependency_tree)
- return DependencyTreeResponse(tree=tree)
+ return DependencyTreeResponse(tree=tree, context=context)
def _get_package_manager(request: Request) -> PackageManager:
@@ -197,10 +218,17 @@ 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)
+
kernel_manager = session._kernel_manager
if isinstance(kernel_manager, IPCKernelManagerImpl):
python_exe = kernel_manager.venv_python
@@ -208,6 +236,7 @@ def _get_package_manager(request: Request) -> PackageManager:
# 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
@@ -215,9 +244,18 @@ def _get_package_manager(request: Request) -> PackageManager:
config_manager.package_manager,
python_exe=python_exe,
script_path=script_path,
+ sandbox_environment=sandbox_environment,
)
+def _get_package_installation_context(
+ package_manager: PackageManager,
+) -> PackageInstallationContext:
+ if isinstance(package_manager, SandboxPackageManager):
+ return SandboxPackageContext(backend=package_manager.backend)
+ return PackageManagerContext(name=package_manager.name)
+
+
def _get_filename(request: Request) -> str | None:
session = AppState(request).get_current_session()
if session is None:
diff --git a/marimo/_server/models/packages.py b/marimo/_server/models/packages.py
index 14215c2891..e95c853144 100644
--- a/marimo/_server/models/packages.py
+++ b/marimo/_server/models/packages.py
@@ -1,6 +1,8 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+from typing import Literal
+
import msgspec
from marimo._runtime.packages.package_manager import PackageDescription
@@ -31,17 +33,42 @@ class RemovePackageRequest(msgspec.Struct, rename="camel"):
group: str | None = None
+class SandboxPackageContext(
+ msgspec.Struct,
+ frozen=True,
+ tag="sandbox",
+ tag_field="kind",
+ rename="camel",
+):
+ backend: Literal["uv", "pixi"]
+
+
+class PackageManagerContext(
+ msgspec.Struct,
+ frozen=True,
+ tag="package-manager",
+ tag_field="kind",
+ rename="camel",
+):
+ name: str
+
+
+PackageInstallationContext = SandboxPackageContext | PackageManagerContext
+
+
class ListPackagesResponse(msgspec.Struct, rename="camel"):
packages: list[PackageDescription]
class DependencyTreeResponse(msgspec.Struct, rename="camel"):
tree: DependencyTreeNode | None
+ context: PackageInstallationContext
class PackageOperationResponse(msgspec.Struct, rename="camel"):
success: bool
error: str | None = None
+ restart_required: bool = False
@staticmethod
def of_success() -> PackageOperationResponse:
diff --git a/marimo/_session/app_host/pool.py b/marimo/_session/app_host/pool.py
index 087e859f30..1661ce81bf 100644
--- a/marimo/_session/app_host/pool.py
+++ b/marimo/_session/app_host/pool.py
@@ -13,13 +13,12 @@ from dataclasses import dataclass
from marimo._environments.environment import (
ProcessPlan,
- launch,
- launch_isolated,
- sync_notebook,
)
-from marimo._environments.errors import EnvironmentManagerError
+from marimo._environments.errors import (
+ EnvironmentManagerError,
+ MissingScriptMetadataError,
+)
from marimo._environments.overlay import runtime_overlay
-from marimo._environments.uv import UvMissingScriptMetadataError
from marimo._session.app_host.host import AppHost
from marimo._session.managers.ipc import KernelStartupError
@@ -88,20 +87,21 @@ class AppHostPool:
del self._pending[abs_path]
def _sandbox_plan(self, abs_path: str) -> ProcessPlan:
+ from marimo._environments import backends
+
+ backend = backends.current_backend()
args = ["-m", "marimo._session.app_host.main"]
overlay = runtime_overlay()
try:
try:
- handle = sync_notebook(abs_path)
- except UvMissingScriptMetadataError:
- import platform
-
- plan = launch_isolated(
- args, overlay=overlay, python=platform.python_version()
- )
+ handle = backends.sync_notebook(abs_path, backend=backend)
+ except MissingScriptMetadataError:
+ plan = backends.launch_fallback(args)
plan.env.pop("MARIMO_SANDBOX_MODE", None)
else:
- plan = launch(handle, args, overlay=overlay)
+ plan = backends.launch(
+ handle, args, backend=backend, overlay=overlay
+ )
plan.env["MARIMO_SANDBOX_MODE"] = "multi"
plan.env["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"
return plan
diff --git a/marimo/_session/managers/ipc.py b/marimo/_session/managers/ipc.py
index a1f3746560..09688c150a 100644
--- a/marimo/_session/managers/ipc.py
+++ b/marimo/_session/managers/ipc.py
@@ -20,17 +20,12 @@ 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,
- launch,
- launch_isolated,
- sync_notebook,
-)
+from marimo._environments.environment import Environment
from marimo._environments.overlay import runtime_overlay
-from marimo._environments.uv import UvError, UvMissingScriptMetadataError
from marimo._messaging.types import KernelMessage
from marimo._runtime import commands
from marimo._session._venv import (
@@ -51,6 +46,7 @@ from marimo._utils.typed_connection import TypedConnection
if TYPE_CHECKING:
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
@@ -238,6 +234,7 @@ def construct_kernel_env(
# kernel inside a sandboxed server must not route package changes
# through a script environment it does not run in.
env.pop("MARIMO_SANDBOX_MODE", None)
+ env.pop("MARIMO_SANDBOX_BACKEND", None)
env.pop("MARIMO_MANAGE_SCRIPT_METADATA", None)
if kernel_pythonpath is not None:
@@ -279,6 +276,7 @@ class IPCKernelManagerImpl(KernelManager):
app_metadata: AppMetadata,
config_manager: MarimoConfigReader,
redirect_console_to_browser: bool = True,
+ sandbox_mode: SandboxMode = SandboxMode.MULTI,
) -> None:
self.queue_manager = queue_manager
self.connection_info = connection_info
@@ -287,12 +285,14 @@ 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._process: subprocess.Popen[bytes] | None = None
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
@@ -300,8 +300,15 @@ class IPCKernelManagerImpl(KernelManager):
@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:
from marimo._cli.print import echo, muted
from marimo._ipc.types import KernelArgs
@@ -321,8 +328,14 @@ class IPCKernelManagerImpl(KernelManager):
venv_config = _get_venv_config(self.config_manager)
try:
- configured_python = get_configured_venv_python(
- venv_config, base_path=self.app_metadata.filename
+ # 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
)
except ValueError as e:
raise KernelStartupError(str(e)) from e
@@ -387,73 +400,53 @@ class IPCKernelManagerImpl(KernelManager):
cmd: list[str] = [venv_python, "-m", "marimo._ipc.launch_kernel"]
plan_launched = False
else:
- # Synchronize the notebook's script environment; a notebook
- # without a metadata block runs ephemerally, and packages
- # installed during its session die with it.
+ # The session retains this Interface so rename and package API
+ # operations update the same Manifest binding and Environment.
+ from marimo._environments import backends
+ from marimo._environments.errors import EnvironmentManagerError
+ from marimo._environments.sandbox import NotebookSandbox
+
+ backend = backends.current_backend()
kernel_args_list = ["-m", "marimo._ipc.launch_kernel"]
overlay = runtime_overlay()
- handle = None
filename = self.app_metadata.filename
- if filename is not None:
- from marimo._environments import script_metadata
-
- # Best-effort: give metadata-less notebooks a block so
- # they get a real script environment instead of an
- # ephemeral one whose installs the server cannot target.
- try:
- script_metadata.ensure_marimo(filename)
- except Exception as e:
- LOGGER.warning(
- "Failed to add marimo to script metadata: %s", e
- )
- try:
- handle = sync_notebook(
- filename, on_output=lambda _line: None
- )
- except UvMissingScriptMetadataError:
- handle = None
- except UvError as e:
- raise KernelStartupError(
- f"Failed to build sandbox environment.\n\n{e}"
- ) from e
-
- if handle is not None:
- self._venv_python = handle.python
- self._script_environment = handle
- plan = launch(
- handle,
+ sandbox = (
+ NotebookSandbox.from_running_process(None, backend)
+ if filename is None and self.sandbox_mode is SandboxMode.SINGLE
+ else NotebookSandbox(filename, backend)
+ )
+ try:
+ plan = sandbox.launch(
kernel_args_list,
overlay=overlay,
base_env=os.environ.copy(),
+ on_output=lambda _line: None,
)
- echo(
- f"Running kernel in script environment: "
- f"{muted(handle.root)}",
- err=True,
+ except EnvironmentManagerError as e:
+ sandbox.close()
+ raise KernelStartupError(
+ f"Failed to build sandbox environment.\n\n{e}"
+ ) from e
+ handle = sandbox.environment
+ if handle is None:
+ sandbox.close()
+ raise KernelStartupError(
+ "Failed to build sandbox environment: no Environment was returned"
)
- else:
- import platform
- plan = launch_isolated(
- kernel_args_list,
- overlay=overlay,
- python=platform.python_version(),
- base_env=os.environ.copy(),
- )
- echo("Running kernel in an ephemeral sandbox", err=True)
+ 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,
+ )
plan_launched = True
env = plan.env
- # Ephemeral sandboxes are always writable; the kernel manages
- # the notebook's script metadata.
env["MARIMO_MANAGE_SCRIPT_METADATA"] = "true"
- if handle is not None:
- # Only a kernel that runs in the script environment may
- # route package changes through it; an isolated kernel
- # installs into itself imperatively.
- env["MARIMO_SANDBOX_MODE"] = "multi"
- else:
- env.pop("MARIMO_SANDBOX_MODE", None)
+ env["MARIMO_SANDBOX_MODE"] = self.sandbox_mode.value
+ env["MARIMO_SANDBOX_BACKEND"] = backend
cmd = list(plan.argv)
LOGGER.debug(f"Launching kernel: {' '.join(cmd)}")
@@ -545,13 +538,28 @@ class IPCKernelManagerImpl(KernelManager):
# Create a ProcessLike wrapper for the subprocess
self.kernel_task = _SubprocessWrapper(self._process)
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
+ def _cleanup_failed_start(self) -> 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],
@@ -673,6 +681,8 @@ class IPCKernelManagerImpl(KernelManager):
LOGGER.warning(e)
# Always attempt cleanup, even if _process is None
+ if self._notebook_sandbox is not None:
+ self._notebook_sandbox.close()
@property
def kernel_connection(self) -> TypedConnection[KernelMessage]:
diff --git a/marimo/_session/session.py b/marimo/_session/session.py
index 5176747549..0eac4cf904 100644
--- a/marimo/_session/session.py
+++ b/marimo/_session/session.py
@@ -66,6 +66,7 @@ from marimo._utils.repr import format_repr
if TYPE_CHECKING:
from collections.abc import Iterator
+ from marimo._environments.sandbox import NotebookSandbox
from marimo._runtime.virtual_file import VirtualFileStorageType
from marimo._session.app_host import AppHostContext
from marimo._session.requests import InstantiateNotebookRequest
@@ -113,6 +114,18 @@ 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.
@@ -143,7 +156,9 @@ class SessionImpl(Session):
config_manager=config_manager,
redirect_console_to_browser=redirect_console_to_browser,
)
- elif sandbox_mode is SandboxMode.MULTI:
+ elif sandbox_mode is SandboxMode.MULTI or (
+ sandbox_mode is SandboxMode.SINGLE and mode == SessionMode.EDIT
+ ):
# IPC kernel path — edit mode with sandbox
# (AppHostPool is never created in edit mode)
from marimo._ipc import QueueManager as IPCQueueManager
@@ -162,6 +177,7 @@ class SessionImpl(Session):
app_metadata=app_metadata,
config_manager=config_manager,
redirect_console_to_browser=redirect_console_to_browser,
+ sandbox_mode=sandbox_mode,
)
else:
# Original kernel: Process for edit, Thread for run
@@ -240,8 +256,10 @@ class SessionImpl(Session):
self.extensions = ExtensionRegistry()
self.extensions.add(*extensions)
self.scratchpad_lock = asyncio.Lock()
+ self._notebook_sandbox: NotebookSandbox | None = None
self._kernel_manager.start_kernel()
+ self._bind_notebook_sandbox()
self._event_bus = SessionEventBus()
self._closed = False
@@ -265,6 +283,31 @@ class SessionImpl(Session):
"""
return self.app_file_manager.app.cell_manager.document
+ @property
+ def notebook_sandbox(self) -> NotebookSandbox | None:
+ """The retained sandbox binding used by this session, if any."""
+ return self._notebook_sandbox
+
+ def _bind_notebook_sandbox(self) -> None:
+ from marimo._config.settings import GLOBAL_SETTINGS
+ from marimo._session.managers.ipc import IPCKernelManagerImpl
+
+ if isinstance(self._kernel_manager, IPCKernelManagerImpl):
+ self._notebook_sandbox = self._kernel_manager.notebook_sandbox
+ return
+
+ filename = self.app_file_manager.filename
+ if GLOBAL_SETTINGS.SANDBOX_MODE != "single":
+ return
+
+ from marimo._environments.backends import current_backend
+ from marimo._environments.sandbox import NotebookSandbox
+
+ backend = current_backend()
+ self._notebook_sandbox = NotebookSandbox.from_running_process(
+ filename, backend
+ )
+
def _attach_extensions(self) -> None:
"""Attach all extensions to the session."""
for extension in self.extensions:
@@ -310,6 +353,10 @@ class SessionImpl(Session):
"""Rename the path of the session."""
old_path = self.app_file_manager.path
self.app_file_manager.rename(new_path)
+ if self._notebook_sandbox is not None:
+ path = self.app_file_manager.path
+ assert path is not None
+ self._notebook_sandbox.rebind(path)
await self._event_bus.emit_session_notebook_renamed(self, old_path)
def try_interrupt(self) -> None:
@@ -456,6 +503,8 @@ class SessionImpl(Session):
# Close the room
self.room.close()
self._kernel_manager.close_kernel(graceful=graceful)
+ if self._notebook_sandbox is not None:
+ self._notebook_sandbox.close()
def instantiate(
self,
diff --git a/marimo/_session/types.py b/marimo/_session/types.py
index bf880ec050..7bfb1ae862 100644
--- a/marimo/_session/types.py
+++ b/marimo/_session/types.py
@@ -19,6 +19,7 @@ if TYPE_CHECKING:
from collections.abc import Iterator
from marimo._config.manager import MarimoConfigManager
+ from marimo._environments.sandbox import NotebookSandbox
from marimo._messaging.notebook.document import NotebookDocument
from marimo._messaging.notification import NotificationMessage
from marimo._messaging.types import KernelMessage
@@ -141,6 +142,11 @@ class Session(Protocol):
scratchpad_lock: asyncio.Lock
room: Room
+ @property
+ def notebook_sandbox(self) -> NotebookSandbox | None:
+ """The retained sandbox binding used by this session, if any."""
+ ...
+
@property
def document(self) -> NotebookDocument:
"""The notebook document this session reflects."""
diff --git a/marimo/_utils/uv_tree.py b/marimo/_utils/uv_tree.py
index a10ce6ae7b..4371b56edb 100644
--- a/marimo/_utils/uv_tree.py
+++ b/marimo/_utils/uv_tree.py
@@ -1,8 +1,13 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+from typing import TYPE_CHECKING
+
import msgspec
+if TYPE_CHECKING:
+ from collections.abc import Callable
+
class DependencyTag(msgspec.Struct, rename="camel"):
kind: str
@@ -12,7 +17,7 @@ class DependencyTag(msgspec.Struct, rename="camel"):
class DependencyTreeNode(msgspec.Struct, rename="camel"):
name: str
version: str | None
- # List of {"kind": "extra"|"group", "value": str}
+ # List of {"kind": "extra"|"group"|"dedupe"|"cycle", "value": str}
tags: list[DependencyTag]
dependencies: list[DependencyTreeNode]
@@ -27,6 +32,41 @@ def parse_name_version(content: str) -> tuple[str, str | None]:
def parse_uv_tree(text: str) -> DependencyTreeNode:
"""Parse the text output of `uv tree` into a nested data structure."""
+ # uv emits one footer for all `(*)` markers. With `--no-dedupe`, only
+ # cycles are marked; without it, markers mean the subtree was displayed.
+ marker_kind = "cycle" if "Package tree is a cycle" in text else "dedupe"
+ return _parse_tree(
+ text,
+ parse_name_version=parse_name_version,
+ marker_kind=marker_kind,
+ )
+
+
+def parse_pixi_tree(text: str) -> DependencyTreeNode:
+ """Parse `pixi tree` output, where `(*)` means already displayed."""
+
+ def parse_name_version(content: str) -> tuple[str, str | None]:
+ parts = content.rsplit(maxsplit=1)
+ if len(parts) == 1:
+ return parts[0], None
+ name, version = parts
+ return name, None if version == "<unknown>" else version
+
+ return _parse_tree(
+ text,
+ parse_name_version=parse_name_version,
+ marker_kind="dedupe",
+ skip_line=lambda line: line.startswith("Installed for:"),
+ )
+
+
+def _parse_tree(
+ text: str,
+ *,
+ parse_name_version: Callable[[str], tuple[str, str | None]],
+ marker_kind: str,
+ skip_line: Callable[[str], bool] | None = None,
+) -> DependencyTreeNode:
lines = text.strip().split("\n")
# Create a virtual root to hold all top-level dependencies
@@ -41,6 +81,7 @@ def parse_uv_tree(text: str) -> DependencyTreeNode:
not line
or "Package tree already displayed" in line
or "Package tree is a cycle" in line
+ or (skip_line is not None and skip_line(line))
):
continue
@@ -58,9 +99,8 @@ def parse_uv_tree(text: str) -> DependencyTreeNode:
# content after tree symbols
content = line.lstrip("│ ├└─").strip()
- # Check for cycle indicator
- is_cycle = content.endswith("(*)")
- if is_cycle:
+ is_repeated = content.endswith("(*)")
+ if is_repeated:
content = content[:-3].strip()
# tags (extras/groups)
@@ -85,9 +125,8 @@ def parse_uv_tree(text: str) -> DependencyTreeNode:
name, version = parse_name_version(content)
- # Add cycle indicator as a special tag
- if is_cycle:
- tags.append(DependencyTag(kind="cycle", value="true"))
+ if is_repeated:
+ tags.append(DependencyTag(kind=marker_kind, value="true"))
node = DependencyTreeNode(
name=name,
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 826d163ed6..6d8d1bde41 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -1506,12 +1506,22 @@ components:
type: object
DependencyTreeResponse:
properties:
+ context:
+ anyOf:
+ - $ref: '#/components/schemas/SandboxPackageContext'
+ - $ref: '#/components/schemas/PackageManagerContext'
+ discriminator:
+ mapping:
+ package-manager: '#/components/schemas/PackageManagerContext'
+ sandbox: '#/components/schemas/SandboxPackageContext'
+ propertyName: kind
tree:
anyOf:
- type: 'null'
- $ref: '#/components/schemas/DependencyTreeNode'
required:
- tree
+ - context
title: DependencyTreeResponse
type: object
DetectedDataSource:
@@ -2760,6 +2770,7 @@ components:
- installed
- installing
- queued
+ - restart-required
type: object
source:
default: kernel
@@ -4321,6 +4332,18 @@ components:
- manager
title: PackageManagementConfig
type: object
+ PackageManagerContext:
+ properties:
+ kind:
+ enum:
+ - package-manager
+ name:
+ type: string
+ required:
+ - kind
+ - name
+ title: PackageManagerContext
+ type: object
PackageOperationResponse:
properties:
error:
@@ -4328,6 +4351,9 @@ components:
- type: string
- type: 'null'
default: null
+ restartRequired:
+ default: false
+ type: boolean
success:
type: boolean
required:
@@ -4936,6 +4962,20 @@ components:
- value
title: SafeLiteralDiscoveryValue
type: object
+ SandboxPackageContext:
+ properties:
+ backend:
+ enum:
+ - pixi
+ - uv
+ kind:
+ enum:
+ - sandbox
+ required:
+ - kind
+ - backend
+ title: SandboxPackageContext
+ type: object
SaveAppConfigurationRequest:
properties:
config:
@@ -8040,3 +8080,4 @@ paths:
summary: Get the auth token for the current session
tags:
- auth
+
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 93ba350aa6..5901adafc3 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -4634,6 +4634,9 @@ export interface components {
};
/** DependencyTreeResponse */
DependencyTreeResponse: {
+ context:
+ | components["schemas"]["SandboxPackageContext"]
+ | components["schemas"]["PackageManagerContext"];
tree: null | components["schemas"]["DependencyTreeNode"];
};
/**
@@ -5383,7 +5386,12 @@ export interface components {
/** @enum {unknown} */
op: "installing-package-alert";
packages: {
- [key: string]: "failed" | "installed" | "installing" | "queued";
+ [key: string]:
+ | "failed"
+ | "installed"
+ | "installing"
+ | "queued"
+ | "restart-required";
};
/**
* @default kernel
@@ -6308,10 +6316,18 @@ export interface components {
/** @enum {unknown} */
manager: "pip" | "pixi" | "poetry" | "rye" | "uv";
};
+ /** PackageManagerContext */
+ PackageManagerContext: {
+ /** @enum {unknown} */
+ kind: "package-manager";
+ name: string;
+ };
/** PackageOperationResponse */
PackageOperationResponse: {
/** @default null */
error?: string | null;
+ /** @default false */
+ restartRequired?: boolean;
success: boolean;
};
/**
@@ -6727,6 +6743,13 @@ export interface components {
kind: "safe-literal";
value: string;
};
+ /** SandboxPackageContext */
+ SandboxPackageContext: {
+ /** @enum {unknown} */
+ backend: "pixi" | "uv";
+ /** @enum {unknown} */
+ kind: "sandbox";
+ };
/** SaveAppConfigurationRequest */
SaveAppConfigurationRequest: {
config: Record<string, any>;
diff --git a/tests/_cli/test_cli.py b/tests/_cli/test_cli.py
index bc0f0ae545..4b637e1764 100644
--- a/tests/_cli/test_cli.py
+++ b/tests/_cli/test_cli.py
@@ -1336,6 +1336,59 @@ def test_cli_sandbox_edit_no_prompt(temp_marimo_file: str) -> None:
_check_contents(p, b"edit", contents)
[email protected]("command", ["edit", "run"])
+ ("option", "backend"), [("--sandbox=pixi", "pixi"), ("--sandbox", "uv")]
+)
[email protected]("directory", ["pixi", "uv"])
+def test_cli_sandbox_records_backend_and_preserves_paths(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ command: str,
+ option: 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.mkdir()
+ (notebook_dir / "nb.py").write_text(
+ codegen.generate_filecontents(
+ codes=["import marimo as mo"],
+ names=["one"],
+ cell_configs=[CellConfig()],
+ ),
+ encoding="utf-8",
+ )
+ runner = CliRunner()
+ captured: dict[str, object] = {}
+
+ 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"],
+ )
+
+ assert result.exit_code == 0, result.output
+ assert captured["sandbox_mode"] is SandboxMode.MULTI
+ assert captured["backend"] == backend
+
+
@pytest.mark.skipif(not HAS_UV, reason="uv is required for sandbox tests")
def test_cli_sandbox_edit_new_file() -> None:
with tempfile.TemporaryDirectory() as d:
@@ -1347,13 +1400,13 @@ def test_cli_sandbox_edit_new_file() -> None:
mock_run_in_sandbox.return_value = 0
result = runner.invoke(
cli_main,
- ["edit", path, "--headless", "--no-token", "--sandbox"],
+ ["edit", "--sandbox", path, "--headless", "--no-token"],
)
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["additional_features"] == ["lsp"]
+ assert call_kwargs.kwargs["extras"] == ["lsp"]
@pytest.mark.skipif(
@@ -1888,7 +1941,7 @@ def test_cli_with_custom_pyproject_config_no_file(tmp_path: Path) -> None:
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["additional_features"] == ["lsp"]
+ assert call_kwargs.kwargs["extras"] == ["lsp"]
# shell-completion has 1 input (value of $SHELL) & 3 outputs (return code, stdout, & stderr)
diff --git a/tests/_cli/test_cli_export_thumbnail.py b/tests/_cli/test_cli_export_thumbnail.py
index 7ffaf18560..f8a0840678 100644
--- a/tests/_cli/test_cli_export_thumbnail.py
+++ b/tests/_cli/test_cli_export_thumbnail.py
@@ -45,14 +45,14 @@ def test_thumbnail_sandbox_single_bootstrap_adds_playwright(
args: list[str],
*,
name: str | None = None,
- additional_features: list[str] | None = None,
- additional_deps: list[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 additional_features
+ del extras
captured["name"] = name
- captured["deps"] = additional_deps
+ captured["deps"] = command_deps
captured["mode"] = (extra_env or {}).get(
thumbnail_module._sandbox_mode_env
)
@@ -105,14 +105,14 @@ def test_thumbnail_sandbox_multi_bootstrap_sets_multi_mode(
args: list[str],
*,
name: str | None = None,
- additional_features: list[str] | None = None,
- additional_deps: list[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 additional_features
+ del extras
captured["name"] = name
- captured["deps"] = additional_deps
+ captured["deps"] = command_deps
captured["mode"] = (extra_env or {}).get(
thumbnail_module._sandbox_mode_env
)
diff --git a/tests/_cli/test_export_subprocess.py b/tests/_cli/test_export_subprocess.py
index 8b41b20e0d..78e9f10994 100644
--- a/tests/_cli/test_export_subprocess.py
+++ b/tests/_cli/test_export_subprocess.py
@@ -22,7 +22,11 @@ def test_export_runs_the_planned_command(isolated: bool) -> None:
else Environment(sys.executable, sys.prefix, "unchanged")
)
module = "marimo._environments.environment"
- target = f"{module}.launch_isolated" if isolated else f"{module}.launch"
+ target = (
+ "marimo._environments.backends.launch_fallback"
+ if isolated
+ else f"{module}.launch"
+ )
code = (
"import json,os,sys; print(json.dumps([os.getpid(), os.getsid(0)]))"
if os.name != "nt"
@@ -60,7 +64,7 @@ def test_export_failure_identifies_launcher_without_payload_or_credentials() ->
True,
)
with patch(
- "marimo._environments.environment.launch_isolated", return_value=plan
+ "marimo._environments.backends.launch_fallback", return_value=plan
):
with pytest.raises(click.ClickException) as error:
run_python_subprocess(
@@ -106,7 +110,7 @@ def test_export_interrupt_reaps_the_child(new_session: bool) -> None:
)
with (
patch(
- "marimo._environments.environment.launch_isolated",
+ "marimo._environments.backends.launch_fallback",
return_value=plan,
),
patch(
@@ -135,9 +139,9 @@ def test_export_sigterm_reaps_isolated_child(tmp_path) -> None:
code = f"""
import os, sys
from marimo._cli.export._common import SandboxTarget, run_python_subprocess
-from marimo._environments import environment
+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)"
-environment.launch_isolated = lambda *a, **kw: environment.ProcessPlan((sys.executable, '-c', child), dict(os.environ), True)
+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])
diff --git a/tests/_cli/test_sandbox.py b/tests/_cli/test_sandbox.py
index d7cbfd5a23..0494e4d6aa 100644
--- a/tests/_cli/test_sandbox.py
+++ b/tests/_cli/test_sandbox.py
@@ -21,6 +21,21 @@ from marimo._utils.inline_script_metadata import PyProjectReader
HAS_UV = DependencyManager.which("uv")
[email protected]("backend", ["uv", "pixi"])
+def test_missing_sandbox_backend_reports_install_instructions(
+ backend, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from marimo._cli.errors import MarimoCLIMissingDependencyError
+
+ monkeypatch.delenv("UV", raising=False)
+ monkeypatch.setenv("PATH", str(tmp_path))
+ monkeypatch.chdir(tmp_path)
+ with pytest.raises(MarimoCLIMissingDependencyError) as error:
+ run_in_sandbox(["edit", "--sandbox", "notebook.py"], backend=backend)
+
+ assert f"{backend} must be installed" in str(error.value)
+
+
def test_dependency_export_uses_notebook_directory(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
@@ -297,37 +312,6 @@ def test_construct_uv_cmd_empty_dependencies() -> None:
assert "--no-project" in uv_cmd
-def test_run_in_sandbox_reports_wrapped_metadata_timeout() -> None:
- from marimo._environments import script_metadata
-
- timeout = subprocess.TimeoutExpired(["uv", "add"], timeout=30)
- metadata_error = script_metadata.ScriptMetadataError("update failed")
- metadata_error.__cause__ = timeout
-
- with (
- patch("marimo._cli.sandbox.require_uv_bin"),
- patch(
- "marimo._cli.sandbox.script_metadata.ensure_marimo",
- side_effect=metadata_error,
- ),
- patch("marimo._cli.sandbox.script_metadata.ensure_requires_python"),
- patch(
- "marimo._cli.sandbox.construct_uv_command",
- return_value=["uv", "run"],
- ),
- patch("marimo._cli.sandbox.subprocess.Popen") as popen,
- patch("marimo._cli.sandbox.signal.signal"),
- patch("marimo._cli.sandbox.LOGGER.warning") as warning,
- ):
- popen.return_value.wait.return_value = 0
-
- assert run_in_sandbox(["edit", "notebook.py"], name="notebook.py") == 0
-
- warning.assert_called_once_with(
- "Timed out adding marimo to script metadata"
- )
-
-
def test_construct_uv_cmd_with_complex_args() -> None:
# Test complex command arguments are preserved
args = [
@@ -704,30 +688,51 @@ def _restore_signal_handlers():
os.name == "nt", reason="signal forwarding differs on Windows"
)
@pytest.mark.usefixtures("_restore_signal_handlers")
+ ("suffix", "metadata"),
+ [
+ (".md", "absent"),
+ (".qmd", "absent"),
+ (".md", "title"),
+ (".md", "pyproject"),
+ (".qmd", "header"),
+ ],
+)
def test_run_in_sandbox_from_script_environment(
- monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+ suffix: str,
+ metadata: str,
) -> None:
"""The provisioned path: a markdown notebook's manifest is
synchronized and marimo launches from the script environment."""
- from marimo._cli.sandbox import run_in_sandbox
monkeypatch.setenv("UV_CACHE_DIR", str(tmp_path.parent / "uv-cache"))
- notebook = tmp_path / "notebook.md"
- notebook.write_text(
- """---
-pyproject: |
- dependencies = []
----
-
-# Hello
-""",
- encoding="utf-8",
- )
+ notebook = tmp_path / f"notebook{suffix}"
+ frontmatter = {
+ "absent": "",
+ "title": "---\ntitle: Hello\n---\n",
+ "pyproject": "---\npyproject: |\n dependencies = []\n---\n",
+ "header": "---\nheader: |\n # Keep this preamble\n---\n",
+ }[metadata]
+ body = "\n# Hello\r\n\r\n```python\r\nprint('hello')\r\n```\r\n"
+ original = (frontmatter + body).encode("utf-8")
+ notebook.write_bytes(original)
code = run_in_sandbox(["--version"], name=str(notebook))
assert code == 0
+ assert notebook.read_bytes().endswith(body.encode("utf-8"))
+ if metadata == "pyproject":
+ assert notebook.read_bytes() == original
+ if metadata == "title":
+ assert "title: Hello" in notebook.read_text()
+ if metadata == "header":
+ from marimo._convert.markdown.to_ir import extract_frontmatter
+
+ saved, _ = extract_frontmatter(notebook.read_text())
+ assert "# Keep this preamble" in saved["header"]
# The carrier is deleted after synchronization.
assert not list(tmp_path.glob("*.py"))
@@ -740,7 +745,6 @@ pyproject: |
@pytest.mark.usefixtures("_restore_signal_handlers")
def test_run_in_sandbox_without_a_manifest() -> None:
"""No target means no manifest: marimo runs ephemerally."""
- from marimo._cli.sandbox import run_in_sandbox
code = run_in_sandbox(["--version"], name=None)
@@ -782,26 +786,80 @@ def test_sandbox_exit_codes_propagate(tmp_path: Path) -> None:
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"
+
+ 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"
+
+ mode, backend = resolve_sandbox("pixi", True, str(notebook))
+ assert mode is None
+
+
+def test_strip_sandbox_args() -> None:
+ from marimo._cli.sandbox import _strip_sandbox_args
+
+ assert _strip_sandbox_args(
+ ["-m", "marimo", "edit", "--sandbox", "nb.py"]
+ ) == ["-m", "marimo", "edit", "nb.py"]
+ assert _strip_sandbox_args(
+ ["-m", "marimo", "edit", "--sandbox=pixi", "nb.py"]
+ ) == ["-m", "marimo", "edit", "nb.py"]
+ assert _strip_sandbox_args(
+ ["-m", "marimo", "edit", "--sandbox", "pixi", "nb.py"]
+ ) == ["-m", "marimo", "edit", "pixi", "nb.py"]
+ assert _strip_sandbox_args(
+ ["-m", "marimo", "edit", "--sandbox", "uv"]
+ ) == ["-m", "marimo", "edit", "uv"]
+ assert _strip_sandbox_args(
+ ["-m", "marimo", "run", "--sandbox", "nb.py", "--", "--sandbox"]
+ ) == ["-m", "marimo", "run", "nb.py", "--", "--sandbox"]
+
+
+def test_no_reprompt_inside_a_sandbox(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A server launched inside a sandbox must not offer to re-wrap
+ itself in a second one."""
+ from marimo._cli.sandbox import maybe_prompt_run_in_sandbox
+ from marimo._config.settings import GLOBAL_SETTINGS
+
+ notebook = tmp_path / "nb.py"
+ notebook.write_text(
+ '# /// script\n# dependencies = ["numpy"]\n# ///\nimport marimo\n'
+ )
+
+ monkeypatch.setattr(GLOBAL_SETTINGS, "MANAGE_SCRIPT_METADATA", False)
+ monkeypatch.setattr(GLOBAL_SETTINGS, "SANDBOX_MODE", None)
+ monkeypatch.setattr(GLOBAL_SETTINGS, "SANDBOX_BACKEND", "pixi")
+ assert maybe_prompt_run_in_sandbox(str(notebook)) is False
+
+
@pytest.mark.parametrize(
("returncode", "expected"), [(0, 0), (7, 7), (-2, 130), (-15, 143)]
)
@pytest.mark.usefixtures("_restore_signal_handlers")
-def test_run_in_sandbox_normalizes_child_status(
+def test_sandbox_launch_normalizes_child_status(
returncode: int, expected: int
) -> None:
from unittest.mock import MagicMock, patch
+ from marimo._cli.sandbox import _wait_on_plan
from marimo._environments.environment import ProcessPlan
process = MagicMock()
process.wait.return_value = returncode
- with (
- patch("marimo._cli.sandbox.require_uv_bin"),
- patch("marimo._cli.sandbox.runtime_overlay", return_value=[]),
- patch(
- "marimo._cli.sandbox.environment.launch_isolated",
- return_value=ProcessPlan(argv=("uv",), env={}),
- ),
- patch("marimo._cli.sandbox.subprocess.Popen", return_value=process),
- ):
- assert run_in_sandbox(["--version"]) == expected
+ with patch("marimo._cli.sandbox.subprocess.Popen", return_value=process):
+ assert _wait_on_plan(ProcessPlan(argv=("uv",), env={})) == expected
diff --git a/tests/_code_mode/test_code_mode_context.py b/tests/_code_mode/test_code_mode_context.py
index 9cad631f66..6d4bf973d9 100644
--- a/tests/_code_mode/test_code_mode_context.py
+++ b/tests/_code_mode/test_code_mode_context.py
@@ -3,7 +3,7 @@ from __future__ import annotations
from contextlib import contextmanager
from typing import TYPE_CHECKING
-from unittest.mock import AsyncMock, patch
+from unittest.mock import AsyncMock, PropertyMock, patch
if TYPE_CHECKING:
from collections.abc import Generator
@@ -943,6 +943,53 @@ class TestPackages:
assert "pandas" in captured.out
[email protected]("operation", ["add", "remove"])
[email protected]("restart_required", [False, True])
+async def test_package_summary_reports_unsuccessful_outcomes(
+ k: Kernel,
+ capsys: pytest.CaptureFixture[str],
+ operation: str,
+ restart_required: bool,
+) -> None:
+ from marimo._messaging.notification import (
+ InstallingPackageAlertNotification,
+ )
+
+ with _ctx(k) as ctx:
+ pm = k.packages_callbacks.package_manager
+ assert pm is not None
+ method = "install" if operation == "add" else "uninstall"
+ with (
+ patch.object(
+ pm, method, new_callable=AsyncMock, return_value=False
+ ),
+ patch.object(
+ type(pm),
+ "restart_required",
+ new_callable=PropertyMock,
+ return_value=restart_required,
+ ),
+ ):
+ async with ctx as nb:
+ getattr(nb.packages, operation)("boltons")
+ output = capsys.readouterr().out
+ assert (
+ "changes saved for boltons; restart the kernel"
+ if restart_required
+ else f"failed to {method} boltons"
+ ) in output
+ assert "installed boltons" not in output
+ if operation == "add":
+ alerts = [
+ n
+ for n in k.stream.operations
+ if isinstance(n, InstallingPackageAlertNotification)
+ ]
+ assert alerts[-1].packages == {
+ "boltons": "restart-required" if restart_required else "failed"
+ }
+
+
class TestAutorunStaleState:
"""In autorun mode, downstream cells should not be marked stale."""
diff --git a/tests/_environments/test_environment.py b/tests/_environments/test_environment.py
index 7a4965fc47..34d0c2f22d 100644
--- a/tests/_environments/test_environment.py
+++ b/tests/_environments/test_environment.py
@@ -51,30 +51,6 @@ EMPTY_SCRIPT = f"""\
"""
-def test_requires_restart() -> None:
- first = Environment(
- python="/env/bin/python", root="/env", action="created"
- )
- unchanged = Environment(
- python="/env/bin/python", root="/env", action="unchanged"
- )
- updated = Environment(
- python="/env/bin/python", root="/env", action="updated"
- )
- replaced = Environment(
- python="/env/bin/python", root="/env", action="replaced"
- )
- moved = Environment(
- python="/other/bin/python", root="/other", action="unchanged"
- )
-
- assert not first.requires_restart(None)
- assert not unchanged.requires_restart(first)
- assert not updated.requires_restart(first)
- assert replaced.requires_restart(first)
- assert moved.requires_restart(first)
-
-
def test_process_env_targets_the_environment() -> None:
env = Environment(python="/env/bin/python", root="/env", action="created")
base = {"UV_PROJECT_ENVIRONMENT": "/project", "PATH": "/usr/bin"}
@@ -123,7 +99,6 @@ def test_sync_creates_and_reuses_the_environment(
again = sync(str(script), cwd=str(tmp_path))
assert again.action == "unchanged"
assert again.python == first.python
- assert not again.requires_restart(first)
@pytest.mark.skipif(not SUPPORTS_SYNC, reason="uv >= 0.7.21 required")
@@ -270,25 +245,34 @@ def test_report_actions_map_to_the_handle(
assert sync("nb.py").action == action
-def test_launch_without_overlay_is_direct() -> None:
+def test_launch_layers_over_the_activated_environment() -> None:
+ """Every launch goes through the layer, and uv is pointed at the
+ script environment rather than replacing it."""
+ from marimo._environments.overlay import RuntimeOverlay
+
env = Environment(python="/env/bin/python", root="/env", action="created")
- plan = launch(env, ["-m", "marimo"], base_env={"PATH": "/usr/bin"})
+ plan = launch(
+ env,
+ ["-m", "marimo"],
+ overlay=RuntimeOverlay(runtime="marimo==1.0"),
+ base_env={"PATH": "/usr/bin"},
+ )
- assert plan.argv == ("/env/bin/python", "-m", "marimo")
+ pairs = list(zip(plan.argv, plan.argv[1:], strict=False))
+ assert "--active" in plan.argv
+ assert ("--python", "/env/bin/python") in pairs
+ assert ("--with", "marimo==1.0") in pairs
+ assert plan.argv[-3:] == ("python", "-m", "marimo")
assert plan.env["VIRTUAL_ENV"] == "/env"
- assert not plan.start_new_session
+ assert plan.start_new_session
-def test_launcher_plans_start_a_new_session() -> None:
- env = Environment(python="/env/bin/python", root="/env", action="created")
-
- overlay = launch(env, ["-m", "marimo"], overlay=["marimo"])
+def test_isolated_launcher_plan_starts_a_new_session() -> None:
isolated = environment.launch_isolated(
- ["-m", "marimo"], overlay=["marimo"], python="3.13"
+ ["-m", "marimo"], requirements=["marimo"], python="3.13"
)
- assert overlay.start_new_session
assert isolated.start_new_session
@@ -315,11 +299,13 @@ def test_launch_overlay_chains_without_mutating(
encoding="utf-8",
)
+ from marimo._environments.overlay import RuntimeOverlay
+
env = sync(str(script), cwd=str(tmp_path))
plan = launch(
env,
["-c", "import six, idna, localpkg; print('chained')"],
- overlay=["idna", f"-e {pkg}"],
+ overlay=RuntimeOverlay(runtime="idna", command=(f"-e {pkg}",)),
)
result = subprocess.run(
@@ -353,7 +339,7 @@ def test_sync_streams_progress(
@pytest.mark.parametrize("editable", [False, True])
[email protected]("features", [[], ["sql", "lsp"]])
[email protected]("features", [[], ["recommended", "lsp"]])
def test_runtime_overlay_preserves_extras(
monkeypatch: pytest.MonkeyPatch, editable: bool, features: list[str]
) -> None:
@@ -361,10 +347,13 @@ def test_runtime_overlay_preserves_extras(
from marimo._version import __version__
monkeypatch.setattr(overlay, "is_editable", lambda _: editable)
- extras = "[sql,lsp]" if features else ""
+ extras = "[recommended,lsp]" if features else ""
expected = (
f"-e {overlay.marimo_dir()}{extras}"
if editable
else f"marimo{extras}=={__version__}"
)
- assert overlay.runtime_overlay(features, ["idna"]) == [expected, "idna"]
+ assert overlay.runtime_overlay(features, ["idna"]).requirements == (
+ expected,
+ "idna",
+ )
diff --git a/tests/_environments/test_pixi.py b/tests/_environments/test_pixi.py
new file mode 100644
index 0000000000..0907fd2015
--- /dev/null
+++ b/tests/_environments/test_pixi.py
@@ -0,0 +1,644 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from typing import TYPE_CHECKING
+
+import pytest
+
+from marimo._environments import pixi, script_metadata
+from marimo._environments.errors import (
+ EnvironmentManagerError,
+ SandboxRestartRequired,
+)
+from marimo._environments.overlay import RuntimeOverlay
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+posix_only = pytest.mark.skipif(
+ sys.platform == "win32", reason="stub executables are POSIX shell"
+)
+
+
+def _stub_pixi(tmp_path: Path, script: str) -> str:
+ path = tmp_path / "pixi"
+ path.write_text("#!/bin/sh\n" + script)
+ path.chmod(path.stat().st_mode | stat.S_IEXEC)
+ return str(path)
+
+
+@posix_only
+def test_sync_parses_the_install_report(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ root = tmp_path / "envs" / "Zoë's environment"
+ (root / "bin").mkdir(parents=True)
+ (root / "bin" / "python").touch()
+ # The message arrives styled; the parser must see through ANSI.
+ stub = _stub_pixi(
+ tmp_path,
+ 'printf "\\033[32m+\\033[0m The script environment has been '
+ f'installed at \'%s\'.\\n" "{root}" >&2\n',
+ )
+ monkeypatch.setattr(pixi, "find_pixi_bin", lambda: stub)
+
+ notebook = tmp_path / "nb.py"
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+ handle = pixi.sync(str(notebook))
+ assert handle.root == str(root)
+ assert handle.python == str(root / "bin" / "python")
+ assert handle.action == "updated"
+
+
[email protected]("active_root", [None, "/env", "/previous-env"])
+def test_pixi_sync_requires_restart_when_the_live_prefix_changes(
+ active_root: str | None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from marimo._environments.backends import PixiBackendAdapter
+ from marimo._environments.environment import Environment
+ from marimo._environments.script_metadata import MaterializedScript
+
+ synced = Environment(
+ python="/env/bin/python", root="/env", action="updated"
+ )
+ monkeypatch.setattr(pixi, "sync", lambda *_args, **_kwargs: synced)
+ active = (
+ Environment(
+ python=f"{active_root}/bin/python",
+ root=active_root,
+ action="unchanged",
+ )
+ if active_root is not None
+ else None
+ )
+
+ def synchronize() -> Environment:
+ return PixiBackendAdapter().sync(
+ MaterializedScript(path="/notebook.py", directory="/"),
+ python_override=None,
+ on_output=None,
+ active_environment=active,
+ )
+
+ if active_root == "/previous-env":
+ with pytest.raises(SandboxRestartRequired, match="Restart the kernel"):
+ synchronize()
+ else:
+ assert synchronize() == synced
+
+
+@posix_only
+def test_sync_surfaces_command_failures(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ stub = _stub_pixi(tmp_path, "echo 'no solution' >&2\nexit 7\n")
+ monkeypatch.setattr(pixi, "find_pixi_bin", lambda: stub)
+
+ with pytest.raises(pixi.PixiCommandError) as excinfo:
+ pixi.sync(str(tmp_path / "nb.py"))
+ assert excinfo.value.returncode == 7
+ assert "no solution" in str(excinfo.value)
+
+
+@posix_only
+def test_sync_refines_missing_script_metadata(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ stub = _stub_pixi(
+ tmp_path,
+ "echo 'The script does not contain a' >&2\n"
+ "echo 'PEP 723 metadata block' >&2\n"
+ "exit 1\n",
+ )
+ monkeypatch.setattr(pixi, "find_pixi_bin", lambda: stub)
+
+ with pytest.raises(pixi.PixiMissingScriptMetadataError):
+ pixi.sync(str(tmp_path / "nb.py"))
+
+
+@posix_only
+def test_add_reports_command_separately_from_backend_output(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+) -> None:
+ stub = _stub_pixi(tmp_path, "echo 'pixi output'\n")
+ monkeypatch.setattr(pixi, "find_pixi_bin", lambda: stub)
+ notebook = tmp_path / "nb.py"
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+ output: list[str] = []
+ commands: list[tuple[str, ...]] = []
+
+ pixi.add(
+ str(notebook),
+ "polars",
+ cwd=str(tmp_path),
+ on_output=output.append,
+ on_command=lambda command: commands.append(tuple(command)),
+ )
+
+ assert output == ["pixi output\n"]
+ assert commands == [
+ (stub, "add", "--script", str(notebook), "--pypi", "polars")
+ ]
+ assert capsys.readouterr().err == ""
+
+
+@posix_only
+ ("package", "expected"),
+ [
+ # `pixi update` refreshes the solve for a package it knows by name.
+ ("polars", ("update", "polars")),
+ # It does not take requirements; a constrained upgrade rewrites
+ # the manifest entry instead.
+ ("polars>=1.2.3", ("add", "--pypi", "polars>=1.2.3")),
+ ],
+)
+def test_upgrade_verb_depends_on_the_requirement_shape(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ package: str,
+ expected: tuple[str, ...],
+) -> None:
+ stub = _stub_pixi(tmp_path, "exit 0\n")
+ monkeypatch.setattr(pixi, "find_pixi_bin", lambda: stub)
+ notebook = tmp_path / "nb.py"
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+ commands: list[tuple[str, ...]] = []
+
+ pixi.add(
+ str(notebook),
+ package,
+ cwd=str(tmp_path),
+ upgrade=True,
+ on_command=lambda command: commands.append(tuple(command)),
+ )
+
+ verb, *arguments = expected
+ assert commands == [(stub, verb, "--script", str(notebook), *arguments)]
+
+
+@posix_only
+def test_low_level_add_is_silent_without_a_reporter(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+) -> None:
+ stub = _stub_pixi(tmp_path, "exit 0\n")
+ monkeypatch.setattr(pixi, "find_pixi_bin", lambda: stub)
+ notebook = tmp_path / "nb.py"
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+
+ pixi.add(str(notebook), "polars", cwd=str(tmp_path))
+
+ assert capsys.readouterr().err == ""
+
+
+def test_terminal_sandbox_reporter_uses_lifecycle_label(
+ capsys: pytest.CaptureFixture[str],
+) -> None:
+ from marimo._environments.sandbox import (
+ SandboxCommand,
+ TerminalSandboxReporter,
+ )
+
+ TerminalSandboxReporter().report(
+ SandboxCommand(
+ backend="pixi",
+ operation="remove",
+ argv=("/local/pixi", "remove", "obstore"),
+ )
+ )
+
+ assert capsys.readouterr().err == (
+ "Removing from sandbox: /local/pixi remove obstore\n"
+ )
+
+
+@posix_only
+def test_pixi_adapter_reports_without_polluting_progress(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from marimo._environments.backends import PixiBackendAdapter
+ from marimo._environments.sandbox import SandboxCommand
+ from marimo._environments.script_metadata import MaterializedScript
+
+ class Recorder:
+ def __init__(self) -> None:
+ self.commands: list[SandboxCommand] = []
+
+ def report(self, command: SandboxCommand) -> None:
+ self.commands.append(command)
+
+ stub = _stub_pixi(tmp_path, "echo 'pixi output'\n")
+ monkeypatch.setattr(pixi, "find_pixi_bin", lambda: stub)
+ notebook = tmp_path / "nb.py"
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+ recorder = Recorder()
+ output: list[str] = []
+
+ PixiBackendAdapter(recorder).add(
+ MaterializedScript(path=str(notebook), directory=str(tmp_path)),
+ "polars",
+ upgrade=False,
+ on_output=output.append,
+ )
+
+ assert output == ["pixi output\n"]
+ assert recorder.commands == [
+ SandboxCommand(
+ backend="pixi",
+ operation="add",
+ argv=(
+ stub,
+ "add",
+ "--script",
+ str(notebook),
+ "--pypi",
+ "polars",
+ ),
+ )
+ ]
+
+
+def test_pixi_adapter_uses_native_pypi_tree(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from marimo._environments.backends import PixiBackendAdapter
+ from marimo._environments.sandbox import PackageState, ResolvedPackage
+ from marimo._environments.script_metadata import MaterializedScript
+ from marimo._utils.uv_tree import DependencyTag, DependencyTreeNode
+
+ records = [
+ {
+ "name": "polars",
+ "version": "1.44.1",
+ "kind": "pypi",
+ },
+ {
+ "name": "polars_runtime_32",
+ "version": "1.44.1",
+ "kind": "pypi",
+ },
+ {
+ "name": "python",
+ "version": "3.14.7",
+ "kind": "conda",
+ },
+ {
+ "name": "libzlib",
+ "version": "1.3.2",
+ "kind": "conda",
+ },
+ {
+ "name": "xarray",
+ "version": "2026.7.0",
+ "kind": "pypi",
+ },
+ ]
+ monkeypatch.setattr(
+ pixi, "list_script_packages", lambda *_args, **_kwargs: records
+ )
+ monkeypatch.setattr(
+ pixi,
+ "tree_script_packages",
+ lambda *_args, **_kwargs: (
+ "Installed for: osx-arm64\n"
+ "├── polars 1.44.1\n"
+ "│ └── polars_runtime_32 1.44.1\n"
+ "├── xarray 2026.7.0\n"
+ "│ └── polars_runtime_32 1.44.1 (*)\n"
+ "└── python 3.14.7\n"
+ " └── libzlib 1.3.2\n"
+ ),
+ )
+ target = MaterializedScript(
+ path=str(tmp_path / "notebook.py"), directory=str(tmp_path)
+ )
+
+ state = PixiBackendAdapter().packages(target, environment=None)
+
+ assert state == PackageState(
+ packages=(
+ ResolvedPackage(name="polars", version="1.44.1"),
+ ResolvedPackage(name="polars_runtime_32", version="1.44.1"),
+ ResolvedPackage(name="xarray", version="2026.7.0"),
+ ),
+ tree=DependencyTreeNode(
+ name="<root>",
+ version=None,
+ tags=[],
+ dependencies=[
+ DependencyTreeNode(
+ name="polars",
+ version="1.44.1",
+ tags=[],
+ dependencies=[
+ DependencyTreeNode(
+ name="polars_runtime_32",
+ version="1.44.1",
+ tags=[],
+ dependencies=[],
+ )
+ ],
+ ),
+ DependencyTreeNode(
+ name="xarray",
+ version="2026.7.0",
+ tags=[],
+ dependencies=[
+ DependencyTreeNode(
+ name="polars_runtime_32",
+ version="1.44.1",
+ tags=[DependencyTag(kind="dedupe", value="true")],
+ dependencies=[],
+ )
+ ],
+ ),
+ ],
+ ),
+ )
+
+
+def test_launch_activates_the_conda_prefix(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from marimo._environments.environment import Environment
+ from marimo._environments.overlay import RuntimeOverlay
+
+ monkeypatch.setattr(pixi, "find_pixi_bin", lambda: "/stub/pixi")
+ root = str(tmp_path / "prefix")
+ handle = Environment(
+ python=os.path.join(root, "bin", "python"),
+ root=root,
+ action="updated",
+ )
+ plan = pixi.launch(
+ handle,
+ ["-m", "marimo"],
+ overlay=RuntimeOverlay(runtime="marimo==1.0"),
+ base_env={"PATH": "/usr/bin", "VIRTUAL_ENV": "/elsewhere"},
+ )
+ # The conventional prefix paths are exposed, and the process itself
+ # runs under uv's layer.
+ assert plan.argv[-2:] == ("-m", "marimo")
+ assert plan.env["CONDA_PREFIX"] == root
+ assert "VIRTUAL_ENV" not in plan.env
+ expected_paths = (
+ [
+ root,
+ os.path.join(root, "Library", "mingw-w64", "bin"),
+ os.path.join(root, "Library", "usr", "bin"),
+ os.path.join(root, "Library", "bin"),
+ os.path.join(root, "Scripts"),
+ os.path.join(root, "bin"),
+ ]
+ if os.name == "nt"
+ else [os.path.join(root, "bin")]
+ )
+ assert plan.env["PATH"] == os.pathsep.join([*expected_paths, "/usr/bin"])
+ assert plan.start_new_session
+
+
+def test_fallback_plan_reflects_this_interpreter() -> None:
+ """With no manifest there is nothing to sandbox; the plan runs this
+ interpreter, and inherited activation state must describe it rather
+ than an enclosing shell's."""
+ from marimo._environments import backends
+
+ plan = backends.launch_fallback(
+ ["-m", "example"],
+ base_env={
+ "VIRTUAL_ENV": "/stale/venv",
+ "UV_PROJECT_ENVIRONMENT": "/elsewhere",
+ "PATH": "/usr/bin",
+ },
+ )
+
+ assert plan.argv[0] == sys.executable
+ assert "UV_PROJECT_ENVIRONMENT" not in plan.env
+ if sys.prefix != sys.base_prefix:
+ assert plan.env["VIRTUAL_ENV"] == sys.prefix
+ else:
+ assert "VIRTUAL_ENV" not in plan.env
+
+
+def test_ensure_metadata_block_respects_shebangs(tmp_path: Path) -> None:
+ plain = tmp_path / "plain.py"
+ plain.write_text("print('hi')\n")
+ script_metadata.ensure_metadata_block(str(plain))
+ assert plain.read_text().startswith("# /// script\n")
+
+ executable = tmp_path / "executable.py"
+ executable.write_text("#!/usr/bin/env python\nprint('hi')\n")
+ script_metadata.ensure_metadata_block(str(executable))
+ lines = executable.read_text().splitlines()
+ assert lines[0] == "#!/usr/bin/env python"
+ assert lines[1] == "# /// script"
+
+ # A script that already has a block is left alone.
+ before = plain.read_text()
+ script_metadata.ensure_metadata_block(str(plain))
+ assert plain.read_text() == before
+
+
+@posix_only
+def test_ensure_marimo_adds_a_loose_requirement(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The manifest carries loose `marimo` for standalone
+ `pixi run --script`; the launch overlay owns the version, so no pin and
+ never a local path -- even from a development checkout."""
+ stub = _stub_pixi(tmp_path, 'echo "$@" > "$0.args"\n')
+ monkeypatch.setattr(pixi, "find_pixi_bin", lambda: stub)
+
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text('# /// script\n# dependencies = ["six"]\n# ///\n')
+
+ pixi.ensure_marimo(str(notebook))
+
+ recorded = (tmp_path / "pixi.args").read_text().split()
+ assert recorded == [
+ "add",
+ "--script",
+ str(notebook),
+ "--pypi",
+ "marimo",
+ ]
+
+
+ not pixi.find_pixi_bin(), reason="pixi is required for this test"
+)
+def test_live_pixi_mutation_after_rename_requires_restart(
+ tmp_path: Path,
+) -> None:
+ from marimo._environments.sandbox import NotebookSandbox
+
+ original = tmp_path / "original.py"
+ renamed = tmp_path / "renamed.py"
+ original.write_text(
+ '# /// script\n# dependencies = ["six==1.16.0"]\n'
+ '# [tool.pixi.workspace]\n# channels = ["conda-forge"]\n# ///\n'
+ )
+ running = pixi.sync(str(original), cwd=str(tmp_path))
+ sandbox = NotebookSandbox(str(original), "pixi", environment=running)
+ original.rename(renamed)
+ sandbox.rebind(str(renamed))
+
+ with pytest.raises(SandboxRestartRequired, match="Restart the kernel"):
+ sandbox.add("boltons")
+
+ assert sandbox.environment == running
+ assert "boltons" in renamed.read_text()
+ assert not original.exists()
+
+ # A later rejected dependency must not poison the saved manifest or
+ # prevent the user from restarting into the successful change.
+ before = renamed.read_text()
+ with pytest.raises(EnvironmentManagerError):
+ sandbox.add("six==999999")
+ assert renamed.read_text() == before
+ restarted = pixi.sync(str(renamed), cwd=str(tmp_path))
+ assert restarted.root != running.root
+
+
+ not pixi.find_pixi_bin(), reason="pixi is required for this test"
+)
+def test_live_pixi_upgrade_installs_the_reported_version(
+ tmp_path: Path,
+) -> None:
+ import subprocess
+
+ from marimo._environments.sandbox import NotebookSandbox
+
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text(
+ '# /// script\n# dependencies = ["six==1.16.0"]\n'
+ '# [tool.pixi.workspace]\n# channels = ["conda-forge"]\n# ///\n'
+ )
+ running = pixi.sync(str(notebook), cwd=str(tmp_path))
+ sandbox = NotebookSandbox(str(notebook), "pixi", environment=running)
+ sandbox.add("six", upgrade=True)
+ reported = next(
+ p.version for p in sandbox.packages().packages if p.name == "six"
+ )
+ installed = subprocess.check_output(
+ [
+ running.python,
+ "-c",
+ "from importlib.metadata import version; print(version('six'))",
+ ],
+ text=True,
+ )
+ assert installed.strip() == reported
+ assert reported != "1.16.0"
+
+
+ not pixi.find_pixi_bin(), reason="pixi is required for this test"
+)
[email protected]("enclosing", ["plain", "uv", "conda", "pixi"])
+def test_overlay_chains_the_conda_prefix(
+ tmp_path: Path, enclosing: str
+) -> None:
+ """The behavior UV_OVERLAY_SPEC floors: uv's ephemeral overlay
+ environment, created from the conda interpreter, chains the
+ prefix's site-packages with overlay-first precedence."""
+ import subprocess
+
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text(
+ "# /// script\n"
+ '# dependencies = ["six"]\n'
+ "#\n"
+ "# [tool.pixi.workspace]\n"
+ '# channels = ["conda-forge"]\n'
+ "# ///\n"
+ )
+ environment = pixi.sync(str(notebook), cwd=str(tmp_path))
+
+ # `attrs` stands in for the runtime requirement so the layer resolves
+ # cheaply; what matters is that it chains the prefix behind it.
+ base_env = os.environ.copy()
+ if enclosing == "uv":
+ base_env.update(
+ VIRTUAL_ENV="/outer/uv", UV_PROJECT_ENVIRONMENT="/outer/project"
+ )
+ elif enclosing in ("conda", "pixi"):
+ base_env.update(
+ CONDA_PREFIX="/outer/conda",
+ CONDA_PREFIX_1="/outer/base",
+ CONDA_SHLVL="2",
+ )
+ if enclosing == "pixi":
+ base_env.update(
+ PIXI_PROJECT_MANIFEST="/outer/pixi.toml",
+ PIXI_ENVIRONMENT_NAME="outer",
+ )
+ plan = pixi.launch(
+ environment,
+ [
+ "-c",
+ (
+ "import attrs, six, sys, os, json; "
+ "print('six', six.__file__); "
+ "print('exe', sys.executable); "
+ "print(json.dumps(dict(prefix=os.environ['CONDA_PREFIX'], "
+ "base=sys.base_prefix, overlay=sys.prefix, "
+ "venv=os.environ['VIRTUAL_ENV'], "
+ "path=os.environ['PATH'].split(os.pathsep), "
+ "pixi=os.environ.get('PIXI_ENVIRONMENT_NAME'))))"
+ ),
+ ],
+ overlay=RuntimeOverlay(runtime="attrs"),
+ base_env=base_env,
+ )
+ completed = subprocess.run(
+ list(plan.argv), env=plan.env, capture_output=True, text=True
+ )
+ assert completed.returncode == 0, completed.stderr
+ # six resolves from the conda prefix, attrs from the overlay, and
+ # the interpreter is uv's ephemeral chain -- not the prefix python.
+ assert environment.root in completed.stdout
+ assert environment.python not in completed.stdout.splitlines()[1]
+ import json
+
+ identity = json.loads(completed.stdout.splitlines()[-1])
+ assert identity["prefix"] == identity["base"] == environment.root
+ assert identity["venv"] == identity["overlay"] != environment.root
+ assert identity["pixi"] is None
+ expected_paths = [
+ os.path.dirname(completed.stdout.splitlines()[1].removeprefix("exe ")),
+ *pixi._activation_path_entries(environment.root),
+ ]
+ assert identity["path"][: len(expected_paths)] == expected_paths
+
+
+def test_command_env_drops_enclosing_activation(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ activation = {
+ "VIRTUAL_ENV": "/venv",
+ "UV_PROJECT_ENVIRONMENT": "/uv-project",
+ "CONDA_PREFIX": "/conda",
+ "CONDA_DEFAULT_ENV": "outer",
+ "PIXI_PROJECT_MANIFEST": "/pixi.toml",
+ "PIXI_PROJECT_ROOT": "/pixi",
+ "PIXI_ENVIRONMENT_NAME": "outer",
+ "PIXI_IN_SHELL": "1",
+ }
+ for key, value in activation.items():
+ monkeypatch.setenv(key, value)
+ monkeypatch.setenv("KEEP_ME", "preserved")
+ env = pixi.command_env()
+ assert not activation.keys() & env.keys()
+ assert env["KEEP_ME"] == "preserved"
diff --git a/tests/_environments/test_sandbox_interface.py b/tests/_environments/test_sandbox_interface.py
new file mode 100644
index 0000000000..6d09b209cd
--- /dev/null
+++ b/tests/_environments/test_sandbox_interface.py
@@ -0,0 +1,744 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import re
+import stat
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+from unittest.mock import patch
+
+import pytest
+
+from marimo._environments import script_metadata
+from marimo._environments.environment import Environment, ProcessPlan
+from marimo._environments.errors import (
+ EnvironmentManagerError,
+ SandboxRestartRequired,
+)
+from marimo._environments.overlay import RuntimeOverlay
+from marimo._environments.sandbox import (
+ NotebookSandbox,
+ PackageState,
+ ResolvedPackage,
+ SandboxCommand,
+ TerminalSandboxReporter,
+)
+from marimo._utils.uv_tree import DependencyTreeNode
+
+if TYPE_CHECKING:
+ from collections.abc import Mapping, Sequence
+
+ from marimo._environments.sandbox import LogCallback
+ from marimo._environments.script_metadata import MaterializedScript
+
+
+class FakeBackend:
+ name = "uv"
+
+ def __init__(self, root: Path) -> None:
+ self.root = root
+ self.sync_targets: list[str] = []
+ self.add_requests: list[str] = []
+ self.versions: dict[str, str] = {"obstore": "0.8.2"}
+
+ def ensure_available(self) -> None:
+ pass
+
+ def prepare_source(self, source: str) -> None:
+ del source
+
+ def add(
+ self,
+ target: MaterializedScript,
+ package: str,
+ *,
+ upgrade: bool,
+ on_output: LogCallback | None,
+ ) -> None:
+ del upgrade, on_output
+ self.add_requests.append(package)
+ path = Path(target.path)
+ content = path.read_text()
+ project = script_metadata.loads(content)
+ assert project is not None
+ dependencies = list(project.get("dependencies", []))
+ # A backend replaces a same-named entry when the request carries a
+ # constraint, and leaves it alone when the request is a bare name.
+ name = _requirement_name(package)
+ is_bare = re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", package)
+ for index, existing in enumerate(dependencies):
+ if _requirement_name(str(existing)) == name:
+ if not is_bare:
+ dependencies[index] = package
+ break
+ else:
+ dependencies.append(package)
+ project["dependencies"] = dependencies
+ path.write_text(
+ script_metadata.replace_block(
+ content, script_metadata.dumps(project)
+ )
+ )
+
+ def remove(
+ self,
+ target: MaterializedScript,
+ package: str,
+ *,
+ on_output: LogCallback | None,
+ ) -> None:
+ del on_output
+ path = Path(target.path)
+ content = path.read_text()
+ project = script_metadata.loads(content)
+ assert project is not None
+ project["dependencies"] = [
+ dependency
+ for dependency in project.get("dependencies", [])
+ if _requirement_name(str(dependency)) != _requirement_name(package)
+ ]
+ path.write_text(
+ script_metadata.replace_block(
+ content, script_metadata.dumps(project)
+ )
+ )
+
+ def sync(
+ self,
+ target: MaterializedScript,
+ *,
+ python_override: str | None,
+ on_output: LogCallback | None,
+ active_environment: Environment | None = None,
+ ) -> Environment:
+ del python_override, on_output, active_environment
+ self.sync_targets.append(target.path)
+ return Environment(
+ python=str(self.root / "bin" / "python"),
+ root=str(self.root),
+ action="updated",
+ )
+
+ def packages(
+ self,
+ target: MaterializedScript,
+ environment: Environment | None,
+ ) -> PackageState:
+ del target, environment
+ return PackageState(
+ packages=tuple(
+ ResolvedPackage(name=name, version=version)
+ for name, version in self.versions.items()
+ ),
+ tree=DependencyTreeNode(
+ name="<root>", version=None, tags=[], dependencies=[]
+ ),
+ )
+
+ def launch(
+ self,
+ environment: Environment,
+ args: Sequence[str],
+ *,
+ overlay: RuntimeOverlay,
+ base_env: Mapping[str, str] | None,
+ ) -> ProcessPlan:
+ del overlay, base_env
+ return ProcessPlan(argv=(environment.python, *args), env={})
+
+
+def _requirement_name(requirement: str) -> str:
+ match = re.match(r"[A-Za-z0-9][A-Za-z0-9._-]*", requirement.strip())
+ return match.group(0).lower() if match else requirement.lower()
+
+
+def test_add_edits_manifest_syncs_and_cleans_carrier(tmp_path: Path) -> None:
+ notebook = tmp_path / "notebook.md"
+ notebook.write_text(
+ "---\npyproject: |\n dependencies = []\n---\n\n# Hello\n"
+ )
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ sandbox.add("obstore")
+
+ assert sandbox.environment is not None
+ assert "obstore==0.8.2" in notebook.read_text()
+ assert len(adapter.sync_targets) == 1
+ assert not list(tmp_path.glob(".marimo-*.py"))
+
+
+def test_add_pins_a_bare_requirement_to_the_resolved_version(
+ tmp_path: Path,
+) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ sandbox.add("obstore")
+
+ assert adapter.add_requests == ["obstore", "obstore==0.8.2"]
+ assert '"obstore==0.8.2"' in notebook.read_text()
+ # Only the final, pinned manifest needs synchronization.
+ assert len(adapter.sync_targets) == 1
+
+
+def test_add_syncs_the_final_pin(tmp_path: Path) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text(
+ '# /// script\n# dependencies = ["obstore==0.7.0"]\n# ///\n'
+ )
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+ sync = adapter.sync
+
+ def synchronize(
+ target: MaterializedScript, **_kwargs: object
+ ) -> Environment:
+ assert script_metadata.loads(Path(target.path).read_text()) == {
+ "dependencies": ["obstore==0.8.2"]
+ }
+ return sync(target, python_override=None, on_output=None)
+
+ with patch.object(adapter, "sync", side_effect=synchronize):
+ sandbox.add("obstore", upgrade=True)
+
+
[email protected]("suffix", [".py", ".md", ".qmd"])
[email protected]("operation", ["add", "remove"])
[email protected]("error", [EnvironmentManagerError, KeyboardInterrupt])
+def test_failed_sync_restores_metadata_but_preserves_notebook_edits(
+ tmp_path: Path, suffix: str, operation: str, error: type[BaseException]
+) -> None:
+ notebook = tmp_path / f"notebook{suffix}"
+ if suffix == ".py":
+ notebook.write_text(
+ '# /// script\n# dependencies = ["obstore==0.7.0"]\n# ///\n\nx = 1\n'
+ )
+ else:
+ notebook.write_text(
+ '---\npyproject: |\n dependencies = ["obstore==0.7.0"]\n---\n\nx = 1\n'
+ )
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ def fail(*_args: object, **_kwargs: object) -> None:
+ notebook.write_text(notebook.read_text().replace("x = 1", "x = 2"))
+ raise error("interrupted mutation")
+
+ with patch.object(adapter, "sync", side_effect=fail):
+ if operation == "add":
+ with pytest.raises(error, match="interrupted mutation"):
+ sandbox.add("obstore", upgrade=True)
+ else:
+ with pytest.raises(error, match="interrupted mutation"):
+ sandbox.remove("obstore")
+
+ with script_metadata.materialized_for_environment(str(notebook)) as target:
+ assert script_metadata.loads(Path(target.path).read_text()) == {
+ "dependencies": ["obstore==0.7.0"]
+ }
+ assert "x = 2" in notebook.read_text()
+ assert not list(tmp_path.glob(".marimo-*.py"))
+
+
+def test_restart_required_keeps_successful_manifest_changes(
+ tmp_path: Path,
+) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ with patch.object(
+ adapter, "sync", side_effect=SandboxRestartRequired("restart")
+ ):
+ with pytest.raises(SandboxRestartRequired):
+ sandbox.add("obstore")
+
+ assert script_metadata.loads(notebook.read_text()) == {
+ "dependencies": ["obstore==0.8.2"]
+ }
+
+
[email protected]("stage", ["add", "packages"])
[email protected]("suffix", [".py", ".md"])
+def test_rejected_add_preserves_the_previous_successful_add(
+ tmp_path: Path, stage: str, suffix: str
+) -> None:
+ notebook = tmp_path / f"notebook{suffix}"
+ notebook.write_text(
+ "# /// script\n# dependencies = []\n# ///\n"
+ if suffix == ".py"
+ else "---\npyproject: |\n dependencies = []\n---\n\n# Notebook\n"
+ )
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+ sandbox.add("obstore")
+ before = notebook.read_text()
+
+ with patch.object(
+ adapter, stage, side_effect=EnvironmentManagerError("no solution")
+ ):
+ with pytest.raises(EnvironmentManagerError, match="no solution"):
+ sandbox.add("other")
+
+ assert notebook.read_text() == before
+
+
+ "dependency",
+ ["obstore[async]", "obstore[async]>=0.7.0", "obstore[async]==0.7.0"],
+)
+def test_add_keeps_declared_extras(tmp_path: Path, dependency: str) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text(
+ f'# /// script\n# dependencies = ["{dependency}"]\n# ///\n'
+ )
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ sandbox.add("obstore")
+
+ assert adapter.add_requests == ["obstore", "obstore[async]==0.8.2"]
+ assert '"obstore[async]==0.8.2"' in notebook.read_text()
+
+
+def test_terminal_reporter_redacts_url_credentials() -> None:
+ command = SandboxCommand(
+ backend="uv",
+ operation="add",
+ argv=(
+ "uv",
+ "add",
+ "pkg @ https://user:[email protected]/pkg.whl",
+ ),
+ )
+
+ with patch("marimo._cli.print.echo") as echo:
+ TerminalSandboxReporter().report(command)
+
+ rendered = echo.call_args.args[0]
+ assert "user:secret" not in rendered
+ assert "https://***@example.com/pkg.whl" in rendered
+
+
+ "requirement",
+ [
+ "obstore>=0.8",
+ "obstore==0.7.0",
+ "obstore @ https://example.com/obstore-0.8.2.whl",
+ "git+https://github.com/developmentseed/obstore",
+ ],
+)
+def test_add_writes_a_constrained_requirement_as_given(
+ tmp_path: Path, requirement: str
+) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ sandbox.add(requirement)
+
+ assert adapter.add_requests == [requirement]
+ assert requirement in notebook.read_text()
+
+
+def test_add_never_pins_the_runtime_dependency(tmp_path: Path) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+ adapter = FakeBackend(tmp_path / "environment")
+ adapter.versions["marimo"] = "0.24.0"
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ sandbox.add("marimo")
+
+ assert adapter.add_requests == ["marimo"]
+ assert '"marimo"' in notebook.read_text()
+
+
+def test_add_leaves_an_unresolved_requirement_open(tmp_path: Path) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ sandbox.add("windows-curses")
+
+ assert adapter.add_requests == ["windows-curses"]
+ assert '"windows-curses"' in notebook.read_text()
+
+
+def test_upgrade_reopens_an_exact_pin(tmp_path: Path) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text(
+ '# /// script\n# dependencies = ["obstore==0.7.0"]\n# ///\n'
+ )
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ sandbox.add("obstore", upgrade=True)
+
+ assert adapter.add_requests == ["obstore>=0.7.0", "obstore==0.8.2"]
+ assert '"obstore==0.8.2"' in notebook.read_text()
+
+
+def test_upgrade_floors_an_unpinned_requirement_at_the_environment(
+ tmp_path: Path,
+) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text('# /// script\n# dependencies = ["obstore"]\n# ///\n')
+ adapter = FakeBackend(tmp_path / "environment")
+ adapter.versions["obstore"] = "0.7.0+cpu"
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ sandbox.add("obstore", upgrade=True)
+
+ # The floor drops the local segment, which PEP 440 forbids in
+ # ordered comparisons; the pin keeps it.
+ assert adapter.add_requests == ["obstore>=0.7.0", "obstore==0.7.0+cpu"]
+
+
+def test_upgrade_pin_keeps_declared_extras(tmp_path: Path) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text(
+ '# /// script\n# dependencies = ["obstore[async]==0.7.0"]\n# ///\n'
+ )
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ sandbox.add("obstore", upgrade=True)
+
+ assert adapter.add_requests == [
+ "obstore[async]>=0.7.0",
+ "obstore[async]==0.8.2",
+ ]
+ assert '"obstore[async]==0.8.2"' in notebook.read_text()
+
+
+def test_remove_edits_markdown_manifest_and_syncs(tmp_path: Path) -> None:
+ notebook = tmp_path / "notebook.md"
+ notebook.write_text(
+ '---\npyproject: |\n dependencies = ["obstore"]\n---\n\n# Hi\n'
+ )
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ sandbox.remove("obstore")
+
+ assert "obstore" not in notebook.read_text()
+ assert len(adapter.sync_targets) == 1
+ assert not list(tmp_path.glob(".marimo-*.py"))
+
+
+def test_rebind_changes_the_source_for_the_next_operation(
+ tmp_path: Path,
+) -> None:
+ first = tmp_path / "first.py"
+ second = tmp_path / "second.py"
+ for notebook in (first, second):
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(first), "uv", adapter=adapter)
+
+ initial = sandbox.launch(
+ ["-m", "example"], overlay=RuntimeOverlay(runtime="marimo")
+ )
+
+ sandbox.rebind(str(second))
+
+ assert sandbox.source == str(second)
+ assert sandbox.environment_source == str(first)
+ assert sandbox.environment is not None
+ assert initial.argv[0] == sandbox.environment.python
+ assert adapter.sync_targets == [str(first)]
+
+ plan = sandbox.launch(
+ ["-m", "example"], overlay=RuntimeOverlay(runtime="marimo")
+ )
+
+ assert sandbox.environment_source == str(second)
+ assert adapter.sync_targets == [str(first), str(second)]
+ assert plan.argv[-2:] == ("-m", "example")
+
+
+def test_packages_does_not_synchronize(tmp_path: Path) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ state = sandbox.packages()
+
+ assert state.packages[0].name == "obstore"
+ assert adapter.sync_targets == []
+
+
+def test_unnamed_manifest_persists_on_rebind_and_cleans_up(
+ tmp_path: Path,
+) -> None:
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(None, "uv", adapter=adapter)
+ temporary_source = Path(sandbox.source)
+
+ sandbox.add("obstore")
+ saved = tmp_path / "saved.py"
+ saved.write_text("import marimo\n")
+ running_environment = sandbox.environment
+ sandbox.rebind(str(saved))
+
+ assert not temporary_source.exists()
+ assert "obstore" in saved.read_text()
+ assert sandbox.source == str(saved)
+ assert sandbox.environment == running_environment
+ assert sandbox.environment_source == str(temporary_source)
+
+
+def test_close_cleans_unnamed_manifest() -> None:
+ sandbox = NotebookSandbox(None, "uv", adapter=FakeBackend(Path("/env")))
+ temporary_source = Path(sandbox.source)
+
+ sandbox.close()
+
+ assert not temporary_source.exists()
+
+
+def test_add_after_rename_updates_the_running_environment(
+ tmp_path: Path,
+) -> None:
+ from marimo._environments.environment import sync
+ from tests._environments.test_environment import (
+ EMPTY_SCRIPT,
+ SUPPORTS_SYNC,
+ )
+
+ if not SUPPORTS_SYNC:
+ pytest.skip("uv script environments required")
+ original = tmp_path / "original.py"
+ renamed = tmp_path / "renamed.py"
+ original.write_text(EMPTY_SCRIPT)
+ running = sync(str(original))
+ sandbox = NotebookSandbox(str(original), "uv", environment=running)
+ original.rename(renamed)
+ sandbox.rebind(str(renamed))
+
+ sandbox.add("six==1.17.0")
+
+ assert sandbox.environment is not None
+ assert sandbox.environment.root == running.root
+ assert "six==1.17.0" in renamed.read_text()
+ assert not original.exists()
+
+ import subprocess
+
+ from marimo._environments.uv import require_uv_bin
+
+ result = subprocess.run(
+ [
+ require_uv_bin(),
+ "run",
+ "--no-project",
+ "--python",
+ running.python,
+ "--",
+ "python",
+ "-c",
+ "import six; print(six.__version__)",
+ ],
+ capture_output=True,
+ text=True,
+ )
+ assert result.returncode == 0, result.stderr
+ assert result.stdout.strip() == "1.17.0"
+ sandbox.remove("six")
+ assert "six" not in renamed.read_text()
+ # A future launch follows the renamed script's canonical identity.
+ canonical = sync(str(renamed))
+ assert canonical.root != running.root
+
+
+def test_runtime_dependency_cannot_be_removed(tmp_path: Path) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text('# /// script\n# dependencies = ["marimo"]\n# ///\n')
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+
+ with pytest.raises(
+ script_metadata.ScriptMetadataError,
+ match="managed by the sandbox runtime",
+ ):
+ sandbox.remove("marimo")
+
+ assert 'dependencies = ["marimo"]' in notebook.read_text()
+ assert adapter.sync_targets == []
+
+
+def test_package_view_hides_runtime_dependency(tmp_path: Path) -> None:
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text("# /// script\n# dependencies = []\n# ///\n")
+ adapter = FakeBackend(tmp_path / "environment")
+ sandbox = NotebookSandbox(str(notebook), "uv", adapter=adapter)
+ original_packages = adapter.packages
+
+ def packages_with_marimo(
+ target: MaterializedScript, environment: Environment | None
+ ) -> PackageState:
+ state = original_packages(target, environment)
+ assert state.tree is not None
+ state.tree.dependencies.append(
+ DependencyTreeNode(
+ name="marimo", version="0.24.0", tags=[], dependencies=[]
+ )
+ )
+ return PackageState(
+ packages=(
+ *state.packages,
+ ResolvedPackage(name="marimo", version="0.24.0"),
+ ),
+ tree=state.tree,
+ )
+
+ adapter.packages = packages_with_marimo # type: ignore[method-assign]
+
+ state = sandbox.packages()
+
+ assert [package.name for package in state.packages] == ["obstore"]
+ assert state.tree is not None
+ assert [node.name for node in state.tree.dependencies] == []
+
+
+def test_pixi_launch_layers_the_runtime_overlay_through_uv(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._environments import pixi
+ from marimo._environments.backends import PixiBackendAdapter
+
+ monkeypatch.setattr(pixi, "find_pixi_bin", lambda: "/stub/pixi")
+
+ root = tmp_path / "environment"
+ environment = Environment(
+ python=str(root / "bin" / "python"),
+ root=str(root),
+ action="unchanged",
+ )
+ checkout = tmp_path / "marimo-checkout"
+
+ plan = PixiBackendAdapter().launch(
+ environment,
+ ["-m", "marimo"],
+ overlay=RuntimeOverlay(
+ runtime=f"-e {checkout}", command=("nbformat",)
+ ),
+ base_env={"PATH": "/bin"},
+ )
+
+ pairs = list(zip(plan.argv, plan.argv[1:], strict=False))
+ assert plan.argv[:5] == (
+ "/stub/pixi",
+ "exec",
+ "--spec",
+ pixi.UV_OVERLAY_SPEC,
+ "uv",
+ )
+ assert ("--python", environment.python) in pairs
+ # A local runtime becomes --with-editable; other entries --with.
+ assert ("--with-editable", str(checkout)) in pairs
+ assert ("--with", "nbformat") in pairs
+ assert plan.argv[-2:] == ("-m", "marimo")
+ assert ("python", "-c") in pairs
+ assert plan.env["CONDA_PREFIX"] == str(root)
+ assert plan.start_new_session
+
+
+def test_pixi_package_list_exposes_only_managed_pypi_packages(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from marimo._environments import pixi
+ from marimo._environments.backends import PixiBackendAdapter
+ from marimo._environments.script_metadata import MaterializedScript
+
+ records = [
+ {
+ "name": "zlib",
+ "version": "1.3.1",
+ "kind": "conda",
+ "is_explicit": True,
+ "depends": [],
+ },
+ {
+ "name": "attrs",
+ "version": "25.3.0",
+ "kind": "pypi",
+ "is_explicit": True,
+ "depends": [],
+ },
+ ]
+ monkeypatch.setattr(
+ pixi,
+ "list_script_packages",
+ lambda *_args, **_kwargs: records,
+ )
+ monkeypatch.setattr(
+ pixi,
+ "tree_script_packages",
+ lambda *_args, **_kwargs: (
+ "Installed for: osx-arm64\n├── attrs 25.3.0\n└── zlib 1.3.1\n"
+ ),
+ )
+ target = MaterializedScript(
+ path=str(tmp_path / "notebook.py"), directory=str(tmp_path)
+ )
+
+ state = PixiBackendAdapter().packages(target, environment=None)
+
+ assert [(package.name, package.version) for package in state.packages] == [
+ ("attrs", "25.3.0")
+ ]
+ assert state.tree is not None
+ assert [node.name for node in state.tree.dependencies] == ["attrs"]
+
+
+ sys.platform == "win32", reason="stub executable is a POSIX shell"
+)
+def test_pixi_launch_does_not_require_uv(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from marimo._environments import pixi, uv
+
+ root = tmp_path / "pixi-environment"
+ (root / "bin").mkdir(parents=True)
+ (root / "bin" / "python").touch()
+ executable = tmp_path / "pixi"
+ executable.write_text(
+ "#!/bin/sh\n"
+ 'if [ "$2" = "--help" ]; then echo "--script"; exit 0; fi\n'
+ f"echo \"The script environment has been installed at '{root}'.\" >&2\n"
+ )
+ executable.chmod(executable.stat().st_mode | stat.S_IEXEC)
+ monkeypatch.setattr(pixi, "find_pixi_bin", lambda: str(executable))
+
+ def fail_uv() -> str:
+ raise AssertionError("pixi selected the uv executable")
+
+ monkeypatch.setattr(uv, "require_uv_bin", fail_uv)
+ notebook = tmp_path / "notebook.py"
+ notebook.write_text('# /// script\n# dependencies = ["marimo"]\n# ///\n')
+
+ sandbox = NotebookSandbox(str(notebook), "pixi")
+ plan = sandbox.launch(
+ ["-m", "example"], overlay=RuntimeOverlay(runtime="marimo")
+ )
+
+ # The overlay rides uv, but uv arrives through `pixi exec` -- never
+ # from the PATH (fail_uv above proves it was not consulted).
+ assert plan.argv[0] == str(executable)
+ assert plan.argv[1:5] == ("exec", "--spec", pixi.UV_OVERLAY_SPEC, "uv")
+ assert plan.env["CONDA_PREFIX"] == str(root)
+ assert plan.env["CONDA_DEFAULT_ENV"] == root.name
diff --git a/tests/_environments/test_uv.py b/tests/_environments/test_uv.py
index 062b7c5e92..b43e9e1e98 100644
--- a/tests/_environments/test_uv.py
+++ b/tests/_environments/test_uv.py
@@ -2,6 +2,7 @@
from __future__ import annotations
import sys
+from subprocess import CompletedProcess
from typing import TYPE_CHECKING, Any
import pytest
@@ -178,6 +179,128 @@ def test_script_edits_ignore_an_active_virtualenv(
assert "UV_PROJECT_ENVIRONMENT" not in env
+def test_uv_adapter_reports_the_exact_invocation(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ """The reported command is the argv the runner executes, not a
+ reconstruction that could drift from it."""
+ from unittest.mock import Mock, patch
+
+ from marimo._environments import uv as uv_module
+ from marimo._environments.backends import UvBackendAdapter
+ from marimo._environments.sandbox import SandboxCommand, SandboxReporter
+ from marimo._environments.script_metadata import MaterializedScript
+
+ executable = str(tmp_path / "uv")
+ monkeypatch.setenv("UV", executable)
+ recorder = Mock(spec=SandboxReporter)
+ target = MaterializedScript(
+ path=str(tmp_path / "nb.py"), directory=str(tmp_path)
+ )
+ with patch.object(
+ uv_module.subprocess,
+ "run",
+ return_value=CompletedProcess([], 0, stdout="", stderr=""),
+ ) as run:
+ UvBackendAdapter(recorder).add(
+ target, "polars", upgrade=False, on_output=None
+ )
+
+ expected = [
+ executable,
+ "--quiet",
+ "add",
+ "--script",
+ target.path,
+ "polars",
+ ]
+ assert run.call_args.args == (expected,)
+ assert run.call_args.kwargs["cwd"] == target.directory
+ recorder.report.assert_called_once_with(
+ SandboxCommand(backend="uv", operation="add", argv=tuple(expected))
+ )
+
+
+def test_uv_adapter_inspects_the_script_environment(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ from marimo._environments import uv as uv_module
+ from marimo._environments.backends import UvBackendAdapter
+ from marimo._environments.script_metadata import MaterializedScript
+
+ invocation: dict[str, object] = {}
+
+ def fake_uv(args: list[str], **kwargs: object) -> CompletedProcess[str]:
+ invocation["args"] = args
+ invocation.update(kwargs)
+ return CompletedProcess(
+ ["uv", *args],
+ 0,
+ stdout="test-package v1.0.0\n",
+ stderr="",
+ )
+
+ monkeypatch.setenv("VIRTUAL_ENV", "/outer")
+ monkeypatch.setenv("UV_PROJECT_ENVIRONMENT", "/project")
+ monkeypatch.setattr(uv_module, "uv", fake_uv)
+ target = MaterializedScript(
+ path=str(tmp_path / "nb.py"), directory=str(tmp_path)
+ )
+
+ UvBackendAdapter().packages(target, None)
+
+ assert invocation["args"] == [
+ "tree",
+ "--script",
+ str(tmp_path / "nb.py"),
+ ]
+ assert invocation["cwd"] == str(tmp_path)
+ env = invocation["env"]
+ assert isinstance(env, dict)
+ assert "VIRTUAL_ENV" not in env
+ assert "UV_PROJECT_ENVIRONMENT" not in env
+
+
+def test_uv_adapter_uses_the_deduplicated_tree(
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+ from marimo._environments import uv as uv_module
+ from marimo._environments.backends import UvBackendAdapter
+ from marimo._environments.script_metadata import MaterializedScript
+ from marimo._utils.uv_tree import DependencyTag
+
+ def fake_uv(
+ command: list[str], *, cwd: str, **_: object
+ ) -> CompletedProcess[str]:
+ assert cwd == str(tmp_path)
+ if "--no-dedupe" in command:
+ stdout = "root v1.0.0\n└── shared v2.0.0\n"
+ else:
+ stdout = (
+ "root v1.0.0\n"
+ "└── shared v2.0.0 (*)\n"
+ "(*) Package tree already displayed\n"
+ )
+ return CompletedProcess(
+ command,
+ 0,
+ stdout=stdout,
+ stderr="",
+ )
+
+ monkeypatch.setattr(uv_module, "uv", fake_uv)
+ target = MaterializedScript(
+ path=str(tmp_path / "notebook.py"), directory=str(tmp_path)
+ )
+
+ state = UvBackendAdapter().packages(target, environment=None)
+
+ assert state.tree is not None
+ assert state.tree.dependencies[0].dependencies[0].tags == [
+ DependencyTag(kind="dedupe", value="true")
+ ]
+
+
@pytest.mark.skipif(not HAS_UV, reason="uv required")
def test_stream_callback_runs_in_the_calling_thread(tmp_path: Path) -> None:
"""Kernel callbacks resolve their notification stream through
diff --git a/tests/_runtime/packages/test_package_managers.py b/tests/_runtime/packages/test_package_managers.py
index 88e792c9da..b5f6bf34b1 100644
--- a/tests/_runtime/packages/test_package_managers.py
+++ b/tests/_runtime/packages/test_package_managers.py
@@ -1,6 +1,5 @@
from __future__ import annotations
-import asyncio
import os
import sys
from typing import Any
@@ -63,6 +62,48 @@ def test_create_package_manager_without_python_exe() -> None:
assert uv_mgr._python_exe == PY_EXE
+def test_sandbox_backend_overrides_configured_package_manager() -> None:
+ from marimo._runtime.packages.sandbox_package_manager import (
+ SandboxPackageManager,
+ )
+
+ manager = create_package_manager(
+ "pip",
+ script_path="nb.py",
+ sandbox_backend="pixi",
+ )
+
+ assert isinstance(manager, SandboxPackageManager)
+ assert manager.name == "pixi"
+
+
+async def test_sandbox_package_manager_splits_package_operations() -> None:
+ from marimo._runtime.packages.sandbox_package_manager import (
+ SandboxPackageManager,
+ )
+
+ sandbox = MagicMock()
+ sandbox.backend = "uv"
+ sandbox.environment = None
+ manager = SandboxPackageManager(sandbox)
+
+ assert await manager._install(
+ "foo==1.0 bar[extra]",
+ upgrade=True,
+ log_callback=None,
+ )
+ assert await manager.uninstall("foo bar")
+
+ assert [call.args[0] for call in sandbox.add.call_args_list] == [
+ "foo==1.0",
+ "bar[extra]",
+ ]
+ assert [call.args[0] for call in sandbox.remove.call_args_list] == [
+ "foo",
+ "bar",
+ ]
+
+
@pytest.fixture
def uv_calls(monkeypatch: pytest.MonkeyPatch) -> list[list[str]]:
"""Capture uv invocations made through the script_metadata verbs."""
@@ -756,160 +797,3 @@ def test_pixi_list_packages_uses_utf8_encoding(mock_run: MagicMock):
call_kwargs = mock_run.call_args[1]
assert call_kwargs.get("encoding") == "utf-8"
assert call_kwargs.get("text") is True
-
-
-class TestUvScriptMode:
- """In script mode, package changes edit the manifest and synchronize
- its script environment, streaming uv's output."""
-
- def test_install_edits_and_syncs(self) -> None:
- from unittest.mock import patch
-
- pm = UvPackageManager(script_path="nb.py")
- logs: list[str] = []
-
- with (
- patch.object(script_metadata, "add_dependencies") as mock_add,
- patch(
- "marimo._environments.environment.sync_notebook"
- ) as mock_sync,
- ):
- success = asyncio.run(
- pm.install("foo bar", version=None, log_callback=logs.append)
- )
-
- assert success
- args, kwargs = mock_add.call_args
- assert args == ("nb.py", ["foo", "bar"])
- assert kwargs["on_output"] is not None
- mock_sync.assert_called_once()
- assert mock_sync.call_args.kwargs["on_output"] is not None
-
- def test_install_failure_streams_solver_message(self) -> None:
- from unittest.mock import patch
-
- from marimo._environments.uv import UvResolutionError
-
- pm = UvPackageManager(script_path="nb.py")
- logs: list[str] = []
- error = UvResolutionError(
- ["uv", "add"], 1, "", "No solution found when resolving"
- )
-
- with patch.object(
- script_metadata, "add_dependencies", side_effect=error
- ):
- success = asyncio.run(
- pm.install("foo", version=None, log_callback=logs.append)
- )
-
- assert not success
- assert any("No solution found" in line for line in logs)
-
- def test_uninstall_edits_and_syncs(self, tmp_path: Any) -> None:
- from unittest.mock import patch
-
- script = tmp_path / "nb.py"
- script.write_text(
- '# /// script\n# dependencies = ["foo"]\n# ///\n',
- encoding="utf-8",
- )
- pm = UvPackageManager(script_path=str(script))
-
- with (
- patch.object(script_metadata, "remove_dependencies") as mock_rm,
- patch(
- "marimo._environments.environment.sync_notebook"
- ) as mock_sync,
- ):
- success = asyncio.run(pm.uninstall("foo"))
-
- assert success
- assert mock_rm.call_args.args == (str(script), ["foo"])
- mock_sync.assert_called_once()
-
- def test_uninstall_reads_markdown_frontmatter(self, tmp_path: Any) -> None:
- from unittest.mock import patch
-
- notebook = tmp_path / "nb.md"
- notebook.write_text(
- '---\npyproject: |\n dependencies = ["foo"]\n---\n\n# Notebook\n',
- encoding="utf-8",
- )
- pm = UvPackageManager(script_path=str(notebook))
-
- with (
- patch.object(script_metadata, "remove_dependencies") as mock_rm,
- patch(
- "marimo._environments.environment.sync_notebook"
- ) as mock_sync,
- ):
- success = asyncio.run(pm.uninstall("foo"))
-
- assert success
- assert mock_rm.call_args.args == (str(notebook), ["foo"])
- mock_sync.assert_called_once()
-
- def test_uninstall_rejects_undeclared_packages(
- self, tmp_path: Any
- ) -> None:
- """A transitive dependency is not the notebook's to remove."""
- from unittest.mock import patch
-
- script = tmp_path / "nb.py"
- script.write_text(
- '# /// script\n# dependencies = ["foo"]\n# ///\n',
- encoding="utf-8",
- )
- pm = UvPackageManager(script_path=str(script))
-
- with patch.object(script_metadata, "remove_dependencies") as mock_rm:
- success = asyncio.run(pm.uninstall("transitive-dep"))
-
- assert not success
- mock_rm.assert_not_called()
-
- def test_metadata_update_skips_explicit_packages(
- self, uv_calls: list[list[str]]
- ) -> None:
- """install/uninstall own explicit packages; only namespace changes
- from cell registration reach the metadata writer."""
-
- class MockUvPackageManager(UvPackageManager):
- def _get_version_map(self) -> VersionMap:
- return VersionMap({"pyyaml": "1.0"})
-
- pm = MockUvPackageManager(script_path="nb.py")
-
- pm.update_notebook_script_metadata(
- filepath="nb.py",
- packages_to_add=["already-handled"],
- import_namespaces_to_add=["yaml"],
- upgrade=False,
- )
-
- assert uv_calls == [
- ["uv", "--quiet", "add", "--script", NB_ABSPATH, "pyyaml==1.0"],
- ]
-
- def test_metadata_update_does_not_pin_declared_dependency(
- self, tmp_path: Any, uv_calls: list[list[str]]
- ) -> None:
- notebook = tmp_path / "nb.py"
- notebook.write_text(
- '# /// script\n# dependencies = ["pyyaml"]\n# ///\n',
- encoding="utf-8",
- )
-
- class MockUvPackageManager(UvPackageManager):
- def _get_version_map(self) -> VersionMap:
- raise AssertionError("declared dependencies need no lookup")
-
- pm = MockUvPackageManager(script_path=str(notebook))
-
- assert pm.update_notebook_script_metadata(
- filepath=str(notebook),
- import_namespaces_to_add=["yaml"],
- upgrade=False,
- )
- assert uv_calls == []
diff --git a/tests/_runtime/packages/test_pypi_package_manager.py b/tests/_runtime/packages/test_pypi_package_manager.py
index fc55d00908..3c5fc5c344 100644
--- a/tests/_runtime/packages/test_pypi_package_manager.py
+++ b/tests/_runtime/packages/test_pypi_package_manager.py
@@ -1290,12 +1290,16 @@ async def test_script_uninstall_matches_distribution_name(
notebook.write_text(
'# /// script\n# dependencies = ["my-pkg[extra]>=1"]\n# ///\n'
)
- manager = UvPackageManager(script_path=str(notebook))
- with patch.object(
- manager, "_change_script_environment", return_value=True
- ) as change:
+ from marimo._environments.sandbox import NotebookSandbox
+ from marimo._runtime.packages.sandbox_package_manager import (
+ SandboxPackageManager,
+ )
+
+ sandbox = NotebookSandbox(str(notebook), "uv")
+ manager = SandboxPackageManager(sandbox)
+ with patch.object(sandbox, "_sync"):
assert await manager.uninstall(requirement)
- change.assert_called_once_with(str(notebook), remove=["my-pkg"])
+ assert "my-pkg" not in notebook.read_text()
@pytest.mark.asyncio
@@ -1304,7 +1308,13 @@ async def test_script_uninstall_preserves_transitive_dependency(
) -> None:
notebook = tmp_path / "notebook.py"
notebook.write_text('# /// script\n# dependencies = ["parent"]\n# ///\n')
- manager = UvPackageManager(script_path=str(notebook))
- with patch.object(manager, "_change_script_environment") as change:
+ from marimo._environments.sandbox import NotebookSandbox
+ from marimo._runtime.packages.sandbox_package_manager import (
+ SandboxPackageManager,
+ )
+
+ sandbox = NotebookSandbox(str(notebook), "uv")
+ manager = SandboxPackageManager(sandbox)
+ with patch.object(sandbox, "_sync") as change:
assert not await manager.uninstall("transitive")
change.assert_not_called()
diff --git a/tests/_runtime/test_manage_script_metadata.py b/tests/_runtime/test_manage_script_metadata.py
index 5a6f331661..27b6b420f4 100644
--- a/tests/_runtime/test_manage_script_metadata.py
+++ b/tests/_runtime/test_manage_script_metadata.py
@@ -1,6 +1,7 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+from functools import partial
from typing import TYPE_CHECKING, Any, cast
from unittest.mock import AsyncMock, Mock, call, patch
@@ -18,7 +19,7 @@ from marimo._runtime.commands import (
CommandMessage,
InstallPackagesCommand,
)
-from marimo._runtime.packages.package_manager import LogCallback
+from marimo._runtime.packages.package_manager import PackageManager
from marimo._runtime.packages.package_managers import create_package_manager
from marimo._runtime.packages.pypi_package_manager import (
MicropipPackageManager,
@@ -30,40 +31,10 @@ from tests.conftest import MockedKernel, mock_pyodide
if TYPE_CHECKING:
import pathlib
- from collections.abc import AsyncIterator, Callable
HAS_UV = DependencyManager.which("uv")
-def _make_stream_install(mock_pm: Mock) -> Any:
- """Create an async generator `stream_install` that delegates to
- the mock's `install` method, matching the base-class default
- behaviour so the existing test expectations hold."""
-
- async def stream_install(
- packages: list[str],
- *,
- versions: dict[str, str | None] | None = None,
- index_urls: list[str] | None = None,
- log_callback_factory: Callable[[str], LogCallback] | None = None,
- ) -> AsyncIterator[tuple[str, bool]]:
- del index_urls
- for pkg in packages:
- if mock_pm.attempted_to_install(package=pkg):
- yield (pkg, False)
- continue
- version = (versions or {}).get(pkg)
- cb = log_callback_factory(pkg) if log_callback_factory else None
- success = await mock_pm.install(
- pkg,
- version=version,
- log_callback=cb,
- )
- yield (pkg, success)
-
- return stream_install
-
-
@pytest.mark.skipif(not HAS_UV, reason="uv not installed")
@patch(
"marimo._runtime.packages.pypi_package_manager.UvPackageManager.is_in_uv_project",
@@ -541,7 +512,7 @@ async def test_install_missing_packages_with_streaming_logs(
broadcast_messages.append(msg)
# Mock package manager
- mock_package_manager = Mock(spec=PipPackageManager)
+ mock_package_manager = Mock(spec=PipPackageManager, restart_required=False)
mock_package_manager.name = "pip"
mock_package_manager.is_manager_installed.return_value = True
mock_package_manager.attempted_to_install.return_value = False
@@ -558,8 +529,8 @@ async def test_install_missing_packages_with_streaming_logs(
return True
mock_package_manager.install = AsyncMock(side_effect=mock_install)
- mock_package_manager.stream_install = _make_stream_install(
- mock_package_manager
+ mock_package_manager.stream_install = partial(
+ PackageManager.stream_install, mock_package_manager
)
# Set up packages callbacks
@@ -622,7 +593,7 @@ async def test_install_missing_packages_streaming_logs_failure(
broadcast_messages.append(msg)
# Mock package manager
- mock_package_manager = Mock(spec=PipPackageManager)
+ mock_package_manager = Mock(spec=PipPackageManager, restart_required=False)
mock_package_manager.name = "pip"
mock_package_manager.is_manager_installed.return_value = True
mock_package_manager.attempted_to_install.return_value = False
@@ -637,8 +608,8 @@ async def test_install_missing_packages_streaming_logs_failure(
return False # Installation failed
mock_package_manager.install = AsyncMock(side_effect=mock_install_fail)
- mock_package_manager.stream_install = _make_stream_install(
- mock_package_manager
+ mock_package_manager.stream_install = partial(
+ PackageManager.stream_install, mock_package_manager
)
k.packages_callbacks.package_manager = mock_package_manager
@@ -684,7 +655,7 @@ async def test_install_missing_packages_streaming_logs_multiple_packages(
broadcast_messages.append(msg)
# Mock package manager
- mock_package_manager = Mock(spec=PipPackageManager)
+ mock_package_manager = Mock(spec=PipPackageManager, restart_required=False)
mock_package_manager.name = "pip"
mock_package_manager.is_manager_installed.return_value = True
mock_package_manager.attempted_to_install.return_value = False
@@ -704,8 +675,8 @@ async def test_install_missing_packages_streaming_logs_multiple_packages(
return True
mock_package_manager.install = AsyncMock(side_effect=mock_install)
- mock_package_manager.stream_install = _make_stream_install(
- mock_package_manager
+ mock_package_manager.stream_install = partial(
+ PackageManager.stream_install, mock_package_manager
)
k.packages_callbacks.package_manager = mock_package_manager
@@ -767,7 +738,7 @@ async def test_install_missing_packages_no_logs_backward_compatibility(
broadcast_messages.append(msg)
# Mock package manager that doesn't use log callbacks
- mock_package_manager = Mock(spec=PipPackageManager)
+ mock_package_manager = Mock(spec=PipPackageManager, restart_required=False)
mock_package_manager.name = "pip"
mock_package_manager.is_manager_installed.return_value = True
mock_package_manager.attempted_to_install.return_value = False
@@ -782,8 +753,8 @@ async def test_install_missing_packages_no_logs_backward_compatibility(
mock_package_manager.install = AsyncMock(
side_effect=mock_install_old_style
)
- mock_package_manager.stream_install = _make_stream_install(
- mock_package_manager
+ mock_package_manager.stream_install = partial(
+ PackageManager.stream_install, mock_package_manager
)
k.packages_callbacks.package_manager = mock_package_manager
@@ -827,7 +798,7 @@ async def test_install_logs_reach_the_stream_from_worker_threads(
current = k.packages_callbacks.package_manager
assert current is not None
- fake = Mock()
+ fake = Mock(restart_required=False)
fake.name = current.name
fake.is_manager_installed.return_value = True
fake.attempted_to_install.return_value = False
@@ -849,7 +820,7 @@ async def test_install_logs_reach_the_stream_from_worker_threads(
return True
fake.install = install
- fake.stream_install = _make_stream_install(fake)
+ fake.stream_install = partial(PackageManager.stream_install, fake)
k.packages_callbacks.package_manager = fake
await k.packages_callbacks.install_missing_packages(
diff --git a/tests/_runtime/test_sandbox_lifecycle.py b/tests/_runtime/test_sandbox_lifecycle.py
new file mode 100644
index 0000000000..6d0d30cdeb
--- /dev/null
+++ b/tests/_runtime/test_sandbox_lifecycle.py
@@ -0,0 +1,237 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import asyncio
+import importlib.metadata
+import subprocess
+from typing import TYPE_CHECKING
+from unittest.mock import MagicMock
+
+import pytest
+
+from marimo._config.settings import GLOBAL_SETTINGS
+from marimo._environments import script_metadata
+from marimo._environments.overlay import RuntimeOverlay
+from marimo._environments.sandbox import NotebookSandbox
+from marimo._environments.uv import is_uv_available
+from marimo._runtime.commands import ExecuteCellCommand
+from marimo._runtime.packages.sandbox_package_manager import (
+ SandboxPackageManager,
+)
+from marimo._utils.inline_script_metadata import PyProjectReader
+from tests._environments.test_sandbox_interface import FakeBackend
+from tests._runtime._helpers.factories import default_app_metadata
+from tests._runtime._helpers.session import mocked_kernel_session
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+
[email protected](not is_uv_available(), reason="uv is required")
[email protected]("suffix", [".py", ".md"])
+async def test_cell_imports_record_transitive_sandbox_dependencies(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, suffix: str
+) -> None:
+ notebook = tmp_path / f"notebook{suffix}"
+ dependencies = ["marimo", "click>=8"] if suffix == ".py" else ["click>=8"]
+ project = {"dependencies": dependencies}
+ notebook.write_text(
+ script_metadata.dumps(project) + "\n"
+ if suffix == ".py"
+ else '---\npyproject: |\n dependencies = ["click>=8"]\n---\n\n# Notebook\n'
+ )
+ sandbox = NotebookSandbox(str(notebook), "uv")
+ plan = sandbox.launch(
+ ["-m", "marimo"], overlay=RuntimeOverlay(runtime="marimo")
+ )
+ assert sandbox.environment is not None
+ prefix_version = (
+ await asyncio.to_thread(
+ subprocess.check_output,
+ [
+ sandbox.environment.python,
+ "-c",
+ (
+ "from importlib.metadata import distributions; "
+ "print(next((d.version for d in distributions() "
+ "if d.metadata['Name'] == 'parso'), ''))"
+ ),
+ ],
+ text=True,
+ )
+ ).strip()
+ if suffix == ".md":
+ # The Markdown prefix lacks parso; the running kernel's runtime
+ # environment still supplies it through marimo's dependencies.
+ assert prefix_version == ""
+ else:
+ assert prefix_version
+ installed_version = importlib.metadata.version("parso")
+ for key, value in plan.env.items():
+ if key.startswith("MARIMO_SANDBOX_"):
+ monkeypatch.setenv(key, value)
+ monkeypatch.setattr(GLOBAL_SETTINGS, "SANDBOX_MODE", "single")
+ monkeypatch.setattr(GLOBAL_SETTINGS, "MANAGE_SCRIPT_METADATA", True)
+
+ with mocked_kernel_session(
+ app_metadata=default_app_metadata(filename=str(notebook))
+ ) as session:
+ session.kernel._maybe_register_cell(
+ "0",
+ "import parso\nimport os\nimport click\nimport missing_package",
+ stale=False,
+ )
+
+ assert set(
+ PyProjectReader.from_filename(str(notebook)).dependencies
+ ) == {
+ *dependencies,
+ f"parso=={installed_version}",
+ }
+
+ # Registering another import must not rewrite the saved requirement.
+ before = notebook.read_bytes()
+ session.kernel._maybe_register_cell(
+ "1", "import parso as other_parso", stale=False
+ )
+ assert notebook.read_bytes() == before
+
+ # An explicit install owns its requirement; the import callback must
+ # not replace that range with an exact pin or redo the install edit.
+ manager = session.kernel.packages_callbacks.package_manager
+ assert isinstance(manager, SandboxPackageManager)
+ assert await manager.install("parso>=0.8", version=None)
+ before = notebook.read_bytes()
+ assert manager.update_notebook_script_metadata(
+ str(notebook),
+ packages_to_add=["parso"],
+ import_namespaces_to_add=["parso"],
+ upgrade=False,
+ )
+ assert notebook.read_bytes() == before
+
+
[email protected]("operation", ["install", "uninstall"])
+async def test_restart_required_batch_saves_every_requirement(
+ operation: str,
+) -> None:
+ from marimo._environments.errors import (
+ EnvironmentManagerError,
+ SandboxRestartRequired,
+ )
+ from marimo._environments.sandbox import NotebookSandbox
+
+ sandbox = MagicMock(spec=NotebookSandbox)
+ sandbox.backend = "pixi"
+ sandbox.environment = None
+ mutation = sandbox.add if operation == "install" else sandbox.remove
+ mutation.side_effect = SandboxRestartRequired("Restart the kernel")
+ manager = SandboxPackageManager(sandbox)
+
+ async def mutate() -> bool:
+ if operation == "install":
+ return await manager.install("boltons six", version=None)
+ return await manager.uninstall("boltons six")
+
+ assert not await mutate()
+ assert [call.args[0] for call in mutation.call_args_list] == [
+ "boltons",
+ "six",
+ ]
+ assert (manager.restart_required, manager.last_error) == (True, None)
+
+ # A subsequent solver failure is a failure, not another saved-change result.
+ mutation.side_effect = EnvironmentManagerError("No solution")
+ assert not await mutate()
+ assert (manager.restart_required, manager.last_error) == (
+ False,
+ "No solution",
+ )
+
+ mutation.side_effect = None
+ assert await mutate()
+ assert (manager.restart_required, manager.last_error) == (False, None)
+
+
+async def test_rename_rebinds_packages_before_rerunning_cells(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from marimo._environments import backends
+
+ original = tmp_path / "original.py"
+ renamed = tmp_path / "renamed.py"
+ original.write_text("# /// script\n# dependencies = []\n# ///\n")
+ adapter = FakeBackend(tmp_path / "environment")
+ monkeypatch.setattr(backends, "adapter_for", lambda *_args: adapter)
+ monkeypatch.setattr(GLOBAL_SETTINGS, "SANDBOX_MODE", "multi")
+ with mocked_kernel_session(
+ app_metadata=default_app_metadata(filename=str(original)),
+ reactive_mode="autorun",
+ ) as session:
+ kernel = session.kernel
+ manager = kernel.packages_callbacks.package_manager
+ assert isinstance(manager, SandboxPackageManager)
+ # A cell dependent on __file__ can request packages during rename.
+ kernel.globals["install"] = lambda: manager._sandbox.add("obstore")
+ await kernel.run(
+ [
+ ExecuteCellCommand(
+ cell_id="0", code="path = __file__; install()"
+ )
+ ]
+ )
+ assert not kernel.errors
+ original.rename(renamed)
+
+ await kernel.rename_file(str(renamed))
+
+ assert not kernel.errors
+ assert adapter.sync_targets[-1] == str(renamed)
+ assert not original.exists()
+ assert "obstore" in renamed.read_text()
+
+
+async def test_unnamed_sandbox_keeps_manifest_and_manager_on_save(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from marimo._environments import backends
+ from marimo._environments.overlay import RuntimeOverlay
+ from marimo._environments.sandbox import NotebookSandbox
+
+ adapter = FakeBackend(tmp_path / "environment")
+ monkeypatch.setattr(backends, "adapter_for", lambda *_args: adapter)
+ outer = NotebookSandbox(None, "uv")
+ plan = outer.launch(
+ ["-m", "marimo"], overlay=RuntimeOverlay(runtime="marimo")
+ )
+ for key, value in plan.env.items():
+ if key.startswith("MARIMO_SANDBOX_"):
+ monkeypatch.setenv(key, value)
+ monkeypatch.setattr(GLOBAL_SETTINGS, "SANDBOX_MODE", "single")
+ try:
+ with mocked_kernel_session(
+ app_metadata=default_app_metadata(filename=None)
+ ) as session:
+ kernel = session.kernel
+ manager = kernel.packages_callbacks.package_manager
+ assert isinstance(manager, SandboxPackageManager)
+ assert await manager.install("obstore", version=None)
+ saved = tmp_path / "saved.py"
+ saved.write_text("import marimo\n")
+
+ # MULTI's session owns and releases the temporary manifest;
+ # the kernel must follow the binding without copying it again.
+ outer.rebind(str(saved))
+
+ await kernel.rename_file(str(saved))
+ kernel.packages_callbacks.update_package_manager("pip")
+
+ assert kernel.packages_callbacks.package_manager is manager
+ assert "obstore==0.8.2" in saved.read_text()
+ assert "requires-python" in saved.read_text()
+ assert await manager.uninstall("obstore")
+ assert "obstore" not in saved.read_text()
+ assert adapter.sync_targets[-1] == str(saved)
+ finally:
+ outer.close()
diff --git a/tests/_server/api/endpoints/test_files.py b/tests/_server/api/endpoints/test_files.py
index 45552e0492..3f1500f15e 100644
--- a/tests/_server/api/endpoints/test_files.py
+++ b/tests/_server/api/endpoints/test_files.py
@@ -62,6 +62,53 @@ def test_rename(client: TestClient) -> None:
try_assert_n_times(5, _new_path_exists)
+@with_session(SESSION_ID)
+def test_rename_prepares_file_before_notifying_kernel(
+ client: TestClient,
+) -> None:
+ session = get_session_manager(client).get_session(SESSION_ID)
+ assert session is not None
+ assert session.app_file_manager.path is not None
+ original = Path(session.app_file_manager.path)
+ renamed = original.with_name(f"{original.stem}_renamed.py")
+
+ def notify(*args: object, **kwargs: object) -> None:
+ del args, kwargs
+ assert renamed.exists()
+ assert not original.exists()
+ assert session.app_file_manager.path == str(renamed)
+
+ with patch.object(
+ session, "put_control_request", side_effect=notify
+ ) as put:
+ response = client.post(
+ "/api/kernel/rename",
+ headers=HEADERS,
+ json={"filename": str(renamed)},
+ )
+ assert response.json() == {"success": True}
+ put.assert_called_once()
+
+
+@with_session(SESSION_ID)
+def test_failed_rename_does_not_notify_kernel(client: TestClient) -> None:
+ session = get_session_manager(client).get_session(SESSION_ID)
+ assert session is not None
+ assert session.app_file_manager.path is not None
+ original = Path(session.app_file_manager.path)
+ occupied = original.with_name(f"{original.stem}_occupied.py")
+ occupied.write_text("# An unrelated notebook\n")
+ with patch.object(session, "put_control_request") as put:
+ response = client.post(
+ "/api/kernel/rename",
+ headers=HEADERS,
+ json={"filename": str(occupied)},
+ )
+ assert response.status_code == 400
+ put.assert_not_called()
+ assert occupied.read_text() == "# An unrelated notebook\n"
+
+
@pytest.mark.flaky(reruns=5)
@with_session(SESSION_ID)
def test_read_code(client: TestClient) -> None:
diff --git a/tests/_server/api/endpoints/test_packages.py b/tests/_server/api/endpoints/test_packages.py
index 07f421efa4..7a3736df91 100644
--- a/tests/_server/api/endpoints/test_packages.py
+++ b/tests/_server/api/endpoints/test_packages.py
@@ -22,9 +22,59 @@ HEADERS = {
}
[email protected]("operation", ["add", "remove"])
[email protected]("restart_required", [True, False])
+def test_sandbox_failure_returns_actionable_message(
+ client: TestClient,
+ monkeypatch: pytest.MonkeyPatch,
+ operation: str,
+ restart_required: bool,
+) -> None:
+ from marimo._environments.errors import SandboxRestartRequired
+ from marimo._environments.pixi import PixiError
+ from marimo._environments.sandbox import NotebookSandbox
+ from marimo._runtime.packages.sandbox_package_manager import (
+ SandboxPackageManager,
+ )
+
+ message = (
+ "Your dependency changes are saved, but Pixi installed them in a new "
+ "environment. Restart the kernel to use the updated dependencies. "
+ "Restarting clears in-memory variables."
+ )
+ sandbox = MagicMock(spec=NotebookSandbox)
+ sandbox.backend = "pixi"
+ sandbox.environment = None
+ getattr(sandbox, operation).side_effect = (
+ SandboxRestartRequired(message)
+ if restart_required
+ else PixiError(message)
+ )
+ manager = SandboxPackageManager(sandbox)
+ monkeypatch.setattr(
+ "marimo._server.api.endpoints.packages._get_package_manager",
+ lambda _request: manager,
+ )
+
+ response = client.post(
+ f"/api/packages/{operation}",
+ headers=HEADERS,
+ json={"package": "boltons"},
+ )
+
+ assert response.status_code == 200
+ assert response.json() == {
+ "success": False,
+ "error": None if restart_required else message,
+ "restartRequired": restart_required,
+ }
+
+
@pytest.fixture
def mock_package_manager(monkeypatch: pytest.MonkeyPatch) -> PackageManager:
mock_manager = MagicMock(spec=PackageManager)
+ mock_manager.restart_required = False
+ mock_manager.name = "pip"
mock_manager.install = AsyncMock(return_value=True)
mock_manager.uninstall = AsyncMock(return_value=True)
mock_manager.list_packages = MagicMock(
@@ -50,7 +100,11 @@ def test_add_package(client: TestClient, mock_package_manager: Mock) -> None:
json={"package": "test-package"},
)
assert response.status_code == 200
- assert response.json() == {"success": True, "error": None}
+ assert response.json() == {
+ "success": True,
+ "error": None,
+ "restartRequired": False,
+ }
mock_package_manager.install.assert_called_once_with(
"test-package", version=None, upgrade=False, group=None
)
@@ -77,7 +131,11 @@ def test_remove_package(
json={"package": "test-package"},
)
assert response.status_code == 200
- assert response.json() == {"success": True, "error": None}
+ assert response.json() == {
+ "success": True,
+ "error": None,
+ "restartRequired": False,
+ }
mock_package_manager.uninstall.assert_called_once_with(
"test-package", group=None
)
@@ -101,9 +159,7 @@ def test_list_packages(client: TestClient, mock_package_manager: Mock) -> None:
headers=HEADERS,
)
assert response.status_code == 200
- assert response.json() == {
- "packages": ["package1", "package2"],
- }
+ assert response.json() == {"packages": ["package1", "package2"]}
mock_package_manager.list_packages.assert_called_once()
@@ -140,6 +196,7 @@ def test_add_package_failure(
assert response.json() == {
"success": False,
"error": "Failed to install test-package. See terminal for error logs.",
+ "restartRequired": False,
}
@@ -156,6 +213,7 @@ def test_remove_package_failure(
assert response.json() == {
"success": False,
"error": "Failed to uninstall test-package. See terminal for error logs.",
+ "restartRequired": False,
}
@@ -169,7 +227,11 @@ def test_add_package_with_upgrade(
json={"package": "test-package", "upgrade": True},
)
assert response.status_code == 200
- assert response.json() == {"success": True, "error": None}
+ assert response.json() == {
+ "success": True,
+ "error": None,
+ "restartRequired": False,
+ }
mock_package_manager.install.assert_called_once_with(
"test-package", version=None, upgrade=True, group=None
)
@@ -185,7 +247,11 @@ def test_add_package_without_upgrade(
json={"package": "test-package", "upgrade": False},
)
assert response.status_code == 200
- assert response.json() == {"success": True, "error": None}
+ assert response.json() == {
+ "success": True,
+ "error": None,
+ "restartRequired": False,
+ }
mock_package_manager.install.assert_called_once_with(
"test-package", version=None, upgrade=False, group=None
)
@@ -389,6 +455,7 @@ def mock_package_manager_with_tree(
) -> PackageManager:
"""Mock package manager with dependency tree support."""
mock_manager = MagicMock(spec=PackageManager)
+ mock_manager.name = "uv"
mock_manager.is_manager_installed.return_value = True
from marimo._server.models.packages import DependencyTreeNode
@@ -426,15 +493,22 @@ def test_dependency_tree(
headers=HEADERS,
)
assert response.status_code == 200
- result = response.json()
- assert "tree" in result
- tree = result["tree"]
- assert tree is not None
- assert tree["name"] == "root"
- assert tree["version"] == "1.0.0"
- assert len(tree["dependencies"]) == 1
- assert tree["dependencies"][0]["name"] == "child"
- assert tree["dependencies"][0]["version"] == "0.1.0"
+ assert response.json() == {
+ "tree": {
+ "name": "root",
+ "version": "1.0.0",
+ "tags": [],
+ "dependencies": [
+ {
+ "name": "child",
+ "version": "0.1.0",
+ "tags": [{"kind": "extra", "value": "dev"}],
+ "dependencies": [],
+ }
+ ],
+ },
+ "context": {"kind": "package-manager", "name": "uv"},
+ }
mock_package_manager_with_tree.dependency_tree.assert_called_once()
@@ -448,11 +522,49 @@ def test_dependency_tree_no_tree(
headers=HEADERS,
)
assert response.status_code == 200
- result = response.json()
- assert result["tree"] is None
+ assert response.json() == {
+ "tree": None,
+ "context": {"kind": "package-manager", "name": "pip"},
+ }
mock_package_manager.dependency_tree.assert_called_once()
+def test_dependency_tree_uses_sandbox_context(
+ client: TestClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from marimo._environments.sandbox import PackageState
+ from marimo._runtime.packages.sandbox_package_manager import (
+ SandboxPackageManager,
+ )
+ from marimo._utils.uv_tree import DependencyTreeNode
+
+ tree = DependencyTreeNode(
+ name="<root>", version=None, tags=[], dependencies=[]
+ )
+ sandbox = MagicMock()
+ sandbox.backend = "pixi"
+ sandbox.environment = None
+ sandbox.packages.return_value = PackageState(packages=(), tree=tree)
+ manager = SandboxPackageManager(sandbox)
+ monkeypatch.setattr(
+ "marimo._server.api.endpoints.packages._get_package_manager",
+ lambda _request: manager,
+ )
+
+ response = client.get("/api/packages/tree", headers=HEADERS)
+
+ assert response.status_code == 200
+ assert response.json() == {
+ "tree": {
+ "name": "<root>",
+ "version": None,
+ "tags": [],
+ "dependencies": [],
+ },
+ "context": {"kind": "sandbox", "backend": "pixi"},
+ }
+
+
def test_dependency_tree_without_session(client: TestClient) -> None:
"""Test dependency tree without session."""
headers_no_session = token_header("fake-token")
@@ -503,7 +615,11 @@ def test_add_package_with_metadata_update(
)
assert response.status_code == 200
result = response.json()
- assert result == {"success": True, "error": None}
+ assert result == {
+ "success": True,
+ "error": None,
+ "restartRequired": False,
+ }
mock_package_manager_with_metadata.update_notebook_script_metadata.assert_called_once()
@@ -528,7 +644,11 @@ def test_add_package_with_spaced_extras_updates_metadata(
json={"package": package, "upgrade": True},
)
- assert response.json() == {"success": True, "error": None}
+ assert response.json() == {
+ "success": True,
+ "error": None,
+ "restartRequired": False,
+ }
mock_package_manager_with_metadata.install.assert_awaited_once_with(
package, version=None, upgrade=True, group=None
)
@@ -582,7 +702,11 @@ def test_remove_package_with_metadata_update(
)
assert response.status_code == 200
result = response.json()
- assert result == {"success": True, "error": None}
+ assert result == {
+ "success": True,
+ "error": None,
+ "restartRequired": False,
+ }
mock_package_manager_with_metadata.update_notebook_script_metadata.assert_called_once()
@@ -665,7 +789,11 @@ def test_add_package_with_git_dependency(
)
assert response.status_code == 200
result = response.json()
- assert result == {"success": True, "error": None}
+ assert result == {
+ "success": True,
+ "error": None,
+ "restartRequired": False,
+ }
# Verify metadata update was called with the git dependency
mock_package_manager_with_metadata.update_notebook_script_metadata.assert_called_once()
@@ -688,7 +816,11 @@ def test_add_package_with_dev_dependency(
json={"package": "test-package", "upgrade": True, "group": "dev"},
)
assert response.status_code == 200
- assert response.json() == {"success": True, "error": None}
+ assert response.json() == {
+ "success": True,
+ "error": None,
+ "restartRequired": False,
+ }
mock_package_manager.install.assert_called_once_with(
"test-package", version=None, upgrade=True, group="dev"
)
@@ -705,7 +837,11 @@ def test_remove_package_with_dev_dependency(
json={"package": "test-package", "group": "dev"},
)
assert response.status_code == 200
- assert response.json() == {"success": True, "error": None}
+ assert response.json() == {
+ "success": True,
+ "error": None,
+ "restartRequired": False,
+ }
mock_package_manager.uninstall.assert_called_once_with(
"test-package", group="dev"
)
@@ -723,6 +859,7 @@ def test_get_package_manager_uses_ipc_venv_python() -> None:
mock_session = MagicMock()
mock_session._kernel_manager = mock_kernel_manager
+ mock_session.notebook_sandbox = None
# Mock app state
mock_app_state = MagicMock()
@@ -757,7 +894,10 @@ def test_get_package_manager_uses_ipc_venv_python() -> None:
# Verify create_package_manager was called with python_exe
mock_create_pm.assert_called_once_with(
- "pip", python_exe="/custom/venv/python", script_path=None
+ "pip",
+ python_exe="/custom/venv/python",
+ script_path=None,
+ sandbox_environment=None,
)
@@ -772,6 +912,7 @@ def test_get_package_manager_with_script_environment() -> None:
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()
@@ -788,7 +929,7 @@ def test_get_package_manager_with_script_environment() -> None:
) as mock_create_pm,
patch(
"marimo._server.api.endpoints.packages.isinstance",
- side_effect=lambda _obj, _cls: True,
+ side_effect=lambda _obj, cls: cls.__name__ != "NotebookSandbox",
),
):
_get_package_manager(MagicMock())
@@ -797,6 +938,7 @@ def test_get_package_manager_with_script_environment() -> None:
"uv",
python_exe="/env/bin/python",
script_path="/nb/notebook.py",
+ sandbox_environment=mock_kernel_manager.script_environment,
)
@@ -830,7 +972,7 @@ def test_get_package_manager_without_ipc_session() -> None:
# Verify create_package_manager was called with python_exe=None
mock_create_pm.assert_called_once_with(
- "uv", python_exe=None, script_path=None
+ "uv", python_exe=None, script_path=None, sandbox_environment=None
)
@@ -870,6 +1012,7 @@ def test_package_manager_binding_for_inprocess_kernel(
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()
@@ -889,4 +1032,5 @@ def test_package_manager_binding_for_inprocess_kernel(
"uv",
python_exe=None,
script_path="/nb/notebook.py" if mode == "single" else None,
+ sandbox_environment=None,
)
diff --git a/tests/_server/test_sessions.py b/tests/_server/test_sessions.py
index 80b8744ed4..d58c568b0b 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
+from unittest.mock import MagicMock, patch
import pytest
@@ -58,6 +58,41 @@ 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",
diff --git a/tests/_session/app_host/test_app_host.py b/tests/_session/app_host/test_app_host.py
index a47594764e..cb49897076 100644
--- a/tests/_session/app_host/test_app_host.py
+++ b/tests/_session/app_host/test_app_host.py
@@ -161,6 +161,7 @@ class TestAppHostSandbox:
from unittest.mock import MagicMock, patch
from marimo._environments.environment import Environment
+ from marimo._environments.overlay import RuntimeOverlay
from marimo._session.app_host.pool import AppHostPool
pool = AppHostPool(sandbox=True)
@@ -173,12 +174,12 @@ class TestAppHostSandbox:
with (
patch(
- "marimo._session.app_host.pool.sync_notebook",
+ "marimo._environments.backends.sync_notebook",
return_value=handle,
) as mock_sync,
patch(
"marimo._session.app_host.pool.runtime_overlay",
- return_value=["kernel-dep==1.0"],
+ return_value=RuntimeOverlay(runtime="kernel-dep==1.0"),
),
patch(
"marimo._session.app_host.pool.AppHost",
@@ -211,7 +212,7 @@ class TestAppHostSandbox:
with (
patch(
- "marimo._session.app_host.pool.sync_notebook",
+ "marimo._environments.backends.sync_notebook",
) as mock_sync,
patch(
"marimo._session.app_host.pool.AppHost",
@@ -223,8 +224,10 @@ class TestAppHostSandbox:
mock_sync.assert_not_called()
assert mock_host_cls.call_args[1].get("plan") is None
- def test_pool_missing_metadata_runs_ephemerally(self) -> None:
- """A notebook without a metadata block launches isolated."""
+ def test_pool_missing_metadata_runs_from_this_interpreter(self) -> None:
+ """A notebook without a metadata block has nothing to sandbox;
+ it runs from the parent interpreter, which has marimo."""
+ import sys
from unittest.mock import MagicMock, patch
from marimo._environments.uv import UvMissingScriptMetadataError
@@ -237,14 +240,40 @@ class TestAppHostSandbox:
with (
patch(
- "marimo._session.app_host.pool.sync_notebook",
+ "marimo._environments.backends.sync_notebook",
side_effect=UvMissingScriptMetadataError(
["uv"], 2, "", "no PEP 723 metadata"
),
),
patch(
- "marimo._session.app_host.pool.runtime_overlay",
- return_value=["marimo==0.0.0"],
+ "marimo._session.app_host.pool.AppHost",
+ return_value=mock_host,
+ ) as mock_host_cls,
+ ):
+ pool.get_or_create("/tmp/test_app.py")
+
+ plan = mock_host_cls.call_args[1]["plan"]
+ assert plan.argv[0] == sys.executable
+
+ def test_pool_missing_pixi_metadata_runs_from_this_interpreter(
+ self,
+ ) -> None:
+ import sys
+ from unittest.mock import MagicMock, patch
+
+ from marimo._environments.pixi import PixiMissingScriptMetadataError
+ from marimo._session.app_host.pool import AppHostPool
+
+ pool = AppHostPool(sandbox=True)
+ mock_host = MagicMock()
+ mock_host.is_alive.return_value = True
+
+ with (
+ patch(
+ "marimo._environments.backends.sync_notebook",
+ side_effect=PixiMissingScriptMetadataError(
+ ["pixi"], 1, "no PEP 723 metadata block"
+ ),
),
patch(
"marimo._session.app_host.pool.AppHost",
@@ -253,9 +282,32 @@ class TestAppHostSandbox:
):
pool.get_or_create("/tmp/test_app.py")
- plan = mock_host_cls.call_args[1]["plan"]
- assert "--isolated" in plan.argv
- assert "marimo==0.0.0" in plan.argv
+ plan = mock_host_cls.call_args[1]["plan"]
+ assert plan.argv[0] == sys.executable
+
+ def test_pool_does_not_fall_back_after_other_pixi_failures(self) -> None:
+ from unittest.mock import patch
+
+ import pytest
+
+ from marimo._environments.pixi import PixiCommandError
+ from marimo._session.app_host.pool import AppHostPool
+ from marimo._session.managers.ipc import KernelStartupError
+
+ pool = AppHostPool(sandbox=True)
+ error = PixiCommandError(["pixi"], 1, "solver failed")
+
+ with (
+ patch(
+ "marimo._environments.backends.sync_notebook",
+ side_effect=error,
+ ),
+ patch("marimo._session.app_host.pool.AppHost") as mock_host_cls,
+ pytest.raises(KernelStartupError, match="solver failed"),
+ ):
+ pool.get_or_create("/tmp/test_app.py")
+
+ mock_host_cls.assert_not_called()
@pytest.mark.requires("zmq")
diff --git a/tests/_session/app_host/test_pool.py b/tests/_session/app_host/test_pool.py
index e5c02b8adc..b143f14e9b 100644
--- a/tests/_session/app_host/test_pool.py
+++ b/tests/_session/app_host/test_pool.py
@@ -138,17 +138,25 @@ def test_old_host_callback_does_not_remove_replacement() -> None:
pool.shutdown()
[email protected]("backend", ["uv", "pixi"])
def test_manifestless_host_clears_inherited_sandbox_identity(
monkeypatch: pytest.MonkeyPatch,
+ backend: str,
) -> None:
+ from marimo._environments.pixi import PixiMissingScriptMetadataError
from marimo._environments.uv import UvMissingScriptMetadataError
+ error = (
+ PixiMissingScriptMetadataError(["pixi"], 1, "missing")
+ if backend == "pixi"
+ else UvMissingScriptMetadataError(["uv"], 1, "", "missing")
+ )
monkeypatch.setenv("MARIMO_SANDBOX_MODE", "multi")
pool = AppHostPool(sandbox=True)
with (
patch(
- "marimo._session.app_host.pool.sync_notebook",
- side_effect=UvMissingScriptMetadataError(["uv"], 1, "", "missing"),
+ "marimo._environments.backends.sync_notebook",
+ side_effect=error,
),
patch(
"marimo._session.app_host.pool.runtime_overlay", return_value=[]
@@ -170,10 +178,10 @@ def test_environment_failure_is_reported_without_fallback() -> None:
pool = AppHostPool(sandbox=True)
with (
patch(
- "marimo._session.app_host.pool.sync_notebook",
+ "marimo._environments.backends.sync_notebook",
side_effect=UvError("solver diagnostic"),
),
- patch("marimo._session.app_host.pool.launch_isolated") as fallback,
+ patch("marimo._environments.backends.launch_fallback") as fallback,
):
with pytest.raises(KernelStartupError, match="solver diagnostic"):
pool.get_or_create("nb.py")
diff --git a/tests/_session/managers/test_ipc.py b/tests/_session/managers/test_ipc.py
index f3d733f0ca..4cc43cbd75 100644
--- a/tests/_session/managers/test_ipc.py
+++ b/tests/_session/managers/test_ipc.py
@@ -4,7 +4,7 @@ from __future__ import annotations
import os
import time
from pathlib import Path
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, patch
import pytest
@@ -303,6 +303,49 @@ 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
@@ -372,6 +415,24 @@ 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:
diff --git a/tests/_utils/test_uv_tree.py b/tests/_utils/test_uv_tree.py
index 69855ce468..42b0877994 100644
--- a/tests/_utils/test_uv_tree.py
+++ b/tests/_utils/test_uv_tree.py
@@ -9,8 +9,11 @@ import sys
import pytest
from marimo._messaging.msgspec_encoder import asdict
-from marimo._server.models.packages import DependencyTreeNode
-from marimo._utils.uv_tree import parse_uv_tree
+from marimo._utils.uv_tree import (
+ DependencyTag,
+ DependencyTreeNode,
+ parse_uv_tree,
+)
from tests.mocks import snapshotter
skip_if_below_py312 = pytest.mark.skipif(
@@ -52,6 +55,24 @@ def uv(cmd: list[str], cwd: str | None = None) -> str:
return result.stdout
+def test_uv_tree_distinguishes_deduplication_from_cycles() -> None:
+ repeated = parse_uv_tree(
+ "root v1.0.0\n"
+ "└── shared v2.0.0 (*)\n"
+ "(*) Package tree already displayed\n"
+ )
+ cycle = parse_uv_tree(
+ "root v1.0.0\n└── root v1.0.0 (*)\n(*) Package tree is a cycle\n"
+ )
+
+ assert repeated.dependencies[0].dependencies[0].tags == [
+ DependencyTag(kind="dedupe", value="true")
+ ]
+ assert cycle.dependencies[0].dependencies[0].tags == [
+ DependencyTag(kind="cycle", value="true")
+ ]
+
+
@pytest.mark.skipif(UV_BIN is None, reason="requires uv executable.")
@skip_if_windows
def test_complex_project_tree(tmp_path: pathlib.Path) -> None: