Motivation#

Why conda-workspaces?#

Conda manages packages and environments. conda-workspaces adds workspace manifests and a task runner, so you can define related environments and the commands that use them in one place.

pixi uses a workspace model that combines multiple environments and tasks in one manifest. conda-workspaces brings that model to conda as a plugin, using conda’s own solver and environment management.

Workspaces and tasks, not a new package manager#

conda-workspaces adds workspace-level orchestration and task running on top of conda’s existing environment management. It does not replace conda’s solver, channels, or installation machinery.

In pixi, a single pixi.toml manages workspace definitions, task definitions, and installation. Running pixi install uses rattler (a Rust-based solver) to resolve and install packages into .pixi/envs/. conda-workspaces separates concerns:

Responsibility	In pixi	In conda + conda-workspaces
Define workspace & envs	`pixi.toml` or `pyproject.toml`	`conda.toml`, `pixi.toml`, or `pyproject.toml`
Define tasks	`pixi.toml` or `pyproject.toml` `[tasks]`	Same manifest file
Solve dependencies	rattler (bundled)	configured conda solver backend
Install packages	rattler (into `.pixi/envs/`)	conda (into `.conda/envs/`)
Manage environments	`pixi install`	`conda workspace install` (delegates to conda)
Run tasks	`pixi run <task>`	`conda task run <task>`
Run commands in env	`pixi run CMD`	`conda workspace run -- CMD` or `conda workspace shell -e ENV -- CMD`
Activate	`pixi shell`	`conda workspace shell` / `conda activate .conda/envs/<name>`

With conda handling environment management:

Workspaces use conda’s configured solver backend and package cache
Environments are standard conda prefixes (compatible with all conda tooling)
No additional resolver or package installation system to maintain
Works with existing conda channels, mirrors, and authentication
Incremental adoption without changing your existing conda workflow
Tasks work standalone without a workspace definition

Tasks without workspaces#

A conda.toml with only a [tasks] table is valid, without [workspace] or [dependencies]. Tasks run in the active conda environment, so you can start with tasks and add workspace features later:

# A valid conda.toml — tasks only, no workspace
[tasks]
test = "pytest tests/ -v"
lint = "ruff check ."
check = { depends-on = ["test", "lint"] }

Compatibility with pixi#

conda-workspaces reads the supported workspace and task portions of pixi manifests. A workspace defined in a pixi.toml or pyproject.toml can use both tools when its manifest uses fields supported by both:

pixi users run pixi install and pixi run as usual
conda users run conda workspace install and conda task run using conda’s solver

Each tool stores environments in a different directory (.pixi/envs/ vs .conda/envs/), so they don’t interfere with each other.

See DESIGN.md for the compatibility mapping.

Comparison to other tools#

Tool	Scope	Tasks	Multi-env	Lock files	Solver
conda-workspaces	Workspaces + tasks	Yes	Yes	Yes (`conda.lock`)	configured conda solver backend
pixi	Workspace management	Yes	Yes	Yes	rattler (bundled)
conda-project	Project management	Commands only	Yes	Yes	conda (via conda-lock)
anaconda-project	Project management	Commands only	Yes	Yes	conda
conda-devenv	Env templating	No	Via includes	Yes	conda / mamba
conda-lock	Lock files only	No	N/A	Yes	conda
tox / nox	Test matrix	Yes	Virtualenvs	No	pip

Prior art#

conda-workspaces builds on ideas from several earlier tools.

anaconda-project was the first tool to add project-scoped conda environments, command runners, and secrets management via an anaconda-project.yml manifest. It supports multiple named environment specs and lock files. However, development has slowed and the manifest format is not shared with any other tool.

conda-project is the spiritual successor to anaconda-project. It uses conda-project.yml for multi-environment management and generates lock files via conda-lock. conda-project remains in alpha and uses its own manifest format.

conda-devenv takes a different approach: it extends environment.yml with Jinja2 templating, file includes, and environment variable definitions. It is well suited for composing a single environment from multiple projects, but does not support multiple independent environments per project.

conda-workspaces differs from all of the above in two ways:

It reads pixi’s TOML workspace manifests. A workspace can use a single pixi.toml or pyproject.toml with both tools when its manifest uses fields supported by both.
It integrates as a conda plugin (conda workspace, conda task) rather than shipping a standalone CLI. Environments are standard conda prefixes that work with conda activate and all existing conda tooling.

Task runner prior art#

pixi was the first tool to integrate task dependencies, platform overrides, input/output caching, template variables, and task arguments with conda package management. Its task system is the direct inspiration for the task features in conda-workspaces. For template rendering and execution, pixi uses MiniJinja (Rust) and deno_task_shell for cross-platform execution, while conda-workspaces uses Jinja2 (Python) and the native platform shell.

General-purpose Python task runners like tox, nox, invoke, and hatch each provide ways to define and run project tasks. tox and nox focus on test-matrix automation with virtualenvs. invoke is a general-purpose Make replacement. hatch offers scripts and environment matrices for Python projects. None of them integrate directly with conda environments or conda’s plugin system.

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. We are grateful for their contribution to the conda ecosystem.

The anaconda-project and conda-project teams explored project-scoped environments and command runners long before conda-workspaces existed. Their work informed how project-level automation fits into the conda ecosystem.