Configuration#

conda-workspaces searches for manifests in the current directory and its parents. The first matching file is used.

Workspace search order#

conda.toml — conda-native workspace manifest
pixi.toml — pixi-native format (full compatibility)
pyproject.toml — embedded under [tool.conda.*] or [tool.pixi.*]

Task search order#

conda.toml — conda-native task manifest
pixi.toml — pixi-native format (reads [tasks] directly)
pyproject.toml — reads [tool.conda.tasks] or [tool.pixi.tasks]

conda task add and conda task remove edit whichever of these files is selected by that search order, using the same tables as above (for pyproject.toml, under [tool.conda.tasks] or [tool.pixi.tasks] according to the same precedence rules as reading).

When both [tool.conda] and [tool.pixi] exist in the same pyproject.toml, the entire [tool.conda] table takes precedence. This means that if [tool.conda] has any content (e.g. workspace settings) but no [tool.conda.tasks], tasks from [tool.pixi.tasks] will not be loaded. To use pixi tasks, either remove [tool.conda] entirely or define your tasks under [tool.conda.tasks].

When a file defines both workspace and task sections, both are used.

File formats#

conda.toml#

The conda-native format. Structurally identical to pixi.toml but uses [workspace] exclusively (no [project] fallback). Supports both workspace and task definitions in a single file.

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

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

[pypi-dependencies]
my-pkg = { path = ".", editable = true }

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

[feature.docs.dependencies]
sphinx = ">=7.0"
myst-parser = ">=3.0"

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

[target.linux-64.dependencies]
linux-headers = ">=5.10"

[activation]
scripts = ["scripts/setup.sh"]
env = { PROJECT_ROOT = "." }

[tasks]
build = "python -m build"
test = { cmd = "pytest tests/ -v", depends-on = ["build"] }
lint = { cmd = "ruff check .", description = "Lint the code" }

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

[target.win-64.tasks]
build = "python -m build --wheel"

pixi.toml#

The pixi-native format. conda-workspaces reads this with full compatibility for workspace and task fields:

[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"

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

[tasks]
build = "python -m build"
test = { cmd = "pytest", depends-on = ["build"] }

The legacy [project] table is also accepted (pre-workspace pixi manifests).

pyproject.toml#

Workspace and task configuration is embedded under [tool.conda.*] (preferred) or [tool.pixi.*]:

tool.conda

[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"

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

[tool.conda.tasks]
build = "python -m build"

[tool.conda.tasks.test]
cmd = "pytest"
depends-on = ["build"]

tool.pixi

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

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

[tool.pixi.feature.test.dependencies]
pytest = ">=8.0"

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

[tool.pixi.tasks]
build = "python -m build"
test = { cmd = "pytest", depends-on = ["build"] }

Workspace table#

The [workspace] (or [project]) table defines workspace metadata:

Field	Type	Description
`name`	string	Workspace name (optional, defaults to directory name)
`version`	string	Workspace version (optional)
`description`	string	Short description (optional)
`channels`	list of strings	Conda channels, in priority order
`platforms`	list of strings	Supported platforms (e.g. `linux-64`, `osx-arm64`)
`channel-priority`	string	Channel priority mode: `strict`, `flexible`, or `disabled`

Dependencies#

Dependencies use conda match-spec syntax:

[dependencies]
python = ">=3.10"
numpy = ">=1.24,<2"
scipy = "*"          # any version
cuda-toolkit = { version = ">=12", build = "*cuda*" }

Feature table#

Each [feature.<name>] table can contain:

Field	Type	Description
`dependencies`	table	Conda dependencies for this feature
`pypi-dependencies`	table	PyPI dependencies for this feature
`channels`	list	Additional channels for this feature
`platforms`	list	Platform restrictions for this feature
`system-requirements`	table	System-level requirements
`activation.scripts`	list	Activation scripts
`activation.env`	table	Environment variables set on activation

Environments table#

Each entry in [environments] defines a named environment:

Field	Type	Description
`features`	list of strings	Features to include (in addition to default)
`no-default-feature`	bool	Exclude the default feature (default: false)

Shorthand forms are supported:

[environments]
# Full form
test = { features = ["test"] }

# Features only
lint = ["lint"]

# Default environment shorthand
default = []

Task fields#

Field	Type	Description
`cmd`	`string` or `list[string]`	Command to execute. Omit for aliases.
`args`	`list`	Named arguments with optional defaults.
`depends-on`	`list`	Tasks to run before this one.
`cwd`	`string`	Working directory for the task.
`env`	`dict`	Environment variables to set.
`description`	`string`	Human-readable description.
`inputs`	`list[string]`	Glob patterns for cache inputs.
`outputs`	`list[string]`	Glob patterns for cache outputs.
`clean-env`	`bool`	Run with minimal environment variables.
`default-environment`	`string`	Conda environment to activate by default.
`target`	`dict`	Per-platform overrides (keys are platform strings).

Task argument definitions#

[tasks.test]
cmd = "pytest {{ path }} {{ flags }}"
args = [
  { arg = "path", default = "tests/" },
  { arg = "flags", default = "-v" },
]

Task dependency definitions#

Simple list:

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

With arguments:

[tasks.check]
depends-on = [
  { task = "test", args = ["tests/unit/"] },
]

With environment:

[tasks.check]
depends-on = [
  { task = "test", environment = "py311" },
]