Coming from pixi

If you already use pixi for workspace management and tasks, conda-workspaces can read the same manifest files. This guide explains how the two tools relate and how to use them side by side.

Key differences

Aspect	pixi	conda-workspaces
Solver	rattler (bundled)	conda / libmamba
Environment location	.pixi/envs/	.conda/envs/
Lock file	pixi.lock	conda.lock
Task runner	Built-in	Built-in (conda task)
Template engine	MiniJinja (Rust)	Jinja2 (Python)
Shell	deno_task_shell	Native platform shell
Package builds	pixi-build (rattler-build)	conda-build (separate)
CLI	pixi	conda workspace / conda task

Using both tools

Since pixi stores environments in .pixi/envs/ and conda-workspaces uses .conda/envs/, both tools can coexist on the same project:

# pixi users
pixi install
pixi run test

# conda users
conda workspace install
conda task run test

Both read the same pixi.toml (or pyproject.toml) manifest — workspace definitions and task definitions alike.

Command mapping

pixi	conda-workspaces
pixi init	conda workspace init
pixi install	conda workspace install
pixi install --locked	conda workspace install --locked (validates lockfile freshness)
pixi install --frozen	conda workspace install --frozen (installs from lockfile as-is)
pixi add python	conda workspace add python
pixi add --feature test pytest	conda workspace add -e test pytest or conda workspace add --feature test pytest
pixi add --pypi requests	conda workspace add --pypi requests
pixi remove numpy	conda workspace remove numpy
pixi run <task>	conda task run <task>
pixi run CMD	conda workspace run -- CMD or conda workspace shell -- CMD
pixi list	conda workspace list (packages in default env)
pixi list (envs)	conda workspace envs
pixi list (specific env)	conda workspace list -e <env>
pixi info	conda workspace info (workspace overview)
pixi info (per-env)	conda workspace info -e <env>
pixi lock	conda workspace lock (pure solve, no install required)
pixi shell	conda workspace shell or conda workspace shell -e <env>
pixi clean	conda workspace clean
pixi task list	conda task list

Template compatibility

pixi uses MiniJinja (Rust) and conda-workspaces uses Jinja2 (Python). The template syntax is identical for all practical purposes:

• {{ pixi.platform }} works in conda-workspaces when reading from pixi.toml

• {{ conda.platform }} is available everywhere

• Jinja2 supports a few extra filters not present in MiniJinja, but you are unlikely to hit any incompatibilities going the other direction

Shell differences

pixi uses deno_task_shell, a cross-platform shell that understands commands like rm on Windows. conda-workspaces uses the native platform shell (sh on Unix, cmd on Windows).

For cross-platform compatibility, use platform overrides:

[tasks]
clean = "rm -rf build/"

[target.win-64.tasks]
clean = "rd /s /q build"

Or use Jinja2 conditionals:

[tasks]
clean = "{% if conda.is_win %}rd /s /q build{% else %}rm -rf build/{% endif %}"

Using conda.toml instead

If your team uses only conda, you can use conda.toml instead of pixi.toml. The format is structurally identical:

conda workspace init --format conda

This creates a conda.toml file with the same workspace/feature/ environment/task structure. The only difference is:

• conda.toml uses [workspace] exclusively (no [project] fallback)

• conda.toml is searched first, before pixi.toml and pyproject.toml

Embedded in pyproject.toml

You can also embed workspace and task configuration in pyproject.toml:

# Preferred: under [tool.conda.*]
[tool.conda.workspace]
channels = ["conda-forge"]
platforms = ["linux-64", "osx-arm64"]

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

[tool.conda.tasks]
test = "pytest tests/ -v"

# Also supported: [tool.pixi.*]
# (same format pixi uses)

Converting to conda.toml

If you want to convert your entire pixi.toml manifest (workspace configuration, dependencies, and tasks) to conda.toml, use the import command:

conda workspace import pixi.toml

This reads your pixi.toml and writes a fully equivalent conda.toml. Use --dry-run to preview the output, or -o custom.toml to choose a different output path.

To export only tasks, use the task export command instead:

conda task export --file pixi.toml -o conda.toml

What’s not supported

Some pixi-only concepts don’t apply to conda-workspaces:

• [package] / pixi-build — use conda-build instead

• [host-dependencies] / [build-dependencies] — part of pixi-build

• deno_task_shell — conda-workspaces uses native platform shells

• solve-group — accepted for compatibility but has no effect (conda’s solver operates on a single environment at a time)

See DESIGN.md for the full compatibility mapping.