Environments

Environment creation, removal, and inspection via conda’s APIs.

Environment manager — create, update, and remove project-local envs.

Uses conda’s Solver API to install packages into project-scoped environments under .conda/envs/<name>/. Each environment is a standard conda prefix that can be activated with conda activate.

class conda_workspaces.envs.PackageRow

JSON-compatible details for an installed package.

build: str

name: str

version: str

conda_workspaces.envs.activate_d_scripts(prefix: Path) → set[str]

Return the filenames under $PREFIX/etc/conda/activate.d/.

Returns an empty set when the directory does not exist. Used to detect new activation hooks installed into an environment, e.g. to warn that a conda workspace shell session needs to be re-spawned.

conda_workspaces.envs.clean_all(ctx: WorkspaceContext) → None

Remove all project-local environments.

conda_workspaces.envs.get_environment_info(ctx: WorkspaceContext, env_name: str) → dict[str, str | int | bool]

Return basic info about an installed environment.

conda_workspaces.envs.install_environment(ctx: WorkspaceContext, resolved: ResolvedEnvironment, *, force_reinstall: bool = False, dry_run: bool = False, prune: bool = False, update_names: set[str] | None = None) → Path

Create or update a project-local environment.

Uses conda’s Solver API directly instead of shelling out, which avoids the overhead of a subprocess and gives full control over the solve/install transaction.

Version-only PyPI dependencies are translated to conda names and merged into the same solver call as conda dependencies, relying on conda-pypi and conda-rattler-solver to resolve and install them in a single pass. Local path PyPI dependencies are built and installed after the conda transaction.

When dry_run is true, solving and transaction rendering still run, but the prefix and its activation metadata remain unchanged. The returned path is the prefix used for solving.

When prune is true, requested specs absent from resolved are removed in a separate transaction before the remaining specs are installed. Conda-libmamba requires add and remove requests to use separate solver instances.

When update_names is supplied, the prefix must already exist. Only those declared and installed conda roots are passed to the solver, while other installed records remain frozen unless satisfying the requested update requires a dependency change.

Raises SolveError if dependency resolution fails.

conda_workspaces.envs.list_installed_environments(ctx: WorkspaceContext) → list[str]

Return names of environments that are currently installed.

conda_workspaces.envs.list_installed_packages(ctx: WorkspaceContext, env_name: str) → list[PackageRow]

Return installed package details sorted by package name.

conda_workspaces.envs.remove_anchored_directory(parent_descriptor: int, name: str, expected_identity: tuple[int, int]) → None

Delete one directory tree through descriptors without following leaves.

shutil.rmtree only gained its public dir_fd argument in Python 3.11. This uses public os descriptor APIs so supported Python 3.10 platforms keep the same anchored deletion guarantee.

conda_workspaces.envs.remove_environment(ctx: WorkspaceContext, env_name: str, *, expected_envs_identity: tuple[int, int] | None = None, expected_prefix_identity: tuple[int, int] | None = None) → None

Remove a prefix without following a replaced directory generation.

conda_workspaces.envs.validate_activation_metadata(prefix: Path, resolved: ResolvedEnvironment) → None

Validate activation inputs without changing an environment prefix.

Solver installs and exact lockfile installs share this validation so a multi-environment preflight can reject unsafe metadata before any prefix transaction begins.

conda_workspaces.envs.validate_path_dependencies(resolved: ResolvedEnvironment) → None

Validate local PyPI project inputs without building or installing them.

Building requires Python in the target prefix, so exact-install preflights validate the stable inputs and conda-pypi entry points up front, then leave the actual build for execution after the conda packages are installed.