conda.toml specification

This page is the normative reference for the conda.toml workspace manifest format read by conda-workspaces. It is the human-readable companion to schema/conda-toml-1.schema.json and the source material for the future Conda Enhancement Proposal that will standardise the format across the conda ecosystem.

For tutorials and examples see Configuration and Quickstart; for plugin name aliases see Plugin format names and aliases.

Status

Field	Value
Format name	conda.toml
Schema version	1
Schema URL	https://schemas.conda.org/conda-toml-1.schema.json
Canonical plugin name	conda-workspaces (see format-aliases.md)
Reference implementation	conda_workspaces.manifests.toml.CondaTomlParser
Standardisation track	Pre-CEP — see the CEP tracker issue

Scope

conda.toml describes a workspace: a project root that may declare one or more conda environments composed from reusable features, plus a set of tasks that run inside those environments. It is the conda-native sibling of pixi.toml; the schema is a constrained subset of pixi.toml plus one conda-specific extension, with the explicit goal that the conda-vouched-for subset can also be consumed by pixi. The reverse direction (pixi.toml → conda.toml) holds only when the pixi.toml keeps to the fields described here; see Pixi compatibility ladder below for the precise asymmetry.

Out of scope: package build recipes (use recipe.yaml), package distribution metadata (pyproject.toml [project]), and lockfile contents (use the companion conda.lock, see Lockfile relationship below).

File detection

A conda-workspaces tool MUST detect a workspace using one of these two forms, in order:

1. A file named conda.toml at the workspace root that contains a top-level [workspace] table.

2. A file named pyproject.toml at the workspace root that contains a [tool.conda.workspace] table.

A conda.toml without a [workspace] table is permitted: it is treated as a tasks-only manifest (see [tasks] below) and does not constitute a workspace on its own.

For compatibility, conda-workspaces also reads pixi.toml (top-level [workspace] / [project]) and pyproject.toml [tool.pixi.workspace]. That compatibility surface is not part of this specification — it is documented in Configuration.

Search order

Tools that search a directory tree for the manifest MUST consult these filenames in this order, returning the first hit:

1. conda.toml

2. pixi.toml

3. pyproject.toml

When more than one form is present in the same directory, conda.toml wins. When pyproject.toml contains both [tool.conda] and [tool.pixi] tables, [tool.conda] wins (see Configuration).

Top-level tables

All tables are optional unless marked required. Field types follow TOML conventions: string, integer, boolean, array, table, inline-table.

[workspace] (required when used as a workspace manifest)

Workspace metadata.

Field	Type	Required	Description
name	string	no	Workspace name. Defaults to the workspace directory name.
version	string	no	Workspace version.
description	string	no	Short prose description.
channels	array of channel	yes	Conda channels in priority order.
platforms	array of platform	yes	Platforms the workspace targets. Used to drive multi-platform solves.
channel-priority	string	no	One of "strict", "flexible", "disabled". Maps to conda’s solver setting.
envs-dir	string	no	Where per-env prefixes live, relative to the workspace root. Default: .conda/envs.

A channel is either:

• a string containing a channel name ("conda-forge") or URL ("https://my.channel/label/dev"), or

• an inline table { channel = "<name-or-url>" }. Other keys (e.g. priority) are reserved and currently ignored by this version.

A platform is a conda subdir string from the closed enum defined in the JSON schema under $defs.platform (e.g. linux-64, osx-arm64, win-64, noarch).

[dependencies]

Conda packages that belong to the default feature. Keys are package names; values are either a version constraint string or a detailed dependency spec.

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

A detailed conda dependency accepts:

Field	Type	Description
version	string	Version constraint (e.g. ">=12").
build	string	Build-string glob (e.g. "*cuda*").

[pypi-dependencies]

PyPI packages that belong to the default feature. Keys are package names; values are either a PEP 508 version-constraint string or a detailed PyPI dependency spec:

Field	Type	Description
version	string	PEP 508 constraint.
path	string	Local path to the package.
editable	boolean	Install in editable mode.
git	string	Git repository URL.
branch	string	Branch (with git).
tag	string	Tag (with git).
rev	string	Revision (with git).

[activation]

Default-feature activation settings.

Field	Type	Description
scripts	array of string	Shell scripts sourced on environment activation.
env	table of string -> string	Environment variables set on activation.

[system-requirements]

Default-feature system-level constraints (e.g. minimum glibc, macOS version). All keys are strings; values are stringified version constraints. Recognised keys mirror conda’s virtual-package names (__glibc, __osx, __cuda, …).

[target.<platform>]

Per-platform overrides for the default feature. <platform> MUST be one of the platform values listed above.

Field	Type	Description
dependencies	conda deps	Platform-specific conda overrides.
pypi-dependencies	PyPI deps	Platform-specific PyPI overrides.

[feature.<name>]

A reusable group of dependencies and settings. <name> is an arbitrary identifier referenced from [environments].

Field	Type	Description
dependencies	conda deps	Conda dependencies for this feature.
pypi-dependencies	PyPI deps	PyPI dependencies for this feature.
channels	array of channel	Additional channels.
platforms	array of platform	Restrict the feature to these platforms.
system-requirements	table	Per-feature system requirements.
activation	table	Per-feature activation.
target	table of [target.<platform>]	Per-platform dep overrides for the feature.
tasks	table	Tasks contributed by this feature; merged into the workspace task set.

[environments]

A named environment is a composition of one or more features plus (by default) the default feature defined by the top-level [dependencies], [pypi-dependencies], [activation] and [system-requirements] tables.

Two forms are accepted:

[environments]
test = ["test"]                                     # shorthand
docs = { features = ["docs"], no-default-feature = false }

Field	Type	Description
features	array of string	Feature names to include in addition to the default feature.
solve-group	string	Solve-group identifier; environments in the same solve-group are version-coordinated.
no-default-feature	boolean	If true, exclude the default feature from this environment. Default: false.

When [environments] is omitted entirely, a single implicit environment named default is used, composed from the default feature only.

[tasks]

Named tasks runnable via conda task run <name>. Each value is either a command string or a task table.

Field	Type	Description
cmd	string or array of string	Command to execute. Omit to define an alias whose only purpose is depends-on.
args	array of task arg	Named arguments with optional defaults.
depends-on	array of task dep	Tasks to run before this one.
cwd	string	Working directory for the task.
env	table of string -> string	Environment variables to set.
description	string	Human-readable description.
inputs	array of string	Glob patterns for cache inputs.
outputs	array of string	Glob patterns for cache outputs.
clean-env	boolean	Run with a minimal environment.
default-environment	string	Conda environment to activate by default for this task.
target	table of [target.<platform>.tasks]	Per-platform overrides.

A task arg is an inline table such as { arg = "path", default = "tests/" }.

A task dep is one of:

• a string naming another task: "build", or

• an inline table with extra fields: { task = "test", args = ["tests/unit/"], environment = "py311" }.

[target.<platform>.tasks]

Platform-specific task overrides. Each entry follows the same shape as a [tasks] entry.

Composition rules

When a tool resolves an environment named <env>:

1. Start with the default feature (top-level [dependencies], [pypi-dependencies], [activation], [system-requirements], [target]) unless the environment sets no-default-feature = true.

2. Merge in each named feature listed in features, in order. Later features override earlier ones for conflicting keys; lists are concatenated and de-duplicated.

3. Apply [target.<platform>] overrides for the host’s platform last.

Channel order is preserved. Duplicate dependency names within the same stack (conda or PyPI) are an error and the tool MUST surface them to the user.

Lockfile relationship

conda workspace lock and conda workspace install produce and consume conda.lock at the workspace root. The lockfile schema is rattler-lock v6 (the same schema pixi.lock uses) with one on-disk difference: conda.lock writes version: 1 instead of version: 6 so tools can identify the file as conda-workspaces-owned at a glance. The remainder of the document — environments, packages, channels, platform package lists — is byte-compatible.

See Plugin format names and aliases for the canonical and alias strings under which conda.lock is registered.

Lockfile satisfiability check

conda workspace install and conda workspace info evaluate the lockfile against the manifest to determine whether a re-solve is needed. The check is purely structural (no file timestamps) and runs in this order:

1. Schema version – the lockfile version field must match the expected version (1).

2. Environments – every environment declared in the manifest must have a corresponding entry in the lockfile.

3. Channels – the channel list for each environment in the lockfile must match the manifest (order-sensitive, URLs normalized).

4. Platforms – every platform declared in the manifest must be present in each lockfile environment’s packages section.

5. Dependencies – for each dependency in the manifest (on the current platform), a locked package must exist whose version satisfies the manifest’s version spec.

The check returns the first failing condition it finds. The result is one of three states:

Status	Constant	Meaning
up-to-date	LockfileStatus.UP_TO_DATE	All checks pass
out-of-date	LockfileStatus.OUT_OF_DATE	At least one check fails
missing	LockfileStatus.MISSING	No conda.lock file found

JSON output fields

conda workspace info --json includes the following lockfile fields:

Field	Type	Description
lockfile_status	string	One of up-to-date, out-of-date, missing
lockfile_reason	string	Human-readable reason (only present when out-of-date)

Embedded form (pyproject.toml)

The same tables are accepted under [tool.conda.<name>] inside a pyproject.toml:

Top-level table	Embedded equivalent
[workspace]	[tool.conda.workspace]
[dependencies]	[tool.conda.dependencies]
[pypi-dependencies]	[tool.conda.pypi-dependencies]
[activation]	[tool.conda.activation]
[system-requirements]	[tool.conda.system-requirements]
[target.<platform>]	[tool.conda.target.<platform>]
[feature.<name>]	[tool.conda.feature.<name>]
[environments]	[tool.conda.environments]
[tasks]	[tool.conda.tasks]

When both conda.toml and pyproject.toml exist in the same directory, conda.toml wins. When a pyproject.toml contains both [tool.conda] and [tool.pixi] tables, [tool.conda] wins.

Pixi compatibility ladder

conda.toml and pixi.toml share a deliberately overlapping table layout, but they are not byte-for-byte interchangeable. The relationship is:

Direction	Holds?	Why
Every valid conda.toml is a valid pixi.toml (modulo filename).	Yes	The fields enumerated in this spec are all accepted by pixi.
Every valid pixi.toml is a valid conda.toml.	No	Pixi’s [workspace] accepts additional fields (authors, license, readme, homepage, repository, documentation, requires-pixi, preview, build-variants, conda-pypi-map, …) that this v1 schema does not list. The schema rejects unknown keys (additionalProperties: false); pixi-only fields are therefore not accepted in a conda.toml.
pixi reads our default-environment task field.	No	default-environment (in [tasks] and [feature.*.tasks]) is the only conda-workspaces extension; pixi will silently ignore it.
conda-workspaces reads pixi.toml.	Yes	conda-workspaces ships a separate compatibility reader for pixi.toml and [tool.pixi.*]; that reader is out of scope for this spec and is documented in Configuration.

Two intentional differences from pixi.toml:

• conda.toml accepts only [workspace]; the legacy pixi [project] table is not part of this specification.

• conda-workspaces resolves dependencies with conda’s solver (libmamba) and installs them as conventional conda prefixes; pixi’s build-process options (e.g. [package]-style build recipes) are not part of this specification.

If you need pixi-only fields, write a pixi.toml and let conda-workspaces’ compatibility reader handle it; do not extend conda.toml with them.

Versioning policy

The schema is versioned with a single integer (1). A future backwards-incompatible change to required fields, semantics, or defaults bumps the version to 2 and gets a sibling schema URL (https://schemas.conda.org/conda-toml-2.schema.json) and plugin canonical name (conda-workspaces-v2). Aliases follow the rules in format-aliases.md.

Backwards-compatible additions (new optional fields, new platforms in the platform enum) do not bump the version. Tools MUST ignore unknown top-level keys and unknown keys inside known tables in the same major version.

Open questions (non-normative)

These are tracked for the CEP draft and are not part of v1:

• Whether [workspace] should be required to carry version and name (currently both optional).

• Whether solve-group semantics need a normative description beyond “version-coordinated”.

• Whether to standardise an [envs] shorthand that maps a feature one-to-one to an environment of the same name.

• Discovery rules for nested workspaces (currently parent-directory search stops at the first match).

• Whether [tool.pixi.*] compatibility belongs in this specification or in a separate “compatibility” CEP.

• Whether conda.toml should exist as a separate filename at all, or whether the spec should describe a “conda-workspaces dialect of pixi.toml” — i.e. a pixi.toml plus the single default-environment extension, without a parallel filename or schema URL. Trade-off: governance ownership (conda community vs. Prefix.dev) versus format proliferation. See the CEP tracker for discussion.