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"
ruff = ">=0.9"

[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 -e test check         # runs lint and test in the test environment
$ 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
• Runnable container images from locked Linux environments and project files
• 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 -n base 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

Task commands

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 -e test test
pixi run -e dev check

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.