conda-workspaces

Project-scoped multi-environment workspaces and task runner for conda, with pixi manifest compatibility.

Define environments and tasks in your project manifest, compose environments from reusable features, and let conda handle the solving and installation. Works with existing pixi manifests -- no new package manager required.

Quick start

Create a conda.toml in your project root:

[workspace]
name = "my-project"
channels = ["conda-forge"]
platforms = ["linux-64", "osx-arm64", "win-64"]

[dependencies]
python = ">=3.10"
numpy = ">=1.24"

[feature.test.dependencies]
pytest = ">=8.0"
pytest-cov = ">=4.0"

[environments]
test = { features = ["test"] }

[tasks]
test = { cmd = "pytest tests/ -v", description = "Run the test suite" }
lint = "ruff check ."

[tasks.check]
depends-on = ["test", "lint"]

Install and manage your environments, then run tasks:

$ conda workspace install              # solve + install + generate conda.lock
$ conda workspace envs                 # list defined environments
$ conda task run check                 # runs lint and test in dependency order
$ conda workspace shell -e test        # spawn a shell with test env activated
$ conda workspace install --locked     # reproducible install from conda.lock

Why?

Conda handles environments and packages. pixi introduced a great project model with multi-environment workspaces and a task runner, but it brings its own solver and environment management.

conda-workspaces reads pixi-compatible manifests and delegates solving and installation to conda's own infrastructure. You get workspace management and task running inside the conda CLI without switching tools.

What it does

• Reads conda.toml, pixi.toml, and pyproject.toml workspace manifests
• Multi-environment support with composable features
• Project-local environments in .conda/envs/
• Lockfile generation (conda.lock) using a rattler-lock-derived schema for reproducible installs
• Workspace archives with optional receipt verification for portable handoff
• Per-platform dependency overrides via [target.<platform>]
• PyPI dependencies translated and resolved alongside conda packages via conda-pypi
• Activation scripts and environment variables per feature
• System requirements as virtual package constraints
• Per-workspace channel priority override
• Task dependencies with topological ordering (depends-on)
• Jinja2 templates in commands ({{ conda.platform }}, conditionals)
• Task arguments with defaults, input/output caching, and per-platform overrides
• conda workspace / conda task subcommands (also available as cw / ct aliases)

Installation

conda install -c conda-forge conda-workspaces

CLI

conda-workspaces registers conda workspace and conda task subcommands, and also provides cw and ct as shorter aliases.

Workspace commands

Command	Description
conda workspace init	Initialize a new workspace manifest
conda workspace install	Create/update workspace environments
conda workspace install --locked	Install from lockfile (skip solving)
conda workspace lock	Generate/update conda.lock
conda workspace list	List packages in an environment
conda workspace envs	List defined environments
conda workspace info -e ENV	Show environment details
conda workspace add SPECS...	Add dependencies
conda workspace remove SPECS...	Remove dependencies
conda workspace export	Export environments and manifests through conda exporters
conda workspace import FILE	Import supported project manifests
conda workspace quickstart SPECS...	Bootstrap a workspace, install it, and optionally open a shell
conda workspace shell -e ENV	Spawn a shell with an environment activated
conda workspace activate -e ENV	Print activation instructions
conda workspace clean	Remove installed environments
conda workspace archive	Create a portable workspace archive
conda workspace unarchive	Extract and optionally verify a workspace archive

Task commands

Command	Description
conda task run TASK	Run a task (with dependency resolution)
conda task list	List available tasks
conda task add NAME CMD	Add a task to the manifest
conda task remove NAME	Remove a task from the manifest
conda task export	Export tasks to conda.toml format

What it doesn't do

conda-workspaces is a workspace manager and task runner, not a package manager replacement. It does not bundle its own solver or bypass conda's installation machinery. If you want a fully integrated tool that handles everything including its own solver, see pixi.

Documentation

• User guide
• conda.toml specification
• JSON schema
• Archive receipt schema

Demos

See demos/README.md for animated terminal recordings of workspace and task features.

Development

pixi install
pixi run test
pixi run lint

Acknowledgements

The workspace and task system in conda-workspaces is directly inspired by the work of the prefix.dev team on pixi. Their design of workspace manifests, features, environments, platform targeting, task dependencies, caching, and template variables provided the blueprint for this plugin.

License

BSD 3-Clause. See LICENSE.