# Fedora install CUDA Toolkit Guida

官方說明文件

https://docs.nvidia.com/cuda/index.html

https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html

好的，這一切顯得有些麻煩
首先，你要使用 CUDA，你需要使用 CUDA Toolkit，要使用者 CUDA Toolkit，你需要安裝 Driver，其實 NV 有提供整包的，但一般會分開裝
所以這邊會單獨說明如何安裝 CUDA Toolkit

有一些需要注意的狀況

以下依序說明

另外，本文將以 Fedora 42 為預設環境

最後更新 : 2025/11/03

## 系統相關
### 系統需求

要在系統上使用 NVIDIA CUDA，需具備以下項目：

- **CUDA 相容 GPU**
- **受支援的 Linux 版本**，且安裝 **gcc 編譯器與工具鏈**
- **CUDA Toolkit**

請注意，在原文中有以下內容
- 可由一般使用者執行的指令，行首以 `$` 表示。
- 需要管理者（root）權限的指令，行首以 `#` 表示。

而在本文中，為求方便，會將 `#` 直接替換為 `sudo`，`$` 則不另外標示

CUDA 開發環境與主機端（host）開發環境緊密整合（主機端編譯器與 C 執行期函式庫），**僅支援已針對該 CUDA 版本完成相容性驗證的發行版**。

下表為 **CUDA 13.0 Update 2** 所支援的 Linux 發行版。

> **注意**：表格中「Codename」與括號中的架構（architecture），在本文中以 `<distro>` 與 `<arch>` 代表。

| Distribution | OS Version | Kernel¹ | Default GCC | GLIBC |
| :--- | :--- | :--- | :--- | :--- |
| **x86_64** | | | | |
| RHEL 10.x | (x = 0) | 6.12.0-55 | 14.2.1 | 2.39 |
| RHEL 9.x | (x ≤ 6) | 5.14.0-570.12.1 | 11.5.0 | 2.34 |
| RHEL 8.x | (x ≤ 10) | 4.18.0-553 | 8.5.0 | 2.28 |
| Rocky Linux 10.x | (x = 0) | 6.12.0-55.21.1 | 14.2.1 | 2.39 |
| Rocky Linux 9.x | (x ≤ 6) | 5.14.0-570.19.1 | 11.5.0 | 2.34 |
| Rocky Linux 8.x | (x ≤ 10) | 4.18.0-553 | 8.5.0 | 2.28 |
| Oracle Linux | 9 | 5.14.0-427 | 11.4.1 | 2.34 |
| Oracle Linux | 8 | 4.18.0-553 | 8.5.0 | 2.28 |
| SUSE SLES 15.x | (x = 6/7) | 6.4.0-150600.21 | 7.5.0 | 2.38 |
| Ubuntu 24.04.x LTS | (x ≤ 3) | 6.14.0-29 | 13.3.0 | 2.39 |
| Ubuntu 22.04.x LTS | (x ≤ 5) | 6.5.0-45 | 12.3.0 | 2.35 |
| Debian 12.x | (x ≤ 12) | 6.1.148-1 | 12.2.0 | 2.36 |
| OpenSUSE Leap 15.x | (x = 6) | 6.4.0-150600.21 | 7.5.0 | 2.38 |
| Fedora | 42 | 6.14.0-63 | 15.1.1 | 2.41 |
| KylinOS | V10 SP3 2403 | 4.19.90-89.11.v2401 | 10.x | 2.28 |
| Amazon Linux 2023 | AL2023 | 6.1.82-99.168 | 11.4.1 | 2.34 |
| MSFT Azure Linux | 3.0 | 6.6.64.2-9.azl3 | 11.2.0 | 2.38-8 |
| MSFT Azure Linux | 2.0 | 5.15.158.2-1 | 13.2.0 | 2.35 |
| **Generic amd64 systems (sbsa)** | | | | |
| RHEL 10.x | (x = 0) | 6.12.0-55.7.1.el10_0 | 14.2.1 | 2.39 |
| RHEL 9.x | (x ≤ 6) | 5.14.0-570.17.1 | 11.5.0 | 2.35 -2-63 |
| RHEL 8.x | (x ≤ 10) | 4.18.0-553 | 8.5.0 | 2.28 |
| Ubuntu 22.04.x LTS | (x ≤ 5) | 6.5.0-1019 | 11.4.0 | 2.35 |
| Ubuntu 24.04.x LTS | (x ≤ 3) | 6.8.0-83-generic | 13.3.0 | 2.39 |
| SUSE SLES 15.x | (x = 6/7) | 6.4.0-150700.51 | 7.5.0 | 2.38 |
| KylinOS V10 SP3 | V10 SP3 2403 | 4.19.90-52 | 7.3.0 | 2.28 |
| **GRACE only arm64 systems (sbsa)** | | | | |
| Amazon Linux 2023 | AL2023 | 6.12.16-18 | 11.4.1 | 2.34 |
| MSFT Azure Linux | 3.0 | 6.6.64.2-9.azl3 | 13.2.0 | 2.38-8 |
| Ubuntu 22.04.x LTS | (x ≤ 5) | 6.8.0-1030-nvidia-64k | 11.4.0 | 2.35 |
| Ubuntu 24.04.x LTS | (x ≤ 3) | 6.8.0-1031-nvidia-64k | 13.2.0 | 2.39 |
| RHEL 10.x | (x = 0) | 6.12.0-55.9.1.el10_0 | 14.2.1 | 2.39 |
| RHEL 9.x | (x = 4/5/6) | 5.14.0-570.28.1.el9\_6.aarch64+64k | 11.5.0 | 2.34 |
| SUSE SLES 15.x | (x = 6/7) | 6.4.0-150700.51 | 7.5.0 | 2.38 |
| **arm64 sbsa Jetson (dGPU + iGPU with OpenRM)** | | | | |
| Ubuntu 24.04.x LTS Rel37 (JP7.x) | native | 6.8.12-tegra | 13.3.0 | 2.39 |
| Ubuntu 24.04.x LTS Rel37 (JP7.x) | cross | 6.11.0-28-generic | 13.3.0 | 2.39 |

### 作業系統支援政策（OS Support Policy）

支援各作業系統至其官方定義的 **EOSS/EOL** 為止。請參考各發行版的支援生命週期以掌握時程，並規劃升級。

### 主機端編譯器支援政策（Host Compiler Support Policy）

為了編譯 CUDA 原始碼中的 CPU "host" 端程式，CUDA 編譯器 NVCC 需要安裝相容的主機端編譯器。
NVCC 會檢查主機編譯器主要版本（major）；
較新的 minor 版本通常可用，但 major 超出範圍則不支援。

### 支援的編譯器（Supported Compilers）

| Distribution | GCC | Clang | NVHPC | XLC | ArmC/C++ |
| :--- | :--- | :--- | :--- | :--- | :--- |
| x86_64 | 6.x – 15.x | 7.x – 20.x | 24.9–25.5 | No | No |
| Arm64 sbsa | 6.x – 15.x | 7.x – 20.x | 24.9–25.5 | No | 24.04–24.10 |

補充：

- 對於 GCC 與 Clang，上表標示**最小版本**與**最新支援**版本。若你的發行版預設編譯器版本低於需求，建議升級工具鏈（例如 RHEL 的 Developer Toolset）。
- 針對預設 GCC 6xx 以下的平臺，不支援連結 CUDA Toolkit 提供的靜態／動態函式庫。
- 僅支援 libstdc++（GCC 的實作）做為 C++ 標準函式庫。

### 主機編譯器相容套件（Host Compiler Compatibility Packages）

非常新的發行版可能預設採用比上表更高的編譯器版本（支援的編譯器附表）。
通常該發行版也會提供 GCC 相容性套件可供 NVCC 使用。
實作方式依發行版而異，但邏輯相同：最後會設定 `NVCC_BIN` 環境變數（詳見 NVCC 文件）。

### 支援的 C++ 語言版本（Supported C++ Dialects）

NVCC 與 NVRTC**（CUDA 執行期編譯器）在受支援主機編譯器上支援 C++11 / C++14 / C++17 / C++20。
NVCC 的預設 C++ 方言由「主機編譯器的預設」決定。

C++20 支援的主機編譯器（host 與 device 端皆適用）：

| GCC | Clang | NVHPC | Arm C/C++ |
| :--- | :--- | :--- | :--- |
| >=10.x | >=11.x | >=22.x | >=22.x |

## 安裝

### 注意事項

這邊說明一下
CUDA 本身是要與相對應的 Driver 搭配，但是一個 Driver 可以裝多個 CUDA Toolkit；

另外在 CUDA 13.0 之前，為了方便，會包含一個 NVIDIA 顯示驅動程式。
而這個捆綁的驅動程式僅用於開發目的。NV 官方不建議將其用於生產環境，尤其是 Tesla GPU。

與此同時在安裝 CUDA Toolkit 期間，使用者可以選擇跳過驅動程式安裝：
- 在 Windows 上：透過互動式或靜默安裝選項。
- 在 Linux 上：透過跳過驅動程式的 meta 套件

簡單說就是如果安裝整個完整的 CUDA，則會包含驅動程式 + CUDA Toolkit
但我們上面已經安裝過 Driver 了，所以這裡只需要安裝 CUDA Toolkit

<font color="red">**請注意，建議驅動與 CUDA Toolkit 分開安裝，不要用他包一起的**</font>
<font color="red">**請注意，建議驅動與 CUDA Toolkit 分開安裝，不要用他包一起的**</font>
<font color="red">**請注意，建議驅動與 CUDA Toolkit 分開安裝，不要用他包一起的**</font>

好的，事情是這樣的，首先，執行 `nvidia-smi`，你會看到一些輸出，如下

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 581.15                 Driver Version: 581.15         CUDA Version: 13.0     |
+-----------------------------------------+------------------------+----------------------+

可以看到 `Driver Version` 與 `CUDA Version`
這裡的 `CUDA Version` 指的是最高可以支援的 CUDA Toolkit 版本
詳情參閱表一

也就是說，如果你的驅動是在 525-580 之間，則 CUDA Toolkit 12.x 版本的都可以使用
此外，CUDA 驅動程式是向後相容的，這意味著針對特定 CUDA 版本編譯的應用程式，將能在後續（更新）的驅動程式版本上繼續運作。
也就世說，你也可以使用 11.x 的版本

但沒有向後相容，所以你不能裝 13.x 的版本

而表二則是如果你安裝完整 CUDA 包，會包含的 Driver，但這裡我們同時也可以當成辨認驅動版本對應的 CUDA Toolkit 版本的細項表格
也就是說如果你的驅動是 `560.35.03` ，則你要安裝 `CUDA 12.6 Update 2`
或是任一 CUDA 12.x 版本也行
大概是這樣

**表 1 : CUDA Toolkit 與 CUDA 次要版本相容性所需的最低驅動程式版本**
| CTK 版本 | 驅動程式範圍 (用於次要版本相容性) | |
| :--- | :--- | :--- |
| | **最低 (Min)** | **最高 (Max)** |
| 13.x | >= 580 | N/A |
| 12.x | >= 525 | < 580 |
| 11.x | >= 450 | < 525 |

---

**表 2 : CUDA Toolkit 與對應的 Driver 版本**
| CUDA Toolkit | Linux x86_64 Driver Version | Windows x86_64 Driver Version |
| :--- | :--- | :--- |
| CUDA 13.0 Update 2 | >=580.95.05 | N/A |
| CUDA 13.0 Update 1 | >=580.82.07 | N/A |
| CUDA 13.0 GA | >=580.65.06 | N/A |
| CUDA 12.9 Update 1 | >=575.57.08 | >=576.57 |
| CUDA 12.9 GA | >=575.51.03 | >=576.02 |
| CUDA 12.8 Update 1 | >=570.124.06 | >=572.61 |
| CUDA 12.8 GA | >=570.26 | >=570.65 |
| CUDA 12.6 Update 3 | >=560.35.05 | >=561.17 |
| CUDA 12.6 Update 2 | >=560.35.03 | >=560.94 |
| CUDA 12.6 Update 1 | >=560.35.03 | >=560.94 |
| CUDA 12.6 GA | >=560.28.03 | >=560.76 |
| CUDA 12.5 Update 1 | >=555.42.06 | >=555.85 |
| CUDA 12.5 GA | >=555.42.02 | >=555.85 |
| CUDA 12.4 Update 1 | >=550.54.15 | >=551.78 |
| CUDA 12.4 GA | >=550.54.14 | >=551.61 |
| CUDA 12.3 Update 1 | >=545.23.08 | >=546.12 |
| CUDA 12.3 GA | >=545.23.06 | >=545.84 |
| CUDA 12.2 Update 2 | >=535.104.05 | >=537.13 |
| CUDA 12.2 Update 1 | >=535.86.09 | >=536.67 |
| CUDA 12.2 GA | >=535.54.03 | >=536.25 |
| CUDA 12.1 Update 1 | >=530.30.02 | >=531.14 |
| CUDA 12.1 GA | >=530.30.02 | >=531.14 |
| CUDA 12.0 Update 1 | >=525.85.12 | >=528.33 |
| CUDA 12.0 GA | >=525.60.13 | >=527.41 |
| CUDA 11.8 GA | >=520.61.05 | >=520.06 |
| CUDA 11.7 Update 1 | >=515.48.07 | >=516.31 |
| CUDA 11.7 GA | >=515.43.04 | >=516.01 |
| CUDA 11.6 Update 2 | >=510.47.03 | >=511.65 |
| CUDA 11.6 Update 1 | >=510.47.03 | >=511.65 |
| CUDA 11.6 GA | >=510.39.01 | >=511.23 |
| CUDA 11.5 Update 2 | >=495.29.05 | >=496.13 |
| CUDA 11.5 Update 1 | >=495.29.05 | >=496.13 |
| CUDA 11.5 GA | >=495.29.05 | >=496.04 |
| CUDA 11.4 Update 4 | >=470.82.01 | >=472.50 |
| CUDA 11.4 Update 3 | >=470.82.01 | >=472.50 |
| CUDA 11.4 Update 2 | >=470.57.02 | >=471.41 |
| CUDA 11.4 Update 1 | >=470.57.02 | >=471.41 |
| CUDA 11.4.0 GA | >=470.42.01 | >=471.11 |
| CUDA 11.3.1 Update 1 | >=465.19.01 | >=465.89 |
| CUDA 11.3.0 GA | >=465.19.01 | >=465.89 |
| CUDA 11.2.2 Update 2 | >=460.32.03 | >=461.33 |
| CUDA 11.2.1 Update 1 | >=460.32.03 | >=461.09 |
| CUDA 11.2.0 GA | >=460.27.03 | >=460.82 |
| CUDA 11.1.1 Update 1 | >=455.32 | >=456.81 |
| CUDA 11.1 GA | >=455.23 | >=456.38 |
| CUDA 11.0.3 Update 1 | >= 450.51.06 | >= 451.82 |
| CUDA 11.0.2 GA | >= 450.51.05 | >= 451.48 |
| CUDA 11.0.1 RC | >= 450.36.06 | >= 451.22 |
| CUDA 10.2.89 | >= 440.33 | >= 441.22 |
| CUDA 10.1 (10.1.105 general release, and updates) | >= 418.39 | >= 418.96 |
| CUDA 10.0.130 | >= 410.48 | >= 411.31 |
| CUDA 9.2 (9.2.148 Update 1) | >= 396.37 | >= 398.26 |
| CUDA 9.2 (9.2.88) | >= 396.26 | >= 397.44 |
| CUDA 9.1 (9.1.85) | >= 390.46 | >= 391.29 |
| CUDA 9.0 (9.0.76) | >= 384.81 | >= 385.54 |
| CUDA 8.0 (8.0.61 GA2) | >= 375.26 | >= 376.51 |
| CUDA 8.0 (8.0.44) | >= 367.48 | >= 369.30 |
| CUDA 7.5 (7.5.16) | >= 352.31 | >= 353.66 |
| CUDA 7.0 (7.0.28) | >= 346.46 | >= 347.62 |

### 安裝前準備

在 Linux 上安裝 CUDA Toolkit 前，請先完成以下事項：

1. 確認 GPU 為 CUDA 相容。
2. 確認作業系統版本受支援。
3. 確認系統已安裝 gcc。
4. 下載 NVIDIA CUDA Toolkit。
5. 處理可能衝突的安裝方式。

#### 確認 GPU 是否支援 CUDA（Verify CUDA‑Capable GPU）

從桌面環境的系統資訊查看，或在命令列輸入：

lspci | grep -i nvidia

若沒有偵測到，可先更新 Linux 所維護的PCI 硬體資料庫，再重試：

sudo update-pciids
lspci | grep -i nvidia

#### 確認受支援的 Linux（Verify Supported Linux）

CUDA 開發工具僅支援特定的 Linux 發行版。查詢當前發行版與版本號：

hostnamectl

#### 確認已安裝 gcc（Verify gcc）

**編譯** CUDA 程式需要 **gcc**；僅**執行** CUDA 應用則不一定需要。多數受支援的發行版預設安裝的 gcc 版本即可。

檢查 gcc 版本：

gcc --version

#### 選擇安裝方式（Choose an Installation Method）

CUDA Toolkit 提供兩大安裝機制：

- 發行版專用套件：RPM / DEB（與系統套件管理整合）
- 與發行版無關的 runfile**：獨立安裝檔（但不會納入系統套件管理）

建議能用發行版套件就優先使用

#### 安裝 CUDA Toolkit

這裡我們選擇使用網路安裝

使用以下指令

# 加入 repo
sudo dnf config-manager addrepo --from-repofile https://developer.download.nvidia.com/compute/cuda/repos/fedora42/x86_64/cuda-fedora42.repo

# 清除 cache
sudo dnf clean all

# 安裝 CUDA Toolkit
sudo dnf -y install cuda-toolkit-13-0
# 重新開機
reboot

完成安裝

### 安裝後動作（Post-installation Actions）

安裝後需要手動執行一些動作。這些動作分為必做（mandatory）、建議（recommended）、與可選（optional） 三類。

#### 需要做的（Mandatory Actions）

在 CUDA Toolkit 可以被使用之前，安裝完成後必須執行以下步驟。

##### 環境設定（Environment Setup）

必須將 CUDA 的 `bin` 路徑加入 `PATH` 環境變數；

先確定有沒有建立 symlinks

ls -l /usr/local/ | grep cuda

若沒有

sudo ln -s /usr/local/cuda-<version> /usr/local/cuda

之後建立一個腳本

sudo nano /etc/profile.d/cuda.sh

在裡面輸入以下指令來建立 `PATH`

if [ -d "/usr/local/cuda/bin" ]; then
    export PATH=/usr/local/cuda/bin:${PATH:+:$PATH}
fi

之後存檔即可

#### 可選（Optional Actions）

以下功能非使用 CUDA Toolkit 所必需，但可提供額外能力。

##### 安裝第三方函式庫（Install Third-party Libraries）

部分 CUDA 範例會使用第三方函式庫，這些函式庫可能不是系統預設安裝。
範例在建置時會嘗試偵測所需函式庫；若偵測不到，該範例會自動跳過並提示缺少哪些套件。要建置與執行這些範例，請先安裝缺少的函式庫。

Fedora

sudo dnf install freeglut-devel libX11-devel libXi-devel libXmu-devel make mesa-libGLU-devel freeimage-devel libglfw3-devel

##### 切換系統中的活動 CUDA 版本（Select the Active Version of CUDA）

對於依賴 `/usr/local/cuda` 與 `/usr/local/cuda-MAJOR` 這些 **symlink** 的應用程式，可使用 alternatives 機制切換到系統內另一個已安裝的 CUDA 版本。

顯示目前啟用版本與所有可用版本：

update-alternatives --display cuda

顯示指定主版本（例如 12）的活動次版本：

update-alternatives --display cuda-12

互動式切換活動版本：

sudo update-alternatives --config cuda

至此，所有安裝及設定完成