Quick start

Installation

conda

conda install -c conda-forge conda-workspaces

pixi

pixi global install conda-workspaces

Both methods provide the cw and ct shortcut commands. Installing into a conda base environment also registers the conda workspace and conda task plugin subcommands.

Your first tasks

Create a conda.toml in your project root:

[tasks]
hello = "echo 'Hello from conda-workspaces!'"
test = { cmd = "pytest tests/ -v", depends-on = ["build"] }
build = "python -m build"

Run a task:

conda task run hello
conda task run test    # runs build first, then test
conda task list        # see all tasks

Tasks run in your current conda environment. No workspace definition is required — you can start with tasks alone and add workspace features later.

Your first workspace

Add workspace configuration to the same conda.toml:

conda.toml

[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]
default = []
test = { features = ["test"] }

pixi.toml

[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]
default = []
test = { features = ["test"] }

pyproject.toml

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

[tool.conda.dependencies]
python = ">=3.10"
numpy = ">=1.24"

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

[tool.conda.environments]
default = []
test = { features = ["test"] }

Tip

cw and ct are available as shorter aliases for conda workspace and conda task.

Or use the init command to scaffold one:

conda workspace init
# or: conda workspace init --format conda
# or: conda workspace init --format pyproject

Install environments

conda workspace install

This creates project-local conda environments under .conda/envs/ for each environment defined in your manifest. A conda.lock file is generated automatically after solving.

You can point to a specific manifest with --file / -f:

conda workspace install -f path/to/conda.toml

To recreate environments from scratch, use --force-reinstall:

conda workspace install --force-reinstall

Lock

The conda workspace lock command runs the solver and records the solution in conda.lock without installing any environments:

conda workspace lock

Reproducible installs

Use --locked to install from the lockfile. This validates that the lockfile is still fresh relative to the manifest — if the manifest has changed, the install fails:

conda workspace install --locked

Use --frozen to install from the lockfile as-is, without checking freshness:

conda workspace install --frozen

Run in workspace environments

Once your workspace is installed, run tasks in specific environments:

conda task run -e test pytest -v

Run a one-shot command in an environment:

conda workspace run -e test -- python -c "import numpy; print(numpy.__version__)"

Or spawn an interactive shell:

conda workspace shell -e test

Add dependencies

conda workspace add numpy

Add to a specific feature:

conda workspace add --feature test pytest

Add a PyPI dependency:

conda workspace add --pypi requests

List packages and environments

conda workspace list              # packages in default env
conda workspace list -e test      # packages in test env
conda workspace envs              # list defined environments

Workspace overview

conda workspace info
conda workspace info -e test      # details for a specific environment

Next steps

• Read about features to learn how environments and tasks work

• See the configuration reference for all manifest options

• Check out the tutorials for more in-depth guides