Metadata-Version: 2.4
Name: uv-torch-compass
Version: 0.7.0
Summary: Verify and configure official PyTorch package indexes for uv projects on Linux
Keywords: cuda,linux,pytorch,torch,uv
Author: Onely7
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: GPU
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Natural Language :: Japanese
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Dist: packaging>=24.2
Requires-Dist: tomli>=2.0.1,<3 ; python_full_version < '3.11'
Requires-Dist: tomlkit>=0.13.2,<1
Maintainer: Onely7
Requires-Python: >=3.10, <3.15
Project-URL: Changelog, https://github.com/Onely7/uv_torch_compass/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/Onely7/uv_torch_compass/blob/main/docs/README.md
Project-URL: Homepage, https://github.com/Onely7/uv_torch_compass
Project-URL: Issues, https://github.com/Onely7/uv_torch_compass/issues
Project-URL: Repository, https://github.com/Onely7/uv_torch_compass
Description-Content-Type: text/markdown

# uv-torch-compass

[日本語](https://github.com/Onely7/uv_torch_compass/blob/main/README_ja.md)

**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](https://docs.astral.sh/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:

```toml
[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:

```toml
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:

```bash
uvx uv-torch-compass plan
```

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

```bash
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:

```bash
uvx uv-torch-compass apply
```

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

```bash
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:

```bash
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](https://github.com/Onely7/uv_torch_compass/blob/main/docs/how-it-works.md) 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](https://github.com/Onely7/uv_torch_compass/blob/main/docs/recovery.md) 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

| Goal | Guide |
| --- | --- |
| Learn the commands and options | [CLI usage](https://github.com/Onely7/uv_torch_compass/blob/main/docs/usage.md) |
| Configure project defaults and environment variables | [Configuration](https://github.com/Onely7/uv_torch_compass/blob/main/docs/configuration.md) |
| Understand the process flow, backend, channel, GPU, Python, and runtime checks | [How selection works](https://github.com/Onely7/uv_torch_compass/blob/main/docs/how-it-works.md) |
| Use extras, groups, and workspaces | [Projects and dependency scopes](https://github.com/Onely7/uv_torch_compass/blob/main/docs/projects-and-scopes.md) |
| Consume text and JSON results | [Reports and automation](https://github.com/Onely7/uv_torch_compass/blob/main/docs/reports.md) |
| Recover files or diagnose a failure | [Recovery and troubleshooting](https://github.com/Onely7/uv_torch_compass/blob/main/docs/recovery.md) |
| Test, build, and prepare artifacts | [Development](https://github.com/Onely7/uv_torch_compass/blob/main/docs/development.md) |

See the [documentation index](https://github.com/Onely7/uv_torch_compass/blob/main/docs/README.md) for the complete map.
