Inconsistent dependency resolution across documented install paths (torch, torchvision)

[cuiliaomei-beep]

Is there an existing issue for this?

• I have searched the existing issues

Bug description

The repository documents more than one way to install it, and they do not produce the same environment: following pip install . installs torch 2.14.0 from PyPI, while following Dockerfile:9 installs torch 2.6.0+cu124 from download.pytorch.org/whl/cu124; 1 further package(s) differ the same way (torchvision). A user who reads the README/Dockerfile expects the CUDA/ROCm build named there, but depending on the installer and index order gets a different variant or major version, which is confusing to debug (GPU silently unused, mismatched CUDA libraries) and means the two paths are not tested against the same dependencies. Because the selection is decided by index visibility and installer semantics rather than by the project, it is also an exposure: whichever index publishes a higher version of these names decides what gets installed.

torch:

• pip install . (pyproject/requirements only, PyPI) → torch 2.14.0 from PyPI
• Dockerfile:9 (pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cu124) → torch 2.6.0+cu124 from download.pytorch.org/whl/cu124

torchvision (transitive):

• pip install . (pyproject/requirements only, PyPI) → torchvision 0.29.0 from PyPI
• Dockerfile:9 (pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cu124) → torchvision 0.21.0+cu124 from download.pytorch.org/whl/cu124

Operating System

Linux (Ubuntu 24.04, x86_64; WSL2)

CEBRA version

main @ d1842ccc659b

Device type

N/A (dependency resolution only, no GPU involved)

Steps To Reproduce

Dry-run resolutions (nothing is installed), Python 3.11, Linux x86_64, pip 26.2.1 / uv 0.12.10, index state of 2026-09-07:

# A: `pip install .` (pyproject/requirements only, PyPI)
pip install --dry-run --report a.json "torch" "torchvision"
#   -> `torch 2.14.0` from PyPI; `torchvision 0.29.0` from PyPI

# B: `Dockerfile:9` (`pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cu124`)
pip install --dry-run --report b.json "torch" "torchvision" --index-url https://download.pytorch.org/whl/cu124
#   -> `torch 2.6.0+cu124` from download.pytorch.org/whl/cu124; `torchvision 0.21.0+cu124` from download.pytorch.org/whl/cu124

Expected behavior

Every documented install path selects the same file for the package(s) above (same version, same index, same hash), or the documentation states which build is intended.

Relevant log output

# pip --report / uv lock: selected files
[A] torch==2.14.0  https://files.pythonhosted.org/packages/8d/be/c0c8a845bf00552960d2f1f6a00b6ac9750fd312f55429c3e8c6c0e3aac4/torch-2.14.0-cp311-cp311-manylinux_2_28_x86_64.whl
[B] torch==2.6.0+cu124  https://download-r2.pytorch.org/whl/cu124/torch-2.6.0%2Bcu124-cp311-cp311-linux_x86_64.whl
[A] torchvision==0.29.0  https://files.pythonhosted.org/packages/a6/2d/a656bfa09b98d01d4baf30114a5befca1de2f7a16133d94aae01d7cd6942/torchvision-0.29.0-cp311-cp311-manylinux_2_28_x86_64.whl
[B] torchvision==0.21.0+cu124  https://download-r2.pytorch.org/whl/cu124/torchvision-0.21.0%2Bcu124-cp311-cp311-linux_x86_64.whl

Anything else?

Consequences

• Users following one path get a different PyTorch build (CUDA/ROCm/CPU variant or major version) than users following the other; GPU code may run on CPU or fail to load CUDA libraries.
• The environment produced by one path is not the one exercised in CI, so bug reports are hard to reproduce.
• The two paths install files with different hashes from different indexes; which build (and whose build) ends up in the environment is decided by index order and installer behaviour rather than by the project's declaration, and the two files were not verified against each other here.

Root cause

• Cases 1, 2: pip applies version priority across all indexes it can see (PEP 766): when PyPI is visible next to a download.pytorch.org channel, the newer PyPI release wins over the +cuXXX build. uv's default first-index strategy does the opposite (first index that has the name). The selected build therefore depends on the installer and on whether the channel is passed as --index-url or --extra-index-url, not on the declaration.

Where the repo binds these packages to an index

• Dockerfile:9 — torch → https://download.pytorch.org/whl/cu124 (pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cu124)
• tests/_build_legacy_model/Dockerfile:2 — torch → https://download.pytorch.org/whl/cpu (pip install torch --index-url https://download.pytorch.org/whl/cpu)
• .github/workflows/latest.yml:37 — torch → https://download.pytorch.org/whl/cpu (python -m pip install --pre torch --extra-index-url https://download.pytorch.org/whl/cpu)
• .github/workflows/build.yml:94 — torch → https://download.pytorch.org/whl/cpu (python -m pip install torch==${{ matrix.torch-version }} --extra-index-url https://download.pytorch.)
• .github/workflows/latest.yml:38 — torch → https://download.pytorch.org/whl/cpu (python -m pip install --pre torch --extra-index-url https://download.pytorch.org/whl/cpu)
• Dockerfile:9 — torchvision → https://download.pytorch.org/whl/cu124 (pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cu124)

Proposed fix

1. Pin the channel build explicitly in the install command(s) (Dockerfile:9): e.g. torch==<ver>+cu124 torchvision==<ver>+cu124 --index-url https://download.pytorch.org/whl/cu124 instead of unpinned names.
2. Install the PyTorch packages in a dedicated step with --index-url <channel> (single index), then install the remaining requirements from PyPI. Avoid --extra-index-url for the channel: with pip it makes PyPI's newer release win.
3. For uv, declare the channel explicit = true and bind the packages to it so uv never takes them from PyPI:

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu124"
explicit = true

[tool.uv.sources]
torch = { index = "pytorch" }
torchvision = { index = "pytorch" }

4. Commit a lock (uv.lock, or pip-compile/pip lock output with hashes) and make the README/Dockerfile/CI install from it, so every documented path resolves identical files.

Selected files

case	install path	package	version	index	file	sha256
1	pip install . (pyproject/requirements only, PyPI)	torch	2.14.0	PyPI	torch-2.14.0-cp311-cp311-manylinux_2_28_x86_64.whl	8d9e232b6376c62f
1	Dockerfile:9 (pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cu124)	torch	2.6.0+cu124	download.pytorch.org/whl/cu124	torch-2.6.0+cu124-cp311-cp311-linux_x86_64.whl	d4c3e9a8d31a7c0f
2	pip install . (pyproject/requirements only, PyPI)	torchvision	0.29.0	PyPI	torchvision-0.29.0-cp311-cp311-manylinux_2_28_x86_64.whl	85fa54bec1f7d922
2	Dockerfile:9 (pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cu124)	torchvision	0.21.0+cu124	download.pytorch.org/whl/cu124	torchvision-0.21.0+cu124-cp311-cp311-linux_x86_64.whl	137376805aca5ba5

Found by an automated check that resolves the declared dependencies under each documented install path and diffs the selected files. File URLs and sha256 hashes are listed above so the result can be re-checked independently.

Code of Conduct

• I agree to follow this project's Code of Conduct