Why does --torch-backend=auto install CPU wheels in a Docker build?

`auto` inspects the machine running the command, not the machine that will run the image. A build container has no GPU and no NVIDIA driver, so uv finds nothing to detect and falls back to the CPU-only index. The resolution succeeds, and the CPU wheels only surface as a problem when the image reaches a GPU host.

How do you tell uv which CUDA driver to assume?

Set `UV_CUDA_DRIVER_VERSION` to the driver version of the target machine, for example `UV_CUDA_DRIVER_VERSION=550.144.03 uv pip install torch --torch-backend=auto`. uv treats the value as if it had detected that driver on the local system and picks the matching PyTorch index. The variable takes precedence over real hardware, so it also works on a machine that does have a GPU.

Does UV_CUDA_DRIVER_VERSION work with uv sync or uv lock?

No. The variable feeds `--torch-backend`, which is respected only by `uv pip install`, `uv pip compile`, `uv pip sync`, `uv tool run`, and `uv tool install`. Project commands such as `uv add`, `uv sync`, and `uv lock` ignore it. For project workflows, route torch through an explicit index with `[[tool.uv.index]]` and `[tool.uv.sources]` instead.

Which driver version should you use?

Use the value `nvidia-smi --query-gpu=driver_version --format=csv,noheader` reports on the target machine. uv compares it against a floor table rather than matching exactly, so any driver at or above 580 selects CUDA 13.2, and anything from 525.60.13 up to 580 selects CUDA 12.9.

Can you force AMD ROCm wheels on a machine with no AMD GPU?

Set `UV_AMD_GPU_ARCHITECTURE` to the target architecture, such as `gfx1100`. uv then resolves ROCm builds of torch. Both overrides are checked before any hardware probe, so setting the AMD variable on an NVIDIA machine still produces ROCm wheels.

How to Install CUDA PyTorch Wheels Without a GPU

by Tim Hopper · Markdown

uv Scientific Python verified with uv 0.12

PyTorch publishes CPU, CUDA, and ROCm wheels on separate indexes, and uv’s --torch-backend=auto picks between them by inspecting the local machine for a GPU. On a CI runner or Docker build stage there is no GPU to find, so auto quietly selects CPU wheels and the build succeeds with the wrong artifact.

Two environment variables let you state what the target machine has instead of what the build machine has.

Prerequisites

uv installed, with --torch-backend available on the uv pip interface
The CUDA driver version of the machine that will run the code

Confirm the build machine fell back to CPU

Resolve torch on the build machine and read the local version suffix:

$ echo "torch" > requirements.in
$ uv pip compile requirements.in --torch-backend=auto
torch==2.13.0+cpu

The +cpu suffix is the symptom. uv found no driver and fell through to the CPU index.

Declare the driver the target machine runs

Set UV_CUDA_DRIVER_VERSION to the driver version reported by nvidia-smi --query-gpu=driver_version --format=csv,noheader on the target host:

$ UV_CUDA_DRIVER_VERSION=550.144.03 uv pip compile requirements.in --torch-backend=auto
torch==2.13.0+cu129

uv now behaves as though it had detected that driver locally. The same variable works for an install:

$ UV_CUDA_DRIVER_VERSION=550.144.03 uv pip install torch --torch-backend=auto

In a Dockerfile, set it for the build stage that installs dependencies:

ENV UV_CUDA_DRIVER_VERSION=550.144.03
RUN uv pip install --system torch --torch-backend=auto

Both overrides are read before uv probes the hardware, so they win even on a machine that has a GPU. A stale value will quietly override a correct autodetection.

Important

--torch-backend is respected by uv pip install, uv pip compile, uv pip sync, uv tool run, and uv tool install. Project commands ignore it, so uv add, uv sync, and uv lock see no effect from either variable. To pin a backend in a project, route torch through an explicit index as described in How to Install PyTorch with uv.

Name the target platform when resolving from macOS

uv maps drivers to CUDA indexes only for Linux and Windows targets. Resolving from macOS without naming a target platform drops the override and returns a plain PyPI build:

$ UV_CUDA_DRIVER_VERSION=550.144.03 uv pip compile requirements.in --torch-backend=auto
torch==2.13.0

Add --python-platform so the resolution targets the machine that will run the wheels:

$ UV_CUDA_DRIVER_VERSION=550.144.03 uv pip compile requirements.in \
    --torch-backend=auto --python-platform linux
torch==2.13.0+cu129

Linux build agents already resolve for Linux, so this step only applies when the resolve runs on macOS.

Pick a driver value

uv compares the driver against a floor for each CUDA version, then takes the highest backend the driver satisfies. Exact values do not matter, only which floor they clear:

Driver version	Highest CUDA backend selected
580 and above	`cu132`
525.60.13 up to 580	`cu129`
450.80.2 up to 525.60.13	`cu118`

An older driver constrains the torch version too, because recent torch releases stopped publishing CUDA 11.8 wheels:

$ UV_CUDA_DRIVER_VERSION=470.199.02 uv pip compile requirements.in \
    --torch-backend=auto --python-platform linux --python-version 3.12
torch==2.7.1+cu118

Name the target Python version alongside the driver. The CUDA 11.8 index carries no build for Python 3.14, so asking for both drops the resolution back to CPU wheels without reporting a conflict:

$ UV_CUDA_DRIVER_VERSION=470.199.02 uv pip compile requirements.in \
    --torch-backend=auto --python-platform linux --python-version 3.14
torch==2.13.0+cpu

A +cpu suffix after setting the override means the requested combination of driver, platform, and Python version has no CUDA build, not that the override was ignored.

An unparseable value fails the command rather than falling back to autodetection, so a typo surfaces immediately:

$ UV_CUDA_DRIVER_VERSION=not-a-version uv pip compile requirements.in --torch-backend=auto
error: Failed to parse environment variable `UV_CUDA_DRIVER_VERSION` with invalid value `not-a-version`: expected version to start with a number, but no leading ASCII digits were found

Target an AMD GPU instead

UV_AMD_GPU_ARCHITECTURE does the same job for ROCm. Set it to the architecture of the target card, such as gfx1100 for RDNA 3:

$ UV_AMD_GPU_ARCHITECTURE=gfx1100 uv pip compile requirements.in \
    --torch-backend=auto --python-platform linux
torch==2.13.0+rocm7.2

uv checks the CUDA override first, so set only one of the two.

Learn More

Using uv with PyTorch documents --torch-backend and the index layout it selects from
Why Installing GPU Python Packages Is So Complicated explains why the wheels are split across indexes at all
How to Use uv in a Dockerfile covers the surrounding build-stage and caching setup
What Are Wheel Variants? describes the proposed standard that would make hardware detection part of package metadata
light-the-torch is the pip wrapper whose driver-to-CUDA mapping uv’s implementation is based on

Last updated on August 8, 2026

How to Install bitsandbytes How to Install DeepSpeed

Please submit corrections and feedback...