Format names and aliases

Each lockfile format has a version-pinned canonical name and, when a short form reads better at the command line, an unversioned alias.

Names today

Canonical name	Unversioned alias	Files
conda-lock-v1	conda-lock	conda-lock.yml, conda-lock.yaml
rattler-lock-v6	pixi	pixi.lock

rattler-lock-v6 also accepts pixi-lock-v6 for compatibility with docs and tooling that use the pixi-lock-v* naming.

What the two names mean

The canonical names (conda-lock-v1, rattler-lock-v6) identify one specific file-format version and never change meaning. conda-lock-v1 will still be conda-lock-v1 after conda-lock-v2 ships. Use these in committed lockfiles, CI pins, and anywhere a file is exchanged with another tool.

The unversioned aliases (conda-lock, pixi) resolve to whichever version is current-stable in the installed conda-lockfiles release. Use these when you want the latest format and do not need the invocation to outlive the next release.

Concretely: conda export --format pixi writes rattler-lock-v6 today. If a later release makes rattler-lock-v7 current-stable, the same command writes v7.

Alias ordering convention

The ALIASES tuple in each format module puts the short unversioned alias first. conda uses the first alias as the display label in --help output, with the canonical name and any remaining aliases shown in parentheses:

Lockfiles:
  - pixi (rattler-lock-v6, pixi-lock-v6)
  - conda-lock (conda-lock-v1)

All names in the tuple, and the canonical name itself, remain valid everywhere conda accepts a --format value. The ordering only affects the help label.

When adding a new alias, place the short form first.

Default filenames across versions

Each format’s default_filenames is the filename users are already typing (pixi.lock, conda-lock.yml). A new version of the same format claims the same filenames; conda-lockfiles does not invent pixi-v7.lock.

That means two export plugins can register the same default_filenames entry once a new version ships alongside the old one. conda export --file pixi.lock (no --format) needs conda to pick one. Conda today raises PluginError on that collision; conda/conda#15963 tracks the tiebreaker work so conda picks the current-stable plugin. Until that lands, users pass --format rattler-lock-vN alongside --file pixi.lock to disambiguate.

On the read side, conda env create -f pixi.lock dispatches on file contents. Each specifier’s can_handle() rejects files it cannot parse, so both plugins can coexist without manual disambiguation.

--file pixi.lock without --format writes current-stable (whatever pixi currently resolves to) once the tiebreaker in conda/conda#15963 lands. Pin --format rattler-lock-v6 when the format version needs to outlive the next alias flip.

Re-exporting a lockfile at a new format version

Existing pixi.lock files on disk remain valid after an alias flip; nothing rewrites them. To upgrade one, re-create the environment from the existing file and re-export at the new format:

conda env create --name lockfile-upgrade --file pixi.lock
conda export \
  --name lockfile-upgrade \
  --format rattler-lock-v7 \
  --file pixi.lock \
  --platform linux-64 \
  --platform osx-arm64 \
  --platform win-64

Pin the new canonical name in the re-export so the command is unaffected by future alias flips. The same pattern works for conda-lock-v1 to a future conda-lock-v2.