uv/docs/reference
Charlie Marsh 5173b59b50
Automatically infer the PyTorch index via --torch-backend=auto (#12070)
## Summary

This is a prototype that I'm considering shipping under `--preview`,
based on [`light-the-torch`](https://github.com/pmeier/light-the-torch).

`light-the-torch` patches pip to pull PyTorch packages from the PyTorch
indexes automatically. And, in particular, `light-the-torch` will query
the installed CUDA drivers to determine which indexes are compatible
with your system.

This PR implements equivalent behavior under `--torch-backend auto`,
though you can also set `--torch-backend cpu`, etc. for convenience.
When enabled, the registry client will fetch from the appropriate
PyTorch index when it sees a package from the PyTorch ecosystem (and
ignore any other configured indexes, _unless_ the package is explicitly
pinned to a different index).

Right now, this is only implemented in the `uv pip` CLI, since it
doesn't quite fit into the lockfile APIs given that it relies on feature
detection on the currently-running machine.

## Test Plan

On macOS, you can test this with (e.g.):

```shell
UV_TORCH_BACKEND=auto UV_CUDA_DRIVER_VERSION=450.80.2 cargo run \
  pip install torch --python-platform linux --python-version 3.12
```

On a GPU-enabled EC2 machine:

```shell
ubuntu@ip-172-31-47-149:~/uv$ UV_TORCH_BACKEND=auto cargo run pip install torch -v
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/uv pip install torch -v`
DEBUG uv 0.6.6 (e95ca063b 2025-03-14)
DEBUG Searching for default Python interpreter in virtual environments
DEBUG Found `cpython-3.13.0-linux-x86_64-gnu` at `/home/ubuntu/uv/.venv/bin/python3` (virtual environment)
DEBUG Using Python 3.13.0 environment at: .venv
DEBUG Acquired lock for `.venv`
DEBUG At least one requirement is not satisfied: torch
warning: The `--torch-backend` setting is experimental and may change without warning. Pass `--preview` to disable this warning.
DEBUG Detected CUDA driver version from `/sys/module/nvidia/version`: 550.144.3
...
```
2025-03-19 14:37:08 +00:00
..
policies Update versioning policy (#11666) 2025-03-07 11:12:07 -06:00
troubleshooting Fix 2 typos in MRE docs (#12198) 2025-03-16 09:26:33 -05:00
benchmarks.md Add link to benchmarks in documentation (#6257) 2024-08-20 12:54:46 -04:00
cli.md Automatically infer the PyTorch index via --torch-backend=auto (#12070) 2025-03-19 14:37:08 +00:00
index.md Add policies reference section and license document (#9367) 2024-12-03 10:56:32 -06:00
resolver-internals.md Update resolver internals docs (#11098) 2025-02-04 13:06:27 +00:00
settings.md Automatically infer the PyTorch index via --torch-backend=auto (#12070) 2025-03-19 14:37:08 +00:00