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.

feat: stream initial package installations for WASM (#9702)

Dylan Madisetti78f0366c8cb6
diff --git a/frontend/src/core/packages/__tests__/useInstallPackage.test.tsx b/frontend/src/core/packages/__tests__/useInstallPackage.test.tsx
new file mode 100644
index 0000000000..e04cdadd97
--- /dev/null
+++ b/frontend/src/core/packages/__tests__/useInstallPackage.test.tsx
@@ -0,0 +1,123 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useInstallPackages } from "../useInstallPackage";
+
+const toast = vi.fn();
+const addPackage = vi.fn();
+
+vi.mock("@/components/ui/use-toast", () => ({
+ toast: (...args: unknown[]) => toast(...args),
+}));
+
+vi.mock("../../network/requests", () => ({
+ useRequestClient: () => ({
+ addPackage: (...args: unknown[]) => addPackage(...args),
+ }),
+}));
+
+describe("useInstallPackages", () => {
+ beforeEach(() => {
+ toast.mockClear();
+ addPackage.mockClear();
+ });
+
+ it("batches all packages into a single install call", async () => {
+ addPackage.mockResolvedValue({ success: true, error: null });
+ const { result } = renderHook(() => useInstallPackages());
+
+ await act(async () => {
+ await result.current.handleInstallPackages(["numpy", "pandas", "scipy"]);
+ });
+
+ // A single batched install call, not one per package.
+ expect(addPackage).toHaveBeenCalledTimes(1);
+ expect(addPackage).toHaveBeenCalledWith({ package: "numpy pandas scipy" });
+ });
+
+ it("shows a single aggregate success toast for multiple packages", async () => {
+ addPackage.mockResolvedValue({ success: true, error: null });
+ const { result } = renderHook(() => useInstallPackages());
+
+ await act(async () => {
+ await result.current.handleInstallPackages(["numpy", "pandas", "scipy"]);
+ });
+
+ // Only one toast, regardless of package count — no false per-package status.
+ expect(toast).toHaveBeenCalledTimes(1);
+ expect(toast).toHaveBeenCalledWith(
+ expect.objectContaining({ title: "Packages added" }),
+ );
+ });
+
+ it("shows a single aggregate error toast when the batch fails", async () => {
+ addPackage.mockResolvedValue({ success: false, error: "boom" });
+ const { result } = renderHook(() => useInstallPackages());
+
+ await act(async () => {
+ await result.current.handleInstallPackages(["numpy", "pandas"]);
+ });
+
+ expect(toast).toHaveBeenCalledTimes(1);
+ expect(toast).toHaveBeenCalledWith(
+ expect.objectContaining({
+ title: "Failed to add packages",
+ description: "boom",
+ variant: "danger",
+ }),
+ );
+ });
+
+ it("collapses a partial (mixed) failure into one aggregate error toast", async () => {
+ // The backend resolves the batch as a single transaction and reports an
+ // aggregate outcome, so even when only some packages fail we surface a
+ // single error toast covering the whole batch — never a per-package
+ // success/failure split the response can't actually represent.
+ addPackage.mockResolvedValue({
+ success: false,
+ error: "pandas failed to install",
+ });
+ const { result } = renderHook(() => useInstallPackages());
+
+ await act(async () => {
+ await result.current.handleInstallPackages(["numpy", "pandas"]);
+ });
+
+ expect(addPackage).toHaveBeenCalledTimes(1);
+ expect(addPackage).toHaveBeenCalledWith({ package: "numpy pandas" });
+ expect(toast).toHaveBeenCalledTimes(1);
+ expect(toast).toHaveBeenCalledWith(
+ expect.objectContaining({
+ title: "Failed to add packages",
+ description: "pandas failed to install",
+ variant: "danger",
+ }),
+ );
+ });
+
+ it("uses singular wording for a single package", async () => {
+ addPackage.mockResolvedValue({ success: true, error: null });
+ const { result } = renderHook(() => useInstallPackages());
+
+ await act(async () => {
+ await result.current.handleInstallPackages(["numpy"]);
+ });
+
+ expect(toast).toHaveBeenCalledTimes(1);
+ expect(toast).toHaveBeenCalledWith(
+ expect.objectContaining({ title: "Package added" }),
+ );
+ });
+
+ it("calls onSuccess after a successful install", async () => {
+ addPackage.mockResolvedValue({ success: true, error: null });
+ const onSuccess = vi.fn();
+ const { result } = renderHook(() => useInstallPackages());
+
+ await act(async () => {
+ await result.current.handleInstallPackages(["numpy"], onSuccess);
+ });
+
+ expect(onSuccess).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/frontend/src/core/packages/toast-components.tsx b/frontend/src/core/packages/toast-components.tsx
index 52eb81498b..e8fef5e384 100644
--- a/frontend/src/core/packages/toast-components.tsx
+++ b/frontend/src/core/packages/toast-components.tsx
@@ -4,23 +4,34 @@ import { Kbd } from "@/components/ui/kbd";
import { toast } from "@/components/ui/use-toast";
export const showAddPackageToast = (
- packageName: string,
+ packageName: string | string[],
error?: string | null,
) => {
+ const packageNames = Array.isArray(packageName) ? packageName : [packageName];
if (error) {
toast({
- title: "Failed to add package",
+ title:
+ packageNames.length > 1
+ ? "Failed to add packages"
+ : "Failed to add package",
description: error,
variant: "danger",
});
} else {
toast({
- title: "Package added",
+ title: packageNames.length > 1 ? "Packages added" : "Package added",
description: (
<div>
<div>
- The package <Kbd className="inline">{packageName}</Kbd> and its
- dependencies has been added to your environment.
+ {packageNames.length > 1 ? "The packages " : "The package "}
+ {packageNames.map((name, index) => (
+ <span key={name}>
+ {index > 0 && ", "}
+ <Kbd className="inline">{name}</Kbd>
+ </span>
+ ))}{" "}
+ and {packageNames.length > 1 ? "their" : "its"} dependencies have
+ been added to your environment.
</div>
<div className="text-xs text-muted-foreground mt-1">
Some Python packages may require a kernel restart to see changes.
diff --git a/frontend/src/core/packages/useInstallPackage.ts b/frontend/src/core/packages/useInstallPackage.ts
index 3d4d0869e7..b641eb811a 100644
--- a/frontend/src/core/packages/useInstallPackage.ts
+++ b/frontend/src/core/packages/useInstallPackage.ts
@@ -22,17 +22,18 @@ export function useInstallPackages(): {
setLoading(true);
try {
- for (const [idx, packageName] of packages.entries()) {
- const response = await addPackage({ package: packageName });
- if (response.success) {
- showAddPackageToast(packageName);
- } else {
- showAddPackageToast(packageName, response.error);
- }
- // Wait 1s if there are more packages to install
- if (idx < packages.length - 1) {
- await new Promise((resolve) => setTimeout(resolve, 1000));
- }
+ // Batch all packages into a single install call.
+ // The worker splits by space and passes the full list to micropip,
+ // which resolves and downloads in parallel internally.
+ const response = await addPackage({ package: packages.join(" ") });
+ // The backend resolves the whole list as a single transaction, so the
+ // 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) {
+ showAddPackageToast(packages);
+ } else {
+ showAddPackageToast(packages, response.error);
}
onSuccess?.();
} catch (error) {
diff --git a/marimo/_runtime/callbacks/packages.py b/marimo/_runtime/callbacks/packages.py
index e12752f9b4..9831d3fa86 100644
--- a/marimo/_runtime/callbacks/packages.py
+++ b/marimo/_runtime/callbacks/packages.py
@@ -56,6 +56,37 @@ class PackagesCallbacks:
def register(self, router: RequestRouter) -> None:
router.register(InstallPackagesCommand, self._handle_install)
+ def _notebook_index_urls(self) -> list[str]:
+ """Read PEP 723 index config from the current notebook.
+
+ Returns a flat list with the primary `index-url` first, then any
+ `extra-index-url` entries, then `[[tool.uv.index]]` URLs.
+ Returns `[]` if there's no filename or no config — the receiving
+ backend will fall back to its default index.
+ """
+ filename = self._kernel.app_metadata.filename
+ if not filename:
+ return []
+ try:
+ from marimo._utils.inline_script_metadata import PyProjectReader
+
+ reader = PyProjectReader.from_filename(filename)
+ except Exception:
+ return []
+ urls: list[str] = []
+ if isinstance(reader.index_url, str) and reader.index_url:
+ urls.append(reader.index_url)
+ for extra in reader.extra_index_urls:
+ if isinstance(extra, str) and extra and extra not in urls:
+ urls.append(extra)
+ for entry in reader.index_configs:
+ if not isinstance(entry, dict):
+ continue
+ url = entry.get("url")
+ if isinstance(url, str) and url and url not in urls:
+ urls.append(url)
+ return urls
+
async def _handle_install(self, request: InstallPackagesCommand) -> None:
await self.install_missing_packages(request)
broadcast_notification(CompletedRunNotification())
@@ -173,7 +204,9 @@ class PackagesCallbacks:
version = {pkg: "" for pkg in packages}
self._kernel.enqueue_control_request(
InstallPackagesCommand(
- manager=self.package_manager.name, versions=version
+ manager=self.package_manager.name,
+ versions=version,
+ index_urls=self._notebook_index_urls(),
)
)
else:
@@ -249,34 +282,43 @@ class PackagesCallbacks:
return log_callback
+ # Mark every still-installable package as "installing" up-front so the
+ # UI can render the batch state before any wheel completes.
for pkg in missing_packages:
- if self.package_manager.attempted_to_install(package=pkg):
- # Already attempted an installation; it must have failed.
- # Skip the installation.
- continue
- package_statuses[pkg] = "installing"
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=package_statuses, source=request.source
- )
+ if not self.package_manager.attempted_to_install(package=pkg):
+ package_statuses[pkg] = "installing"
+ broadcast_notification(
+ InstallingPackageAlertNotification(
+ packages=package_statuses, source=request.source
)
-
- # Send initial "start" log
- broadcast_notification(
- InstallingPackageAlertNotification(
- packages=package_statuses,
- logs={pkg: f"Installing {pkg}...\n"},
- log_status="start",
- source=request.source,
+ )
+ for pkg in missing_packages:
+ if package_statuses.get(pkg) == "installing":
+ broadcast_notification(
+ InstallingPackageAlertNotification(
+ packages=package_statuses,
+ logs={pkg: f"Installing {pkg}...\n"},
+ log_status="start",
+ source=request.source,
+ )
)
- )
- version = request.versions.get(pkg)
- if await self.package_manager.install(
- pkg, version=version, log_callback=create_log_callback(pkg)
- ):
+ installable = [
+ pkg
+ for pkg in missing_packages
+ if not self.package_manager.attempted_to_install(package=pkg)
+ ]
+ versions: dict[str, str | None] = {
+ pkg: request.versions.get(pkg) for pkg in installable
+ }
+ async for pkg, success in self.package_manager.stream_install(
+ installable,
+ versions=versions,
+ index_urls=request.index_urls or None,
+ log_callback_factory=create_log_callback,
+ ):
+ if success:
package_statuses[pkg] = "installed"
- # Send final "done" log
broadcast_notification(
InstallingPackageAlertNotification(
packages=package_statuses,
@@ -289,7 +331,6 @@ class PackagesCallbacks:
package_statuses[pkg] = "failed"
mod = self.package_manager.package_to_module(pkg)
self._kernel.module_registry.excluded_modules.add(mod)
- # Send final "done" log with error
broadcast_notification(
InstallingPackageAlertNotification(
packages=package_statuses,
diff --git a/marimo/_runtime/commands.py b/marimo/_runtime/commands.py
index b21abd3f08..44d36705a0 100644
--- a/marimo/_runtime/commands.py
+++ b/marimo/_runtime/commands.py
@@ -630,13 +630,15 @@ class InstallPackagesCommand(Command):
manager: Package manager to use ('pip', 'conda', 'uv', etc.).
versions: Package names mapped to version specifiers. Empty version
means install latest.
+ index_urls: Alternative package index URLs. Primary index first,
+ then extras. Honored by backends that support custom
+ indexes (currently micropip); other backends ignore it.
source: Where to install. "kernel" (default) dispatches to the kernel
subprocess; "server" installs directly into the server's Python
environment (sys.executable), used when the server itself needs
a package (e.g. nbformat for IPYNB auto-export in sandbox mode).
"""
- # TODO: index URL (index/channel/...)
manager: str
# Map from package name to desired version
@@ -644,6 +646,9 @@ class InstallPackagesCommand(Command):
# will be installed
versions: dict[str, str]
+ # Alternative package index URLs (primary + extras, primary first).
+ index_urls: list[str] = msgspec.field(default_factory=list)
+
source: Literal["kernel", "server"] = "kernel"
diff --git a/marimo/_runtime/packages/_micropip_streaming.py b/marimo/_runtime/packages/_micropip_streaming.py
new file mode 100644
index 0000000000..f9a42ac89e
--- /dev/null
+++ b/marimo/_runtime/packages/_micropip_streaming.py
@@ -0,0 +1,196 @@
+# Copyright 2026 Marimo. All rights reserved.
+# This module is intentionally marimo-free so it can be contributed
+# back to pyodide/micropip as a streaming install primitive.
+# Do NOT import from marimo.* here.
+from __future__ import annotations
+
+import asyncio
+import importlib
+import importlib.metadata
+from pathlib import Path
+from site import getsitepackages
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+ from collections.abc import AsyncIterator
+
+
+def _append_version(pkg_name: str, version: str | None) -> str:
+ """Qualify a version string with a leading '==' if it doesn't have one."""
+ if version is None or version in ("", "latest"):
+ return pkg_name
+ return f"{pkg_name}=={version}"
+
+
+def _split_packages(package: str) -> list[str]:
+ """Split a whitespace-joined package spec into individual requirements.
+
+ Each individual requirement follows PEP 508 dependency-specification
+ grammar (https://peps.python.org/pep-0508/) — version specifiers, direct
+ URL references (`pkg @ url`), and environment markers
+ (`pkg==1.0; python_version>'3.6'`). The whitespace-joined list and the
+ `-e`/`--editable` prefix mirror pip's requirement-specifier syntax
+ (https://pip.pypa.io/en/stable/reference/requirement-specifiers/).
+ """
+ packages: list[str] = []
+ current: list[str] = []
+ in_marker = False
+
+ for part in package.split():
+ if (
+ part in ("-e", "--editable", "@")
+ or current
+ and current[-1] in ("-e", "--editable", "@")
+ ):
+ current.append(part)
+ elif part.endswith(";"):
+ if current:
+ packages.append(" ".join(current))
+ current = []
+ in_marker = True
+ current.append(part)
+ elif in_marker:
+ current.append(part)
+ if part.endswith(("'", '"')):
+ in_marker = False
+ packages.append(" ".join(current))
+ current = []
+ else:
+ if current:
+ packages.append(" ".join(current))
+ current = [part]
+
+ if current:
+ packages.append(" ".join(current))
+
+ return [pkg.strip() for pkg in packages]
+
+
+async def stream_transaction_install(
+ packages: list[str],
+ *,
+ versions: dict[str, str | None] | None = None,
+ index_urls: list[str] | None = None,
+ constraints: list[str] | None = None,
+) -> AsyncIterator[tuple[str, bool]]:
+ """Install via micropip's Transaction API, yielding (name, success) per wheel.
+
+ Mirrors what `micropip.install()` does internally, but exposes the resolved
+ wheel list so callers can stream progress as each wheel finishes installing
+ (via `asyncio.as_completed`) instead of waiting for an opaque end-to-end call.
+
+ `index_urls` and `constraints`, when None, fall back to the values on
+ `micropip._micropip` (the global singleton); when provided, they override
+ the singleton for this transaction only.
+
+ Yields `(package_name, success)` per requested package. Packages that
+ resolve to native pyodide-distribution entries are loaded via
+ `loadPackage`; pure-python wheels are downloaded and extracted in parallel.
+ """
+ # Lazy / dynamic import so this module loads cleanly outside Pyodide
+ # (where micropip isn't installed). A ModuleNotFoundError here propagates
+ # as ImportError, which the marimo-side wrapper catches and falls back.
+ micropip = importlib.import_module("micropip")
+ default_environment = importlib.import_module(
+ "micropip._utils"
+ ).default_environment
+ Transaction = importlib.import_module("micropip.transaction").Transaction
+ from packaging.requirements import Requirement
+ from packaging.utils import canonicalize_name
+
+ mgr = micropip._micropip # singleton PackageManager
+ ctx = default_environment()
+ wheel_base = Path(getsitepackages()[0])
+
+ flat_requirements: list[str] = []
+ for pkg in packages:
+ version = (versions or {}).get(pkg)
+ versioned = _append_version(pkg, version)
+ flat_requirements.extend(_split_packages(versioned))
+
+ transaction = Transaction(
+ _compat_layer=mgr.compat_layer,
+ ctx=ctx,
+ ctx_extras=[],
+ keep_going=True,
+ deps=True,
+ pre=False,
+ fetch_kwargs={},
+ verbose=False,
+ index_urls=index_urls if index_urls is not None else mgr.index_urls,
+ constraints=constraints
+ if constraints is not None
+ else mgr.constraints,
+ reinstall=False,
+ )
+
+ await transaction.gather_requirements(flat_requirements)
+
+ # Map normalized base-package-name -> (original spec, base name). The
+ # caller's strings may include version specifiers, URL specs, or markers
+ # (`foo==1.0`, `foo @ git+…@ref`, `foo; python_version>'3.10'`), so parse
+ # out the base name before canonicalizing — otherwise the wheel name
+ # micropip yields back ("foo") will fail to match the spec string. We keep
+ # both: `original` is what we report back to the caller (their spelling),
+ # `base_name` is the bare distribution name for `importlib.metadata`.
+ requested: dict[str, tuple[str, str]] = {}
+ for spec in packages:
+ try:
+ base_name = Requirement(spec).name
+ except Exception:
+ # Editable/path specs and other oddities Requirement can't parse;
+ # fall back to canonicalizing the whole string. Worst case it
+ # gets reconciled by the importlib.metadata pass at the end.
+ base_name = spec
+ requested[canonicalize_name(base_name)] = (spec, base_name)
+
+ for failed_name in transaction.failed:
+ normalized = canonicalize_name(failed_name)
+ original, _ = requested.pop(normalized, (failed_name, failed_name))
+ yield (original, False)
+
+ async def _install_wheel(wheel: Any) -> tuple[str, Exception | None]:
+ try:
+ await wheel.install(wheel_base, mgr.compat_layer)
+ except Exception as exc:
+ return wheel.name, exc
+ return wheel.name, None
+
+ if transaction.wheels:
+ tasks = [
+ asyncio.create_task(_install_wheel(w)) for w in transaction.wheels
+ ]
+ for future in asyncio.as_completed(tasks):
+ name, exc = await future
+ normalized = canonicalize_name(name)
+ if normalized in requested:
+ original, _ = requested.pop(normalized)
+ yield (original, exc is None)
+
+ if transaction.pyodide_packages:
+ names = [name for name, _, _ in transaction.pyodide_packages]
+ try:
+ await mgr.compat_layer.loadPackage(mgr.compat_layer.to_js(names))
+ except Exception:
+ load_succeeded = False
+ else:
+ load_succeeded = True
+ for name in names:
+ normalized = canonicalize_name(name)
+ if normalized in requested:
+ original, _ = requested.pop(normalized)
+ yield (original, load_succeeded)
+
+ importlib.invalidate_caches()
+
+ # Anything still in `requested` may have been pulled in transitively under
+ # a different name (e.g. caller asked for `foo`, micropip installed `foo-impl`).
+ # If it's importable now, treat it as installed. Look up the bare base name,
+ # not the caller's spec — `importlib.metadata.version` expects a
+ # distribution name and would raise on `foo==1.0`, `foo @ git+…`, or markers.
+ for _normalized, (original, base_name) in list(requested.items()):
+ try:
+ importlib.metadata.version(base_name)
+ yield (original, True)
+ except importlib.metadata.PackageNotFoundError:
+ yield (original, False)
diff --git a/marimo/_runtime/packages/package_manager.py b/marimo/_runtime/packages/package_manager.py
index 6bf176f7f0..26e537c92f 100644
--- a/marimo/_runtime/packages/package_manager.py
+++ b/marimo/_runtime/packages/package_manager.py
@@ -4,7 +4,7 @@ from __future__ import annotations
import abc
import re
import sys
-from collections.abc import Callable
+from collections.abc import AsyncIterator, Callable
from typing import TYPE_CHECKING
import msgspec
@@ -128,6 +128,37 @@ class PackageManager(abc.ABC):
log_callback=log_callback,
)
+ async def stream_install(
+ self,
+ 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]]:
+ """Install packages and yield (name, success) as each completes.
+
+ The default implementation installs sequentially. Subclasses (e.g.
+ `MicropipPackageManager`) may override to batch installs and stream
+ real progress. `index_urls` is honored by backends that support it
+ (currently only micropip); other backends ignore it.
+ """
+ # `index_urls` honored by overriding subclasses (micropip);
+ # the sequential default ignores it.
+ del index_urls
+ for pkg in packages:
+ if self.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 self.install(
+ pkg,
+ version=version,
+ log_callback=cb,
+ )
+ yield (pkg, success)
+
@abc.abstractmethod
async def uninstall(self, package: str, group: str | None = None) -> bool:
"""Attempt to uninstall a package
diff --git a/marimo/_runtime/packages/pypi_package_manager.py b/marimo/_runtime/packages/pypi_package_manager.py
index 82fd5f6736..233b222df3 100644
--- a/marimo/_runtime/packages/pypi_package_manager.py
+++ b/marimo/_runtime/packages/pypi_package_manager.py
@@ -8,9 +8,16 @@ import sys
import tempfile
from functools import cached_property
from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ from collections.abc import AsyncIterator, Callable
from marimo import _loggers
from marimo._dependencies.dependencies import DependencyManager
+from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+)
from marimo._runtime.packages.module_name_to_pypi_name import (
module_name_to_pypi_name,
)
@@ -245,6 +252,63 @@ class MicropipPackageManager(PypiPackageManager):
log_callback(f"Failed to install {package}: {e}\n")
return False
+ async def stream_install(
+ self,
+ 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]]:
+ """Batch-install via micropip Transaction internals, streaming progress.
+
+ Wraps `stream_transaction_install` with marimo bookkeeping
+ (`_attempted_packages`) and log-callback glue. Falls back to the
+ base sequential path if micropip's internal API has shifted.
+ """
+ assert is_pyodide()
+
+ if log_callback_factory:
+ for pkg in packages:
+ log_callback_factory(pkg)(f"Resolving {pkg}...\n")
+
+ yielded: set[str] = set()
+ try:
+ async for pkg, success in stream_transaction_install(
+ packages,
+ versions=versions,
+ index_urls=index_urls,
+ ):
+ # Mark only as the engine resolves each package — if the
+ # engine raises before any yields, the fallback path needs
+ # to start clean (it will mark via `install()`).
+ self._attempted_packages.add(pkg)
+ yielded.add(pkg)
+ if log_callback_factory:
+ msg = (
+ f"Successfully installed {pkg}\n"
+ if success
+ else f"Failed to install {pkg}\n"
+ )
+ log_callback_factory(pkg)(msg)
+ yield (pkg, success)
+ except (AttributeError, ImportError, TypeError):
+ # micropip's private Transaction API shifted; fall back to the
+ # base sequential path. Narrow catch: install errors should
+ # surface, only API-shape mismatches trigger the fallback.
+ LOGGER.warning(
+ "micropip Transaction API unavailable, falling back to sequential installs",
+ exc_info=True,
+ )
+ remaining = [p for p in packages if p not in yielded]
+ async for result in super().stream_install(
+ remaining,
+ versions=versions,
+ index_urls=index_urls,
+ log_callback_factory=log_callback_factory,
+ ):
+ yield result
+
async def uninstall(self, package: str, group: str | None = None) -> bool:
# The `group` parameter is accepted for interface compatibility, but is ignored.
del group
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index 67f6bee801..a587bacbaa 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -2609,12 +2609,20 @@ components:
\ or manually by the user.\n\n Attributes:\n manager: Package manager\
\ to use ('pip', 'conda', 'uv', etc.).\n versions: Package names mapped\
\ to version specifiers. Empty version\n means install latest.\n\
+ \ index_urls: Alternative package index URLs. Primary index first,\n\
+ \ then extras. Honored by backends that support custom\n\
+ \ indexes (currently micropip); other backends ignore it.\n\
\ source: Where to install. \"kernel\" (default) dispatches to the\
\ kernel\n subprocess; \"server\" installs directly into the\
\ server's Python\n environment (sys.executable), used when\
\ the server itself needs\n a package (e.g. nbformat for IPYNB\
\ auto-export in sandbox mode)."
properties:
+ indexUrls:
+ default: []
+ items:
+ type: string
+ type: array
manager:
type: string
source:
@@ -2637,6 +2645,11 @@ components:
type: object
InstallPackagesRequest:
properties:
+ indexUrls:
+ default: []
+ items:
+ type: string
+ type: array
manager:
type: string
source:
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index 76959e90e4..490d05bf0a 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -5245,12 +5245,17 @@ export interface components {
* manager: Package manager to use ('pip', 'conda', 'uv', etc.).
* versions: Package names mapped to version specifiers. Empty version
* means install latest.
+ * index_urls: Alternative package index URLs. Primary index first,
+ * then extras. Honored by backends that support custom
+ * indexes (currently micropip); other backends ignore it.
* source: Where to install. "kernel" (default) dispatches to the kernel
* subprocess; "server" installs directly into the server's Python
* environment (sys.executable), used when the server itself needs
* a package (e.g. nbformat for IPYNB auto-export in sandbox mode).
*/
InstallPackagesCommand: {
+ /** @default [] */
+ indexUrls?: string[];
manager: string;
/**
* @default kernel
@@ -5265,6 +5270,8 @@ export interface components {
};
/** InstallPackagesRequest */
InstallPackagesRequest: {
+ /** @default [] */
+ indexUrls?: string[];
manager: string;
/**
* @default kernel
diff --git a/tests/_runtime/packages/test_micropip_streaming.py b/tests/_runtime/packages/test_micropip_streaming.py
new file mode 100644
index 0000000000..aa301d4cea
--- /dev/null
+++ b/tests/_runtime/packages/test_micropip_streaming.py
@@ -0,0 +1,469 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Unit tests for the marimo-free `stream_transaction_install` engine.
+
+micropip itself only runs inside Pyodide, so we monkeypatch
+`micropip._micropip` + `micropip.transaction.Transaction` with stubs that
+simulate the resolution / install steps deterministically.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import types
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+ import pytest
+
+
+@dataclass
+class _FakeWheel:
+ name: str
+ install_error: Exception | None = None
+ install_event: asyncio.Event | None = None
+
+ async def install(self, _wheel_base: Any, _compat: Any) -> None:
+ if self.install_event is not None:
+ await self.install_event.wait()
+ if self.install_error is not None:
+ raise self.install_error
+
+
+@dataclass
+class _FakeTransaction:
+ wheels: list[_FakeWheel] = field(default_factory=list)
+ failed: list[str] = field(default_factory=list)
+ pyodide_packages: list[tuple[str, str, str]] = field(default_factory=list)
+ seen_requirements: list[str] = field(default_factory=list)
+ init_kwargs: dict[str, Any] = field(default_factory=dict)
+
+ async def gather_requirements(self, requirements: list[str]) -> None:
+ self.seen_requirements.extend(requirements)
+
+
+class _FakeCompatLayer:
+ def __init__(self) -> None:
+ self.loaded: list[list[str]] = []
+
+ def to_js(self, value: Any) -> Any:
+ return value
+
+ async def loadPackage(self, names: list[str]) -> None:
+ self.loaded.append(list(names))
+
+
+@dataclass
+class _FakeMicropipManager:
+ compat_layer: _FakeCompatLayer = field(default_factory=_FakeCompatLayer)
+ index_urls: list[str] = field(default_factory=lambda: ["https://default/"])
+ constraints: list[str] = field(default_factory=list)
+
+
+def _install_fake_micropip(
+ monkeypatch: Any, fake_tx: _FakeTransaction
+) -> _FakeMicropipManager:
+ """Install fake `micropip`, `micropip._utils`, `micropip.transaction`, and
+ `packaging.utils` modules into sys.modules so the engine resolves to them.
+ """
+ fake_mgr = _FakeMicropipManager()
+
+ micropip_mod = types.ModuleType("micropip")
+ micropip_mod._micropip = fake_mgr # type: ignore[attr-defined]
+
+ utils_mod = types.ModuleType("micropip._utils")
+ utils_mod.default_environment = dict # type: ignore[attr-defined]
+
+ txn_mod = types.ModuleType("micropip.transaction")
+
+ def _Transaction(**kwargs: Any) -> _FakeTransaction:
+ fake_tx.init_kwargs = kwargs
+ return fake_tx
+
+ txn_mod.Transaction = _Transaction # type: ignore[attr-defined]
+
+ monkeypatch.setitem(sys.modules, "micropip", micropip_mod)
+ monkeypatch.setitem(sys.modules, "micropip._utils", utils_mod)
+ monkeypatch.setitem(sys.modules, "micropip.transaction", txn_mod)
+ return fake_mgr
+
+
+async def _drain(agen: Any) -> list[tuple[str, bool]]:
+ out: list[tuple[str, bool]] = []
+ async for item in agen:
+ out.append(item)
+ return out
+
+
+async def test_two_wheels_both_succeed(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ tx = _FakeTransaction(wheels=[_FakeWheel("foo"), _FakeWheel("bar")])
+ _install_fake_micropip(monkeypatch, tx)
+
+ results = await _drain(stream_transaction_install(["foo", "bar"]))
+ assert sorted(results) == [("bar", True), ("foo", True)]
+
+
+async def test_wheel_install_failure_no_double_yield(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ tx = _FakeTransaction(
+ wheels=[
+ _FakeWheel("foo", install_error=RuntimeError("boom")),
+ _FakeWheel("bar"),
+ ]
+ )
+ _install_fake_micropip(monkeypatch, tx)
+
+ results = await _drain(stream_transaction_install(["foo", "bar"]))
+ assert sorted(results) == [("bar", True), ("foo", False)]
+ # Each requested package yields exactly once.
+ assert [name for name, _ in results].count("foo") == 1
+
+
+async def test_resolution_failure_yields_false(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ tx = _FakeTransaction(failed=["foo"])
+ _install_fake_micropip(monkeypatch, tx)
+
+ results = await _drain(stream_transaction_install(["foo"]))
+ assert results == [("foo", False)]
+
+
+async def test_pyodide_package_only_loadpackage_once(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ tx = _FakeTransaction(
+ pyodide_packages=[("numpy", "1.26.0", "default")],
+ )
+ fake_mgr = _install_fake_micropip(monkeypatch, tx)
+
+ results = await _drain(stream_transaction_install(["numpy"]))
+ assert results == [("numpy", True)]
+ assert fake_mgr.compat_layer.loaded == [["numpy"]]
+
+
+async def test_index_urls_override_passed_to_transaction(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ tx = _FakeTransaction(wheels=[_FakeWheel("foo")])
+ fake_mgr = _install_fake_micropip(monkeypatch, tx)
+
+ override = ["https://my.private/simple", "https://extra/simple"]
+ await _drain(stream_transaction_install(["foo"], index_urls=override))
+ assert tx.init_kwargs["index_urls"] == override
+ # And the singleton's was NOT used.
+ assert tx.init_kwargs["index_urls"] is not fake_mgr.index_urls
+
+
+async def test_index_urls_none_falls_back_to_singleton(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ tx = _FakeTransaction(wheels=[_FakeWheel("foo")])
+ fake_mgr = _install_fake_micropip(monkeypatch, tx)
+
+ await _drain(stream_transaction_install(["foo"], index_urls=None))
+ assert tx.init_kwargs["index_urls"] is fake_mgr.index_urls
+
+
+async def test_url_spec_passthrough(monkeypatch: pytest.MonkeyPatch) -> None:
+ """PEP 508 URL specs in the packages list must reach gather_requirements
+ unaltered — the engine shouldn't try to be clever about them."""
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ tx = _FakeTransaction(wheels=[_FakeWheel("foo")])
+ _install_fake_micropip(monkeypatch, tx)
+
+ spec = "foo @ git+https://example.com/repo@deadbeef"
+ await _drain(stream_transaction_install([spec]))
+ assert spec in tx.seen_requirements
+
+
+async def test_versions_appended(monkeypatch: pytest.MonkeyPatch) -> None:
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ tx = _FakeTransaction(wheels=[_FakeWheel("foo")])
+ _install_fake_micropip(monkeypatch, tx)
+
+ await _drain(
+ stream_transaction_install(["foo"], versions={"foo": "1.2.3"})
+ )
+ assert "foo==1.2.3" in tx.seen_requirements
+
+
+async def test_streaming_order_first_done_first_yielded(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """The engine should yield as each wheel completes, not in submission order."""
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ fast_done = asyncio.Event()
+ slow_done = asyncio.Event()
+ tx = _FakeTransaction(
+ wheels=[
+ _FakeWheel("slow", install_event=slow_done),
+ _FakeWheel("fast", install_event=fast_done),
+ ]
+ )
+ _install_fake_micropip(monkeypatch, tx)
+
+ async def driver() -> list[tuple[str, bool]]:
+ results: list[tuple[str, bool]] = []
+ agen = stream_transaction_install(["slow", "fast"])
+ # Let `fast` finish first.
+ fast_done.set()
+ async for item in agen:
+ results.append(item)
+ if item[0] == "fast":
+ # Now release `slow` so the generator can complete.
+ slow_done.set()
+ return results
+
+ results = await driver()
+ assert results[0] == ("fast", True)
+ assert results[1] == ("slow", True)
+
+
+async def test_versioned_spec_tracked_correctly(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A versioned spec ("foo==1.0") must be tracked by its base name so the
+ wheel install ("foo") is recognized as fulfilling the request."""
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ tx = _FakeTransaction(wheels=[_FakeWheel("foo")])
+ _install_fake_micropip(monkeypatch, tx)
+
+ results = await _drain(stream_transaction_install(["foo==1.0"]))
+ # Yields the original spec string, not the bare name.
+ assert results == [("foo==1.0", True)]
+
+
+async def test_url_spec_tracked_correctly(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A PEP 508 URL spec ("foo @ git+…") must be tracked by base name too."""
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ tx = _FakeTransaction(wheels=[_FakeWheel("foo")])
+ _install_fake_micropip(monkeypatch, tx)
+
+ spec = "foo @ git+https://example.com/repo@deadbeef"
+ results = await _drain(stream_transaction_install([spec]))
+ assert results == [(spec, True)]
+
+
+async def test_reconciliation_uses_base_name_for_metadata_lookup(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A versioned spec that resolves transitively (no wheel/failed/pyodide
+ entry of its own) is reconciled via `importlib.metadata`. The lookup must
+ use the bare distribution name — `importlib.metadata.version("foo==1.0")`
+ would always raise `PackageNotFoundError` and falsely report a failure."""
+ import importlib.metadata as importlib_metadata
+
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ # Empty transaction: nothing failed, no wheels, no pyodide packages, so the
+ # spec falls through to the final importlib.metadata reconciliation pass.
+ tx = _FakeTransaction()
+ _install_fake_micropip(monkeypatch, tx)
+
+ seen: list[str] = []
+
+ def fake_version(name: str) -> str:
+ seen.append(name)
+ return "1.0"
+
+ monkeypatch.setattr(importlib_metadata, "version", fake_version)
+
+ results = await _drain(stream_transaction_install(["foo==1.0"]))
+ # Reported back with the caller's original spelling, marked installed.
+ assert results == [("foo==1.0", True)]
+ # But looked up by the bare distribution name.
+ assert seen == ["foo"]
+
+
+async def _make_micropip_manager(monkeypatch: Any) -> Any:
+ """Build a `MicropipPackageManager` outside Pyodide by stubbing the
+ `is_pyodide()` guard that both the constructor path and `stream_install`
+ assert on."""
+ import marimo._runtime.packages.pypi_package_manager as ppm
+
+ monkeypatch.setattr(ppm, "is_pyodide", lambda: True)
+ return ppm.MicropipPackageManager()
+
+
+async def test_manager_stream_install_happy_path(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """The manager wraps the engine, marks attempted packages, and yields
+ each package exactly once."""
+ import marimo._runtime.packages.pypi_package_manager as ppm
+
+ manager = await _make_micropip_manager(monkeypatch)
+
+ async def fake_engine(packages: list[str], **_kwargs: Any) -> Any:
+ for pkg in packages:
+ yield (pkg, True)
+
+ monkeypatch.setattr(ppm, "stream_transaction_install", fake_engine)
+
+ results = await _drain(manager.stream_install(["foo", "bar"]))
+ assert results == [("foo", True), ("bar", True)]
+ assert manager._attempted_packages == {"foo", "bar"}
+ # Each package yielded exactly once.
+ names = [name for name, _ in results]
+ assert sorted(names) == ["bar", "foo"]
+
+
+async def test_manager_stream_install_fallback_no_reinstall(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """If the engine raises after yielding some packages, the manager falls
+ back to the sequential base path for the *remaining* packages only —
+ already-yielded packages are not re-installed, and every package is
+ yielded exactly once."""
+ import marimo._runtime.packages.pypi_package_manager as ppm
+
+ manager = await _make_micropip_manager(monkeypatch)
+
+ async def flaky_engine(packages: list[str], **_kwargs: Any) -> Any:
+ del packages
+ # First package resolves, then the private API "shifts".
+ yield ("foo", True)
+ raise AttributeError("Transaction internals moved")
+
+ monkeypatch.setattr(ppm, "stream_transaction_install", flaky_engine)
+
+ # Record which packages the fallback actually tries to install.
+ installed: list[str] = []
+
+ async def fake_install(package: str, *_args: Any, **_kwargs: Any) -> bool:
+ installed.append(package)
+ return True
+
+ monkeypatch.setattr(manager, "_install", fake_install)
+
+ results = await _drain(manager.stream_install(["foo", "bar", "baz"]))
+
+ # `foo` came from the engine; `bar`/`baz` from the fallback.
+ assert results == [("foo", True), ("bar", True), ("baz", True)]
+
+ # The already-yielded `foo` was NOT re-installed by the fallback.
+ assert installed == ["bar", "baz"]
+
+ # Each requested package is yielded exactly once.
+ names = [name for name, _ in results]
+ assert sorted(names) == ["bar", "baz", "foo"]
+ assert len(names) == len(set(names))
+
+
+async def test_manager_stream_install_fallback_before_any_yield(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """If the engine raises before yielding anything, the fallback installs
+ the full list."""
+ import marimo._runtime.packages.pypi_package_manager as ppm
+
+ manager = await _make_micropip_manager(monkeypatch)
+
+ async def dead_engine(packages: list[str], **_kwargs: Any) -> Any:
+ del packages
+ raise ImportError("micropip.transaction unavailable")
+ yield # pragma: no cover - makes this an async generator
+
+ monkeypatch.setattr(ppm, "stream_transaction_install", dead_engine)
+
+ installed: list[str] = []
+
+ async def fake_install(package: str, *_args: Any, **_kwargs: Any) -> bool:
+ installed.append(package)
+ return True
+
+ monkeypatch.setattr(manager, "_install", fake_install)
+
+ results = await _drain(manager.stream_install(["foo", "bar"]))
+ assert results == [("foo", True), ("bar", True)]
+ assert installed == ["foo", "bar"]
+
+
+async def test_loadpackage_failure_yields_false_no_terminate(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A loadPackage exception must yield (name, False) per pyodide package
+ rather than crashing the generator mid-stream."""
+ from marimo._runtime.packages._micropip_streaming import (
+ stream_transaction_install,
+ )
+
+ class _BadCompatLayer(_FakeCompatLayer):
+ async def loadPackage(self, names: list[str]) -> None:
+ del names
+ raise RuntimeError("pyodide load failed")
+
+ fake_mgr = _FakeMicropipManager(compat_layer=_BadCompatLayer())
+ tx = _FakeTransaction(
+ wheels=[_FakeWheel("foo")],
+ pyodide_packages=[("numpy", "1.26.0", "default")],
+ )
+
+ micropip_mod = types.ModuleType("micropip")
+ micropip_mod._micropip = fake_mgr # type: ignore[attr-defined]
+ utils_mod = types.ModuleType("micropip._utils")
+ utils_mod.default_environment = dict # type: ignore[attr-defined]
+ txn_mod = types.ModuleType("micropip.transaction")
+
+ def _Transaction(**kwargs: Any) -> _FakeTransaction:
+ tx.init_kwargs = kwargs
+ return tx
+
+ txn_mod.Transaction = _Transaction # type: ignore[attr-defined]
+ monkeypatch.setitem(sys.modules, "micropip", micropip_mod)
+ monkeypatch.setitem(sys.modules, "micropip._utils", utils_mod)
+ monkeypatch.setitem(sys.modules, "micropip.transaction", txn_mod)
+
+ results = await _drain(stream_transaction_install(["foo", "numpy"]))
+ # Generator completed (no crash); numpy yielded False from the failure.
+ assert ("numpy", False) in results
+ # foo wheel still succeeded independently.
+ assert ("foo", True) in results
diff --git a/tests/_runtime/test_manage_script_metadata.py b/tests/_runtime/test_manage_script_metadata.py
index 3eebba93cf..d487ebc392 100644
--- a/tests/_runtime/test_manage_script_metadata.py
+++ b/tests/_runtime/test_manage_script_metadata.py
@@ -18,6 +18,7 @@ from marimo._runtime.commands import (
CommandMessage,
InstallPackagesCommand,
)
+from marimo._runtime.packages.package_manager import LogCallback
from marimo._runtime.packages.package_managers import create_package_manager
from marimo._runtime.packages.pypi_package_manager import (
MicropipPackageManager,
@@ -29,10 +30,40 @@ 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",
@@ -527,6 +558,9 @@ 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
+ )
# Set up packages callbacks
k.packages_callbacks.package_manager = mock_package_manager
@@ -603,6 +637,9 @@ 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
+ )
k.packages_callbacks.package_manager = mock_package_manager
with (
@@ -667,6 +704,9 @@ 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
+ )
k.packages_callbacks.package_manager = mock_package_manager
with (
@@ -742,6 +782,9 @@ 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
+ )
k.packages_callbacks.package_manager = mock_package_manager
with (