From 068c33cec4a584bc0fb93483a76862c74842f00b Mon Sep 17 00:00:00 2001
From: Hyunsu Cho <phcho@nvidia.com>
Date: Fri, 5 Jun 2026 16:00:54 -0700
Subject: [PATCH 1/2] Add documentation for building CUDA wheels

---
 docs/faq.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/docs/faq.md b/docs/faq.md
index cd8c024c7..04f8cf17e 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -282,6 +282,59 @@ skip = ["*-musllinux_i686"]
 
 Also see [maturin-action](https://github.com/PyO3/maturin-action) which is optimized for Rust wheels, builds the non-Python Rust modules once, and can cross-compile (and can build 32-bit musl, for example).
 
+### Linux: Building wheels with CUDA
+
+On Linux, you can build binary wheels with CUDA to take advantage of NVIDIA GPUs for hardware acceleration.
+Specify the custom Docker containers with CUDA Toolkit as follows:
+
+```yaml
+CIBW_MANYLINUX_X86_64_IMAGE: >-
+  quay.io/manylinux_cuda/manylinux2_28_x86_64_cuda13_1:latest
+CIBW_MANYLINUX_AARCH64_IMAGE: >-
+  quay.io/manylinux_cuda/manylinux2_28_aarch64_cuda13_1:latest
+```
+Currently, we support the following CUDA manylinux containers:
+
+* `quay.io/manylinux_cuda/manylinux2_28_x86_64_cuda12_9:latest`
+* `quay.io/manylinux_cuda/manylinux2_28_aarch64_cuda12_9:latest`
+* `quay.io/manylinux_cuda/manylinux2_28_x86_64_cuda13_1:latest`
+* `quay.io/manylinux_cuda/manylinux2_28_aarch64_cuda13_1:latest`
+* `quay.io/manylinux_cuda/manylinux2_34_x86_64_cuda12_9:latest`
+* `quay.io/manylinux_cuda/manylinux2_34_aarch64_cuda12_9:latest`
+* `quay.io/manylinux_cuda/manylinux2_34_x86_64_cuda13_1:latest`
+* `quay.io/manylinux_cuda/manylinux2_34_aarch64_cuda13_1:latest`
+
+A typical GitHub Actions workflow will look like this:
+
+```yaml
+jobs:
+  build-wheels:
+    name: Build wheels
+    runs-on: ${{ matrix.target.runner }}
+    strategy:
+      matrix:
+        manylinux-base: [manylinux_2_28, manylinux_2_34]
+        cuda-version: [12_9, 13_1]
+        target:
+          - arch: x86_64
+            runner: ubuntu-24.04
+          - arch: aarch64
+            runner: ubuntu-24.04-arm
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v3
+        env:
+          CIBW_MANYLINUX_X86_64_IMAGE: >-
+            quay.io/manylinux_cuda/${{ matrix.manylinux-base }}_x86_64_cuda${{ matrix.cuda-version }}:latest
+          CIBW_MANYLINUX_AARCH64_IMAGE: >-
+            quay.io/manylinux_cuda/${{ matrix.manylinux-base }}_aarch64_cuda${{ matrix.cuda-version }}:latest
+          CIBW_BUILD: cp312-manylinux_${{ matrix.target.arch }}
+```
+
 ### macOS: 'No module named XYZ' errors after running cibuildwheel
 
 `cibuildwheel` on Mac installs the distributions from Python.org system-wide during its operation. This is necessary, but it can cause some confusing errors after cibuildwheel has finished.

From 2dc3d44ae6b5208c045484097aaf9f2dff7ee75e Mon Sep 17 00:00:00 2001
From: Hyunsu Cho <phcho@nvidia.com>
Date: Fri, 5 Jun 2026 16:04:25 -0700
Subject: [PATCH 2/2] Move to Tips section

---
 docs/faq.md | 107 ++++++++++++++++++++++++++--------------------------
 1 file changed, 54 insertions(+), 53 deletions(-)

diff --git a/docs/faq.md b/docs/faq.md
index 04f8cf17e..8a1181eaa 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -221,6 +221,60 @@ Your build might need some compiler flags to be set through environment variable
 Consider incorporating these into your package, for example, in `setup.py` using [`extra_compile_args` or
 `extra_link_args`](https://setuptools.pypa.io/en/latest/userguide/ext_modules.html#setuptools.Extension).
 
+### Building wheels with CUDA on Linux
+
+On Linux, you can build binary wheels with CUDA to take advantage of NVIDIA GPUs for hardware acceleration.
+Specify the custom Docker containers with CUDA Toolkit as follows:
+
+```yaml
+CIBW_MANYLINUX_X86_64_IMAGE: >-
+  quay.io/manylinux_cuda/manylinux2_28_x86_64_cuda13_1:latest
+CIBW_MANYLINUX_AARCH64_IMAGE: >-
+  quay.io/manylinux_cuda/manylinux2_28_aarch64_cuda13_1:latest
+```
+Currently, we support the following CUDA manylinux containers:
+
+* `quay.io/manylinux_cuda/manylinux2_28_x86_64_cuda12_9:latest`
+* `quay.io/manylinux_cuda/manylinux2_28_aarch64_cuda12_9:latest`
+* `quay.io/manylinux_cuda/manylinux2_28_x86_64_cuda13_1:latest`
+* `quay.io/manylinux_cuda/manylinux2_28_aarch64_cuda13_1:latest`
+* `quay.io/manylinux_cuda/manylinux2_34_x86_64_cuda12_9:latest`
+* `quay.io/manylinux_cuda/manylinux2_34_aarch64_cuda12_9:latest`
+* `quay.io/manylinux_cuda/manylinux2_34_x86_64_cuda13_1:latest`
+* `quay.io/manylinux_cuda/manylinux2_34_aarch64_cuda13_1:latest`
+
+A typical GitHub Actions workflow will look like this:
+
+```yaml
+jobs:
+  build-wheels:
+    name: Build wheels
+    runs-on: ${{ matrix.target.runner }}
+    strategy:
+      matrix:
+        manylinux-base: [manylinux_2_28, manylinux_2_34]
+        cuda-version: [12_9, 13_1]
+        target:
+          - arch: x86_64
+            runner: ubuntu-24.04
+          - arch: aarch64
+            runner: ubuntu-24.04-arm
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v3
+        env:
+          CIBW_MANYLINUX_X86_64_IMAGE: >-
+            quay.io/manylinux_cuda/${{ matrix.manylinux-base }}_x86_64_cuda${{ matrix.cuda-version }}:latest
+          CIBW_MANYLINUX_AARCH64_IMAGE: >-
+            quay.io/manylinux_cuda/${{ matrix.manylinux-base }}_aarch64_cuda${{ matrix.cuda-version }}:latest
+          CIBW_BUILD: cp312-manylinux_${{ matrix.target.arch }}
+```
+
+
 ## Troubleshooting
 
 If your wheel didn't compile, you might have a mistake in your config.
@@ -282,59 +336,6 @@ skip = ["*-musllinux_i686"]
 
 Also see [maturin-action](https://github.com/PyO3/maturin-action) which is optimized for Rust wheels, builds the non-Python Rust modules once, and can cross-compile (and can build 32-bit musl, for example).
 
-### Linux: Building wheels with CUDA
-
-On Linux, you can build binary wheels with CUDA to take advantage of NVIDIA GPUs for hardware acceleration.
-Specify the custom Docker containers with CUDA Toolkit as follows:
-
-```yaml
-CIBW_MANYLINUX_X86_64_IMAGE: >-
-  quay.io/manylinux_cuda/manylinux2_28_x86_64_cuda13_1:latest
-CIBW_MANYLINUX_AARCH64_IMAGE: >-
-  quay.io/manylinux_cuda/manylinux2_28_aarch64_cuda13_1:latest
-```
-Currently, we support the following CUDA manylinux containers:
-
-* `quay.io/manylinux_cuda/manylinux2_28_x86_64_cuda12_9:latest`
-* `quay.io/manylinux_cuda/manylinux2_28_aarch64_cuda12_9:latest`
-* `quay.io/manylinux_cuda/manylinux2_28_x86_64_cuda13_1:latest`
-* `quay.io/manylinux_cuda/manylinux2_28_aarch64_cuda13_1:latest`
-* `quay.io/manylinux_cuda/manylinux2_34_x86_64_cuda12_9:latest`
-* `quay.io/manylinux_cuda/manylinux2_34_aarch64_cuda12_9:latest`
-* `quay.io/manylinux_cuda/manylinux2_34_x86_64_cuda13_1:latest`
-* `quay.io/manylinux_cuda/manylinux2_34_aarch64_cuda13_1:latest`
-
-A typical GitHub Actions workflow will look like this:
-
-```yaml
-jobs:
-  build-wheels:
-    name: Build wheels
-    runs-on: ${{ matrix.target.runner }}
-    strategy:
-      matrix:
-        manylinux-base: [manylinux_2_28, manylinux_2_34]
-        cuda-version: [12_9, 13_1]
-        target:
-          - arch: x86_64
-            runner: ubuntu-24.04
-          - arch: aarch64
-            runner: ubuntu-24.04-arm
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-
-      - name: Build wheels
-        uses: pypa/cibuildwheel@v3
-        env:
-          CIBW_MANYLINUX_X86_64_IMAGE: >-
-            quay.io/manylinux_cuda/${{ matrix.manylinux-base }}_x86_64_cuda${{ matrix.cuda-version }}:latest
-          CIBW_MANYLINUX_AARCH64_IMAGE: >-
-            quay.io/manylinux_cuda/${{ matrix.manylinux-base }}_aarch64_cuda${{ matrix.cuda-version }}:latest
-          CIBW_BUILD: cp312-manylinux_${{ matrix.target.arch }}
-```
-
 ### macOS: 'No module named XYZ' errors after running cibuildwheel
 
 `cibuildwheel` on Mac installs the distributions from Python.org system-wide during its operation. This is necessary, but it can cause some confusing errors after cibuildwheel has finished.