ci: configure the CUDA manylinux images in pyproject.toml

Hardcode the CUDA manylinux images in [tool.cibuildwheel] so the wheels
workflow no longer sets them. Document overriding them via the
CIBW_MANYLINUX_*_IMAGE environment variables to target a different (e.g.
older) CUDA version in the README.

Assisted-by: ClaudeCode:claude-opus-4.8

Author: henryiii

.github/workflows/wheels.yml

@@ -48,23 +48,13 @@ jobs:
           - arch: aarch64
             runner: ubuntu-24.04-arm
 
-    # The CUDA Toolkit ships inside these custom manylinux images, so nvcc is
-    # available during the build (see https://github.com/pypa/cibuildwheel/pull/2896).
-    # Bump the CUDA version here; to publish wheels for several CUDA versions you
-    # would also need distinct local version labels (e.g. 0.0.1+cu131).
-    env:
-      CUDA_VERSION: "13_1"
-      MANYLINUX_BASE: manylinux_2_28
-
     steps:
     - uses: actions/checkout@v6
 
+    # The CUDA manylinux images (with nvcc) are configured in pyproject.toml.
+    # Override them with CIBW_MANYLINUX_*_IMAGE here to target a different CUDA
+    # version (see the README).
     - uses: pypa/cibuildwheel@v3.4
-      env:
-        CIBW_MANYLINUX_X86_64_IMAGE: >-
-          quay.io/manylinux_cuda/${{ env.MANYLINUX_BASE }}_x86_64_cuda${{ env.CUDA_VERSION }}:latest
-        CIBW_MANYLINUX_AARCH64_IMAGE: >-
-          quay.io/manylinux_cuda/${{ env.MANYLINUX_BASE }}_aarch64_cuda${{ env.CUDA_VERSION }}:latest
 
     - name: Verify clean directory
       run: git diff --exit-code

README.md

@@ -85,17 +85,31 @@ assert (cpu == gpu).all()  # identical results, very different runtimes
 
 ## Building CUDA wheels
 
-The `Wheels` workflow builds CUDA-enabled Linux wheels with [cibuildwheel][] by
-pointing it at the custom manylinux images that ship the CUDA Toolkit (see
-[pypa/cibuildwheel#2896][cibw-cuda]):
-
-```yaml
-- uses: pypa/cibuildwheel@v3.4
-  env:
-    CIBW_MANYLINUX_X86_64_IMAGE: quay.io/manylinux_cuda/manylinux_2_28_x86_64_cuda13_1:latest
-    CIBW_MANYLINUX_AARCH64_IMAGE: quay.io/manylinux_cuda/manylinux_2_28_aarch64_cuda13_1:latest
+The `Wheels` workflow builds CUDA-enabled Linux wheels with [cibuildwheel][],
+using the custom manylinux images that ship the CUDA Toolkit (see
+[pypa/cibuildwheel#2896][cibw-cuda]). The images are configured in
+`pyproject.toml`:
+
+```toml
+[tool.cibuildwheel]
+manylinux-x86_64-image = "quay.io/manylinux_cuda/manylinux_2_28_x86_64_cuda13_1:latest"
+manylinux-aarch64-image = "quay.io/manylinux_cuda/manylinux_2_28_aarch64_cuda13_1:latest"
 ```
 
+To target a different CUDA version (e.g. an older `cuda12_9` to support older
+drivers) without editing `pyproject.toml`, override the images with environment
+variables when running cibuildwheel:
+
+```bash
+export CIBW_MANYLINUX_X86_64_IMAGE=quay.io/manylinux_cuda/manylinux_2_28_x86_64_cuda12_9:latest
+export CIBW_MANYLINUX_AARCH64_IMAGE=quay.io/manylinux_cuda/manylinux_2_28_aarch64_cuda12_9:latest
+cibuildwheel
+```
+
+The available images are listed in [the cibuildwheel docs][cibw-cuda]; the
+`manylinux_2_28`/`manylinux_2_34` base and `cuda12_9`/`cuda13_1` version can be
+mixed and matched.
+
 The CUDA runtime is linked statically (`CUDA_RUNTIME_LIBRARY Static`), so the
 resulting wheels do not depend on `libcudart`. GitHub-hosted runners have no
 GPU, so the wheels are compiled and imported, but the kernels themselves only

pyproject.toml

@@ -52,9 +52,11 @@ testpaths = ["tests"]
 [tool.cibuildwheel]
 build-frontend = "build[uv]"
 # Building requires the CUDA Toolkit, which is only present in the custom
-# manylinux CUDA images (see the wheels workflow). Restrict to CPython on
-# manylinux; musllinux and PyPy have no matching CUDA image.
-build = "cp3*"
+# manylinux CUDA images (https://github.com/pypa/cibuildwheel/pull/2896).
+# Override these to target a different CUDA version
+manylinux-x86_64-image = "quay.io/manylinux_cuda/manylinux_2_28_x86_64_cuda13_1:latest"
+manylinux-aarch64-image = "quay.io/manylinux_cuda/manylinux_2_28_aarch64_cuda13_1:latest"
+# Restrict to CPython on manylinux; musllinux and PyPy have no matching CUDA image.
 skip = "*-musllinux*"
 test-command = "python -m pytest tests"
 test-sources = ["pyproject.toml", "tests"]