Skip to content

How to Install CUDA PyTorch Wheels Without a GPU

by Tim Hopper · Markdown
uv Scientific Python verified with uv 0.13

A GPU-less build host can install CUDA PyTorch wheels. Select the execution host’s backend explicitly: uv’s --torch-backend=auto probes the build host and selects CPU wheels when it detects no accelerator.

Prerequisites

  • uv installed on a Linux or Windows build host
  • A target Python version and CUDA backend with published PyTorch wheels
  • A compatible NVIDIA driver and supported GPU on the execution host

Install the target build explicitly

For a CUDA 12.8 deployment, create a Python 3.12 environment and install from that backend:

uv venv --python 3.12
uv pip install --python .venv torch --torch-backend=cu128
uv run --no-project python -c "import torch; print(torch.__version__, torch.version.cuda)"

The output includes +cu128 and 12.8. Run these commands outside an existing uv project. uv run executes the command inside the virtual environment, ensuring dependencies are installed first; --no-project prevents a surrounding project’s configuration from changing the environment.

In a Linux Docker build stage with uv and Python already installed:

RUN uv pip install --system torch --torch-backend=cu128
RUN python -c "import torch; assert torch.version.cuda == '12.8'"

Neither step needs a GPU. The import checks that runtime libraries load; it does not establish GPU functionality. torch.cuda.is_available() is normally false during a GPU-less build, including with a correct CUDA wheel.

Keep project installs on the same index

--torch-backend applies to the uv pip and uv tool interfaces, not uv add, uv lock, uv sync, or uv run. For a project, use the explicit index configuration and copy its pyproject.toml and uv.lock into the image before uv sync --locked.

When resolving on macOS for Linux, create requirements.in containing torch, then name both the target platform and Python version:

uv pip compile requirements.in --torch-backend=cu128 --python-platform linux --python-version 3.12

The resolution contains a CUDA torch build; resolution alone does not import or execute it.

UV_CUDA_DRIVER_VERSION and UV_AMD_GPU_ARCHITECTURE override the inputs to auto detection. They do not install drivers, expose devices, or validate hardware support. Prefer an explicit backend for image builds so a driver mapping change cannot silently change the artifact.

Verify the deployed image on a GPU

After starting the image with GPU access enabled, run the PyTorch accelerator check. It must assert device availability and complete a CUDA matrix multiplication.

A failure at runtime can mean a missing/old driver, missing container GPU passthrough, an unsupported GPU architecture, or incompatible libraries. Installing a CUDA toolkit inside the image does not replace the host driver. See NVIDIA’s driver compatibility guidance; JIT-generated PTX can require a newer driver than the minimum for precompiled CUDA code.

Last updated on