feat: add pinned CUDA manylinux image aliases

[henryiii]

Updated the docs naming issue in #2900 separately.

I left the minor versions in, but an alternative would be to drop them, and always track the latest minor version (manylinux_2_28_cuda13 instead of manylinux_2_28_cuda13_1).

🤖 AI text below 🤖

Summary

Follow-up to #2896, which documented building CUDA wheels using the manylinux_cuda containers. This adds pinned aliases for those images so users can pass a short name to the manylinux-*-image options, exactly like the existing manylinux_2_28 alias, instead of a full registry URL:

CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28_cuda13_1
CIBW_MANYLINUX_AARCH64_IMAGE: manylinux_2_28_cuda13_1

New aliases (for x86_64 and aarch64 only — the only arches these images exist for):

• manylinux_2_28_cuda12_9, manylinux_2_28_cuda13_1
• manylinux_2_34_cuda12_9, manylinux_2_34_cuda13_1

No options.py changes were needed — alias resolution is entirely cfg-driven (pinned_images.get(value, value)).

Details

• bin/update_docker.py — adds a CudaImage class and a digest-pinning branch. Unlike the PyPA images (which carry dated tags), the CUDA repos publish only a latest tag and each arch is a separate repository, so they are pinned by digest (@sha256:…) per architecture. nox -s update_pins now keeps these current.
• cibuildwheel/resources/pinned_docker_images.cfg — adds the 8 CUDA entries (4 aliases × 2 arches), pinned to current digests. Generated by the updated script; the existing PyPA pins were left untouched so this PR doesn't sweep in unrelated pin-date bumps.
• docs/faq.md — documents the new aliases (the recommended, pinned approach) while still showing the underlying quay.io/manylinux_cuda/… repo path so users can pin other combinations or use :latest directly.
• unit_test/options_test.py — parametrized test asserting each CUDA alias resolves to a digest-pinned manylinux_cuda image on supported arches and is absent on others.

Note

The image names in #2896's docs (manylinux2_28_…) didn't match the actual public quay repos, which are named manylinux_2_28_… (underscore, matching the PyPA convention). I confirmed the correct names against the live registry and the docs are corrected here.

No CUDA build/integration test is included — that's a larger task for another time.

Verification

• prek -a clean (ruff + mypy)
• pytest unit_test/options_test.py — existing + 8 new tests pass

[agriyakhetarpal]

LGTM once CI passes!

[mayeut]

Looking at the quay.io repos, those images seem to be using a moving tag. If I'm not mistaken, cibuildwheel will fail to use those images as soon as a new latest image is published.

It also might be nice to link to the GitHub repo https://github.com/gpu-ci-demo/manylinux-cuda-container in addition to the quay.io repo in the docs.
I was made aware of similar images a few weeks ago through an issue opened in https://github.com/pypa/manylinux: https://github.com/ameli/manylinux-cuda

[henryiii]

🤖 AI text below 🤖

The manylinux_cuda repositories now publish dated tags (e.g. 2026.06.08-1) alongside latest, so I switched the CUDA aliases from digest pinning to dated-tag pinning — same scheme the PyPA images already use. bin/update_docker.py now resolves the dated tag whose manifest matches latest for each per-arch repository.

I also added a link to the source project (gpu-ci-demo/manylinux-cuda-container) from the CudaImage docstring and the CUDA FAQ section.

• cibuildwheel/resources/pinned_docker_images.cfg: CUDA aliases now ...:2026.06.08-1 instead of @sha256:... (PyPA pins left untouched).
• unit_test/options_test.py: test_cuda_pinned_images now asserts the repository:tag form.

pytest unit_test -k cuda → 8 passed; prek -a clean.

[joerick]

A few questions-

• I'm not sure what the point of a pin is if we aren't testing anything on our side? I suppose it does give some form of build repeatability w.r.t. a given cibuildwheel version. Is there an advantage for a user aside from a slightly neater config?
• Adding the pin does imply some form of endorsement/support. Can we be confident this project will continue indefinitely, and maintain some forward-compatibility?

[henryiii]

For the first point, yes, simpler config and pinned versions based on the cibuildwheel version.

Second point, no idea - @hcho3 maybe can comment. There is a lot of support in general going forward for expanding CUDA in wheels with variants.

I'd not want to go too far here until we see the final form of variants and if they are getting accepted. I think I have a plan for them. I think this is fine as far as that's concerned, though (any variant support shouldn't interfere with image aliases).

I'm perfectly fine waiting and seeing if these get used first, etc.

[joerick]

Hmm. Yes the variant work also intersects here. That might end up as some matrix axes that cibuildwheel operates with.

We already referenced these images in the documentation, right? Yes, I see them in the FAQ. I think I'd rather wait and see how usage looks like. And if we were adding shorthand pins for these images, I'd like to include some kind of integration test to reduce the chances that we pin a bad/incompatible version

[hcho3]

Can we be confident this project will continue indefinitely

Yes, my employer (NVIDIA) is interested in making it easy for developers to build CUDA wheels. My org is planning to support manylinux-cuda for the foreseeable future.

I think I'd rather wait and see how usage looks like

What would be the metrics here? Open source projects using cibuildwheel to build CUDA wheels?

[hcho3]

On a second thought, it would be better for everyone if we waited a little before merging the image aliases. Let's try to gain adoption in the wild (multiple open-source projects). This is because the image aliases involve pinning image versions, and we should wait until the images are battle tested in the wild.

outdated

#2901 (comment)