--- name: env-management description: Use when a notebook run fails on a missing package (ImportError, ModuleNotFoundError, "there is no package called"), when you need to inspect an installed package version, or when you need to install, add, or manage Python or R packages for the notebook runtime. Covers inspect_packages, routing Python vs R through manage_packages, why in-cell %pip/!pip/install.packages() and OS installers are forbidden, restarting the kernel after an install, and when to stop and ask the user. license: Apache-2.0 --- # Environment and package management The notebook runs against the session's **bound runtime**: the app-managed default (`default-python` / `default-r`) unless you bind another one with `notebook_bind_runtime` — a named environment you created, or one of the user's own detected interpreters. You never activate environments by hand, and you never install packages from inside a cell. Installs happen in the trusted main process through a single tool, `manage_packages`, and always land in the currently bound runtime. This page is the workflow for getting a package installed and for knowing when a package is not something you can install yourself. ## When a package is missing A run that fails with `ImportError` / `ModuleNotFoundError` (Python) or `Error in library(x): there is no package called 'x'` (R) means the package is not in the environment yet. The fix is one `manage_packages` call, not a code change. Do not rewrite the cell to use a different library that "does roughly the same thing" — install the package the task actually needs. Do not fall back to reading data or computing results a worse way to dodge the missing import. ## Check an installed version Use `inspect_packages(language, packages)` when the user asks whether a package is installed in an app-managed runtime or which version is present, or when your code depends on a version-specific feature. It reads package metadata from the session's bound app-managed runtime without importing the package or changing the environment. An `installed` result does not prove the import will succeed; use `notebook_execute` when importability itself is the question. Inspection does not provision a missing app-managed default runtime. If it reports `DEFAULT_RUNTIME_NOT_READY`, use `notebook_execute` in that language to prepare the runtime under notebook execution approval, then retry `inspect_packages`. `inspect_packages` intentionally rejects a user-owned external runtime because reading its metadata executes that interpreter. Use `notebook_execute` for an external runtime so the user sees the normal notebook execution approval. Do not use inspection as a mandatory preflight for every install. For a clear missing-package error, call `manage_packages` directly; installation is the recovery action, while inspection is for explicit version and compatibility questions. ## Route by language - Python package → `manage_packages(language="python", packages=["numpy", "pandas"])`. - R package → `manage_packages(language="r", packages=["ggplot2"])`. R packages install from conda-forge as `r-` automatically; pass the plain CRAN name (`ggplot2`, not `r-ggplot2`). - A PyPI-only Python package that is not on conda → add `usePip=true`. - A package that needs a specific conda channel → pass `channels=["bioconda"]`. Leave `channels` off otherwise; the app supplies the right default mirror. `manage_packages` always returns a target receipt. When resolution succeeds, it identifies the implicit default or explicit binding and the actual runtime; `selection:"unresolved"` means no target could be established. After a failed bind or switch, inspect `bindingChanged` and `target` before deciding where a later install would run. Every install persists — there is no "temporary" install to undo later. Install once; it stays available in later cells and sessions on that runtime. To install into a different environment, bind or switch to it first (`notebook_bind_runtime` / `notebook_switch_runtime`); there is no per-call environment argument. The app-managed defaults are additive-only (bare name or `name==version`); for uninstalls, version ranges, or git/URL specs, create a named environment and install there. ## Restart the kernel after an install when told to `manage_packages` returns a compact result with `ok`, `needsRestart`, the installer `method`, the target receipt, verified `packageChanges`, and an actionable `error` on failure. A requested package change reports `installed`, `updated`, `unchanged`, or `removed` plus its observed before/after version when available. `unchanged` means only that distribution metadata in the reported target did not change; it does not prove the current Kernel can import the module. When importability or the loaded version matters, use `notebook_execute` to import the package and inspect its version. When `needsRestart` is `true` (always true for R, because the running kernel holds the old library state), call `notebook_restart` before you `import` or `library()`-load the new package, then re-run the cell. For Python, a fresh `import` usually sees the new package without a restart; if an earlier failed import was cached, restart and retry. ## Never install any other way These bypass the install gate and are forbidden: - OS package managers — `apt`, `brew`, `yum` — and `sudo`. - `curl | bash`, downloading and running installers, or hand-rolled `subprocess` installs. - In-cell installs: `%pip install`, `!pip install`, `install.packages(...)`, `remotes::install_github(...)`. These run inside the kernel, which has no install-network path and is sandboxed in a later phase — they do not belong in a cell. ## When to stop and tell the user Some things are not a `manage_packages` install: - A package that needs a **system / OS-level dependency** (a compiler, a shared C library, a CUDA/GPU toolchain) that is not present. Stop and report the limitation to the user — say what is needed and why it is out of scope here; do not try to self-install system dependencies. When you choose to select a newly created isolated environment (to remove/downgrade a package, use richer specs, or keep a project's deps separate), await `manage_environments(action:"create", language, name)`, check `created.runnable`, and use its canonical `created.runtimeId`. Create does not select the environment; continue only when `created.runnable` is true. With no existing binding for that language, pass the receipt's `runtimeId` to `notebook_bind_runtime`; with an existing binding, pass it to `notebook_switch_runtime`. Do not use the short environment name as `runtimeId`, and do not call list merely to rediscover the environment you just created. Only `action:"list"` returns the full environment snapshot; create and remove do not return that snapshot, and instead return receipts for the environment they created or removed. The app-managed defaults cannot be removed.