#4636·kornia

pixi run install, install-docs and build-docs fail as documented: the task is ambiguous

Author: awss1iCreated Sep 17, 2026Updated Sep 17, 2026

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, py314

pixi 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 run pixi 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:

  1. Rename the CUDA variants (for example install-cuda and install-docs-cuda) and update the one documented CUDA command, pixi run -e cuda install, to match. The bare commands then work as written everywhere.
  2. Keep pixi.toml as it is and change every documented bare command to name the environment (pixi run -e default install, and so on).

Acceptance criteria

  • Every pixi run command in CONTRIBUTING.md, README.md and AGENTS.md runs as written on pixi 0.40.0 and on the current pixi from install.sh.
  • pixi run build-docs resolves its install-docs dependency.
  • 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.