uv-torch-compass

日本語

By using uv-torch-compass, you can test official PyTorch package indexes against both your version requirements and the current Linux machine, then safely write the first verified choice to the target project's pyproject.toml.

An index is a package download location. PyTorch publishes separate official indexes for CPU and NVIDIA CUDA builds. This tool checks more than whether a package can be installed. By default, it rejects CUDA builds newer than the selected NVIDIA driver normally supports, then runs PyTorch, NumPy, the selected GPU, cuBLAS, cuDNN, and optional torchvision or torchaudio checks before applying a choice.

Quick start

You need Linux, a recent uv, internet access, and Python 3.10–3.14. PyTorch may be declared directly or introduced by another selected package such as vllm.

For a minimal project:

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.10,<3.15"
dependencies = ["torch>=2.5"]

For a framework that depends on PyTorch, keep its real dependency in the project:

dependencies = ["vllm==0.19.1"]

The candidate environment first locks the complete selected dependency graph for the chosen Python minor version, Linux, and CPU architecture. If vllm requires particular torch, torchvision, or torchaudio versions, those constraints participate in backend selection. The tool redirects those transitive PyTorch packages to the same official index, relocks until the sources are consistent, and preserves the framework requirement.

For a reviewed exact requirement such as vllm==0.6.0, uv-torch-compass narrows the CUDA candidates before locking. For a range such as vllm>=0.19.1, it may reject an incompatible resolved vLLM release and retry an older release on the same backend. The search is bounded. When apply uses a verified alternative, the original range remains in the dependency list and an exact, tool-managed uv constraint makes the verified result reproducible.

Candidate resolution also preserves relevant uv constraints, overrides, private indexes, and selected path, Git, URL, or workspace sources. Only PyTorch packages are redirected to the official candidate index.

If locking succeeds but a later package cannot be installed, the result keeps the resolved PyTorch versions and reports the actual blocker instead of claiming that the backend is unavailable. For example, it can distinguish “torch==2.10.0+cu126 resolved” from “the xgrammar wheel required by vllm is unavailable for Linux x86_64.” Complete redacted uv output remains in the private log.

From the target project, run a version published on PyPI to verify a candidate and preview the change:

uvx uv-torch-compass plan

To try a local checkout or wheel instead, select it explicitly:

uvx --from /path/to/uv_torch_compass uv-torch-compass plan

If the plan is suitable, apply it. This updates pyproject.toml, locks the workspace, synchronizes the selected project environment, and verifies the result again:

uvx uv-torch-compass apply

Later, validate the recorded source, lockfile, synchronized environment, and installed runtime without changing them:

uvx uv-torch-compass check

When using a local checkout, replace /path/to/uv_torch_compass with this repository's path and keep the same --from prefix for apply and check. Add --pyproject /path/to/project/pyproject.toml when running from another directory.

Choosing what to test

The default --backend auto --cuda-compatibility strict policy behaves as follows:

• When an NVIDIA GPU is visible, it tests only concrete CUDA builds that the driver normally supports, from newer to older. It does not silently switch to CPU when those candidates fail.
• When no NVIDIA GPU is visible, it tests the official CPU build.

The command stops at the first candidate that passes. It does not benchmark every candidate or claim to choose the fastest build. This also means that a machine whose nvidia-smi output says CUDA Version: 12.4 will not accept cu129 under the default policy.

You can narrow the policy:

uv-torch-compass plan --backend cpu
uv-torch-compass plan --backend cuda
uv-torch-compass plan --backend cu128
uv-torch-compass plan --channel nightly
uv-torch-compass plan --probe-profile compile
uv-torch-compass plan --framework-probe vllm

stable is the default channel. nightly is used only when explicitly selected. CUDA minor-version compatibility is also opt-in with --cuda-compatibility minor; it can use a newer CUDA runtime within the same major family, but a successful result is reported with a warning. See backend and runtime selection for the exact order and checks.

When the resolved graph contains vllm, the same bounded vLLM check runs automatically. --framework-probe vllm remains available when you want to request it explicitly. The check covers metadata, importability, the native extension, and the selected execution platform without downloading a model or starting workers.

Before installing the complete candidate graph, uv-torch-compass extracts only the locked vLLM wheel when the active uv supports selective installation. It does not import or execute the wheel. Instead, it reads the native ELF metadata and compares required libraries such as libcudart.so.13 with the PyTorch backend. Reviewed official-wheel facts supplement this inspection. A mismatch such as “vLLM requires CUDA 13, but cu129 provides CUDA 12.9” is therefore reported before repeated multi-gigabyte installs. Python API failures such as an unavailable DTensor are reported separately from CUDA ABI failures.

Safety at a glance

• plan installs and tests candidates in temporary environments but does not change the target pyproject.toml, uv.lock, or project environment.
• apply creates timestamped backups and treats a workspace member's pyproject.toml and the shared root uv.lock as one transaction.
• Candidate verification separates locking, locked installation, runtime checks, and framework checks. It limits the temporary lock to the selected Python minor version, Linux, and CPU architecture, allowing uv to backtrack to a version with a usable wheel when one exists.
• Candidate graphs are read through uv's JSON workspace metadata when available. A validated lockfile reader remains as a compatibility fallback and accepts wheel entries whose optional size is absent.
• Before changing the project environment, apply locks the complete graph and performs a locked sync dry run. It also records the current Linux architecture as a required uv environment, so unavailable wheels fail before installation starts.
• Writes use same-directory temporary files and atomic replacement. A workspace lock prevents two apply processes from updating together.
• Lock, sync, final validation, timeout, SIGINT, and SIGTERM failures trigger file rollback and an environment recovery attempt.
• Logs and JSON reports redact common credential forms and are created with private file permissions. If apply succeeds but a requested report cannot be written, the project remains applied and the command exits with 1 while reporting applied: true.
• uv older than 0.11.28 produces an upgrade warning. Metadata and selective-install capabilities are checked separately; unavailable optional capabilities use validated fallbacks while full installation and runtime validation remain required.

Review git diff after plan and apply. Backups remain after success; recovery and troubleshooting explains their names and limitations.

Supported scope

• plan, apply, and check run on Linux. --help and --version work on other systems.
• CPU and NVIDIA CUDA builds are supported. AMD ROCm and Intel XPU are rejected.
• Stable and nightly official PyTorch indexes are supported; stable never falls back to nightly automatically.
• Base dependencies, selected extras, selected dependency groups, uv workspaces, torchvision, and torchaudio are supported.
• CUDA success requires GPU tensor, cuBLAS, cuDNN, architecture, and selected companion-package checks. --probe-profile compile additionally tests torch.compile.
• When no GPU is specified, the visible device with the most free memory is selected. Use --cuda-device for deterministic selection.
• NVIDIA drivers are never installed or updated. Re-run plan and apply after updating a driver.
• Exit codes are 0 for success, 1 for configuration or operational failure, and 2 for invalid command syntax.

Documentation

See the documentation index for the complete map.