pixi run install, install-docs and build-docs fail as documented: the task is ambiguous
The setup commands in CONTRIBUTING.md, README.md and AGENTS.md fail as written:
$ pixi run install
Error: × the task 'install' is ambiguous
help: These environments provide the task 'install': default, cuda, py311, py312, py313, py314pixi run install-docs fails the same way, and so does pixi run build-docs, through its depends-on = ["install-docs"].
Cause
pixi.toml defines install and install-docs both in [tasks] and, with different commands, in [feature.cuda.tasks]. I isolated it on copies of pixi.toml at 607869e2, with every task command replaced by an echo:
| command | pixi.toml as on main |
with the two [feature.cuda.tasks] entries removed |
|---|---|---|
pixi run install |
× the task 'install' is ambiguous |
runs the base task |
pixi run install-docs |
× the task 'install-docs' is ambiguous |
runs the base task |
pixi run build-docs |
× the task 'install-docs' is ambiguous |
runs install-docs, then build-docs |
pixi run -e default install |
runs the base task | runs the base task |
pixi run -e cuda install |
runs the CUDA task | runs the base task |
This was on pixi 0.40.0, the version CI pins. pixi run install fails the same way on pixi 0.81.0 from curl -fsSL https://pixi.sh/install.sh | bash in a clean ubuntu:24.04 container, following CONTRIBUTING.md.
CI doesn't hit this because every workflow passes an environment: tests.yml uses pixi run -e <py env> install, and typecheck.yml uses pixi run -e default install.
Where it is documented
- CONTRIBUTING.md: lines 91 and 111 (
pixi run install), 112 (pixi run install-docs), 137 and 188 (pixi run build-docs), and 161 ("Update it and runpixi run install"). - README.md: line 182 (
pixi run install). - AGENTS.md: lines 26 (
pixi run install) and 44 (pixi run build-docs).
Scope
This is a maintainer choice between two approaches:
- Rename the CUDA variants (for example
install-cudaandinstall-docs-cuda) and update the one documented CUDA command,pixi run -e cuda install, to match. The bare commands then work as written everywhere. - Keep
pixi.tomlas it is and change every documented bare command to name the environment (pixi run -e default install, and so on).
Acceptance criteria
- Every
pixi runcommand in CONTRIBUTING.md, README.md and AGENTS.md runs as written on pixi 0.40.0 and on the current pixi frominstall.sh. pixi run build-docsresolves itsinstall-docsdependency.- The CUDA environment still installs the CUDA build of torch.
Size: small. It's two lines in pixi.toml plus doc edits in three files, or doc edits only, and a check of each command on both pixi versions.
Found while setting up for #4628.
Source: kornia/kornia