Ubuntu22.04视觉开发环境搭建全流程
🚀 第一步：安装 NVIDIA 显卡驱动
📌 安装适配提醒
本文档提供的是通用安装流程和示例命令。不同显卡型号（如 RTX 3060、RTX 4090、RTX 50 系列）、不同 Ubuntu 内核版本，需要安装的驱动版本可能完全不同。请务必在执行以下步骤之前：
- 通过
lspci -nn | grep -i nvidia确认你的显卡型号。- 通过
uname -r确认你的内核版本。- 将上述信息提供给 AI 助手（如 ChatGPT、DeepSeek 等）或查阅 NVIDIA 官方文档，获取针对你当前设备的最合适驱动版本和安装命令。
- 下文中出现的
535、550、575-open等版本号均为示例，请替换为 AI 或官方推荐的实际版本。
1. 为什么先装驱动？（核心原则）
在 Ubuntu 上搭建视觉开发环境，第一步必须是安装 NVIDIA 显卡驱动。
Ubuntu 系统为了开箱即用，默认会加载一个名为 Nouveau 的开源显卡驱动。它能让你点亮屏幕，但它的性能非常有限。对于任何需要使用 CUDA 的开发任务（如深度学习框架、OpenCV 的 CUDA 加速模块等），Nouveau 驱动完全不兼容，并且会和官方驱动产生严重冲突，导致驱动安装失败、黑屏或系统不稳定。
如果先装好其他开发环境再折腾驱动，一旦驱动安装出问题导致系统崩溃，前面的努力就都白费了。因此，这个关键但脆弱的环节必须放在最前面，做成了再继续，做不成也方便随时重装系统。
📌 注意：对于 Ubuntu 22.04，如果使用的是 RTX 50 系列显卡（如 5060、5070 Ti、5080），必须安装开源版 NVIDIA 驱动，命令行安装需要指定
-open后缀。例如：sudo apt install nvidia-driver-575-open # 使用 apt 安装开源驱动 # 或 sudo ubuntu-drivers install nvidia:575-open # 使用 ubuntu-drivers 工具
2. 第一步：环境预检与冲突排查
⚠️ 重要提示： 在开始安装之前，90% 的驱动问题都可以通过系统状态检查来预防。
打开终端（Ctrl + Alt + T），依次执行以下检查命令：
# ① 确认显卡型号
lspci -nn | grep -i nvidia
这个命令会显示 PCI 总线上的 NVIDIA 设备 ID，例如 [10de:13c2]，前段是厂商 ID（10de 代表 NVIDIA），后段是设备型号，记下这个 ID 有助于后续选择正确的驱动版本。
# ② 检查当前正在使用的驱动
lspci -k | grep -A 3 -i vga
查看输出中 Kernel driver in use: 这一行。如果是 nouveau，说明系统正在使用开源驱动，必须禁用它。
# ③ 检查 Secure Boot 状态
mokutil --sb-state
如果显示 SecureBoot enabled，说明安全启动已开启，这可能会阻止未签名的 NVIDIA 驱动模块加载。安装前需要进入 BIOS 将其关闭，或者在安装过程中完成 MOK 密钥注册。
# ④ 检查当前内核版本
uname -r
Ubuntu 22.04 默认内核为 5.15.0-91，该内核支持 535/550 驱动。如果升级过内核，需确保驱动与内核版本匹配。
3. 第二步：安装编译依赖
安装 NVIDIA 驱动需要编译内核模块，因此必须提前安装必要的编译工具和内核头文件：
sudo apt update
sudo apt install build-essential gcc make dkms
sudo apt install linux-headers-$(uname -r)
build-essential包含了gcc、make等基本编译工具。dkms（Dynamic Kernel Module Support）是一个非常重要的工具，它能确保你的 NVIDIA 驱动在系统内核更新后，自动重新编译并适配新内核，避免因内核升级导致驱动失效。linux-headers-$(uname -r)是你当前内核版本对应的头文件，编译驱动时必需。
4. 第三步：彻底清除 Nouveau 开源驱动
⚠️ 注意： 这是最关键的一步。NVIDIA 官方驱动和 Nouveau 会同时尝试控制同一硬件，如果你不先禁用 Nouveau，它们会在系统底层（内核模块）打架，导致“未能创建内核”的报错，甚至引发系统黑屏无法启动。
4.1 彻底删除所有旧的 NVIDIA 驱动残留（如之前安装过）
sudo apt-get --purge remove "*nvidia*" # 清理所有 nvidia 相关包
sudo apt-get --purge remove "*cuda*" # 如果有 CUDA 残留也一并清理
sudo apt autoremove
💡 提示： 如果你之前用
.run文件安装过驱动，还需要运行卸载脚本：sudo /usr/bin/nvidia-uninstall # 如果提示找不到文件，说明之前没用过此方式
4.2 将 Nouveau 驱动加入黑名单
方式一：创建独立的配置文件（推荐）
sudo bash -c "echo blacklist nouveau > /etc/modprobe.d/blacklist-nvidia-nouveau.conf"
sudo bash -c "echo options nouveau modeset=0 >> /etc/modprobe.d/blacklist-nvidia-nouveau.conf"
然后验证文件内容：
cat /etc/modprobe.d/blacklist-nvidia-nouveau.conf
应显示：
blacklist nouveau
options nouveau modeset=0
方式二：添加到已有的 blacklist.conf（备选）
sudo vim /etc/modprobe.d/blacklist.conf
在文件末尾添加：
blacklist nouveau
options nouveau modeset=0
备选方案：通过 GRUB 内核参数禁用
# 编辑 GRUB 配置文件
sudo nano /etc/default/grub
# 找到 GRUB_CMDLINE_LINUX_DEFAULT 或 GRUB_CMDLINE_LINUX 行，在引号内添加 nouveau.blacklist=1
GRUB_CMDLINE_LINUX_DEFAULT="quiet splash nouveau.blacklist=1"
# 保存后更新 GRUB 并重启
sudo update-grub
sudo reboot
4.3 更新内核并重启
sudo update-initramfs -u
sudo reboot
4.4 验证 Nouveau 是否已被成功禁用
重启后，在终端执行：
lsmod | grep nouveau
如果命令没有任何输出，说明 Nouveau 驱动已被成功屏蔽，可以继续下一步。
💡 提示：在 Ubuntu 22.04 中，通过正规渠道（如
ubuntu-drivers或“附加驱动”）安装 NVIDIA 驱动时，系统通常会自动处理 Nouveau 的禁用问题，手动干预有时反而可能因操作不当导致系统无法正常启动。如果后续通过推荐方法安装，此步骤可以跳过，但提前做好清理能避免绝大多数潜在冲突。
5. 第四步：安装 NVIDIA 驱动（三种方法任选其一）
方法一：通过 ubuntu-drivers 命令行安装（首选）
-
安装
ubuntu-drivers工具（通常已预装）：sudo apt install ubuntu-drivers-common -
添加 Graphics Drivers PPA 源（可选但推荐） ：
Ubuntu 官方仓库中的显卡驱动版本可能较旧，添加 Graphics Drivers Team 维护的 PPA 源可以获取更新且更稳定的驱动程序：sudo add-apt-repository ppa:graphics-drivers/ppa sudo apt update -
查看系统为你的显卡推荐的驱动版本：
sudo ubuntu-drivers devices命令会列出所有可用驱动，带
recommended标记的就是系统推荐的最佳版本，通常也是数字版本最大的那个。例如：== /sys/devices/pci0000:00/0000:00:01.0/0000:01:00.0 == modalias : pci:v000010DEd00002206sv00001458sd0000403Fbc03sc00i00 vendor : NVIDIA Corporation model : GA102 [GeForce RTX 3080] driver : nvidia-driver-535 - distro non-free recommended driver : nvidia-driver-550 - distro non-free ... -
自动安装推荐驱动：
sudo ubuntu-drivers autoinstall或者手动指定版本安装（以
535为例）：sudo apt install nvidia-driver-535两种方式效果相同，后者更可控。对于 Ubuntu 22.04.5（使用 Linux 6.8 内核），
nvidia-driver-535或nvidia-driver-550通常是经过严格测试的稳定版本。 -
安装完成后重启系统：
sudo reboot注意：即使
nvidia-smi暂时看不到显卡信息，重启后就能正常显示。
方法二：通过“软件和更新”图形界面安装（备选）
- 在应用程序菜单中搜索并打开 “软件和更新”。
- 切换到 “附加驱动” 选项卡，系统会自动检测可用的驱动。
- 在列表中选择标记为“专有，测试过（tested）” 的推荐版本，避开任何带有“nouveau”或“开源”字样的选项。
- 点击“应用更改”，输入密码，等待下载安装完成。
- 安装完成后，点击“重启”使驱动生效。
💡 提示：如果命令行
ubuntu-drivers autoinstall反复失败，可以试试这个图形界面方法，有时它能自动解决一些奇怪的依赖冲突。
方法三：从 NVIDIA 官网下载 .run 文件手动安装（最后手段）
⚠️ 警告： 这是一个更复杂的方案，仅在前两种方法都失败时才考虑。它的操作相对繁琐，要求你完全熟悉 Linux 命令行，并且需要手动处理后续的内核更新问题。官方社区甚至建议不要直接从 NVIDIA 安装
.run文件。
-
访问 NVIDIA 官网下载驱动：
- NVIDIA 中国驱动下载中心：https://www.nvidia.cn/Download/index.aspx?lang=cn
- 根据你的显卡型号、操作系统（Linux 64-bit）下载
.run文件。 - 注意： 下载的驱动文件要放在英文路径中，避免中文路径导致问题。
-
安装编译依赖（参见第三步）。
-
进入 TTY 模式并停止图形界面：
- 按
Ctrl + Alt + F2（或 F3~F6）进入 TTY 命令行，输入用户名和密码登录。 - 停止图形界面服务：
sudo service gdm3 stop # 如果使用 GDM # 或 sudo service lightdm stop # 如果使用 LightDM - 如果 TTY 界面出现中文乱码，输入：
export LANG="UTF-8" export LANGUAGE="UTF-8"
- 按
-
赋予
.run文件执行权限并安装：cd ~/Downloads chmod 777 NVIDIA-Linux-*.run # 赋予可执行权限 sudo ./NVIDIA-Linux-*.run --no-opengl-files --no-x-check --no-nouveau-check--no-opengl-files：只安装驱动文件，不安装 OpenGL 文件。--no-x-check：安装驱动时关闭 X 服务检查。--no-nouveau-check：跳过 Nouveau 检查（已在前面手动禁用）。
-
安装过程中的选项：
- 遇到
Install Nvidia's 32-bit compatibility libraries?选择 "No"。 - 遇到
Would you like to run the nvidia-xconfig utility...?选择 "Yes"。 - 其他选项保持默认即可。
- 遇到
-
安装完成后重启图形界面并验证：
sudo service gdm3 start # 或 sudo service lightdm start sudo reboot
6. 第五步：验证驱动是否安装成功
重启后，打开终端执行：
nvidia-smi
如果成功，你会看到类似以下的输出，包含 NVIDIA-SMI 版本、驱动版本、CUDA 版本、GPU 型号等信息：
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.154.05 Driver Version: 535.154.05 CUDA Version: 12.2 |
|-------------------------------+----------------------+----------------------+
| GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. |
|===============================+======================+======================|
| 0 NVIDIA GeForce ... Off | 00000000:01:00.0 On | N/A |
...
上方中间显示的是驱动版本，CUDA Version 表示最高可支持的 CUDA 版本。
此外，还可以通过以下命令打开 NVIDIA 设置面板进行进一步确认：
nvidia-settings
如果 nvidia-settings 命令不存在，可通过以下命令安装：
sudo apt install nvidia-settings
7. 常见问题与排坑指南
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
nvidia-smi 报错 "NVIDIA-SMI has failed..." 或 "No devices were found" |
驱动未正确加载；Nouveau 未禁用干净；Secure Boot 阻止了驱动加载 | 1. 确认 Nouveau 已禁用：lsmod \| grep nouveau 应无输出。2. 确认驱动已安装： dpkg -l \| grep nvidia-driver。3. 检查 Secure Boot 状态： mokutil --sb-state，若开启则进入 BIOS 关闭。4. 尝试彻底清理并重装： sudo apt purge "*nvidia*" → 重启 → 重新安装推荐驱动。 |
| 安装驱动后，重启黑屏或卡在登录界面 | 驱动版本与内核或显卡不兼容；Wayland 与 NVIDIA 不兼容 | 1. 在 GRUB 界面按 e，在 quiet splash 后添加 nomodeset 临时进入系统。2. Ubuntu 22.04 默认使用 Wayland 显示协议，但 NVIDIA 对 Wayland 的支持仍不完善，建议切换到 Xorg。 3. 卸载当前驱动： sudo apt purge "*nvidia*"。4. 换一个推荐驱动版本重试（例如从 nvidia-driver-535 换成 nvidia-driver-470）。5. 检查 HDMI/DP 线是否插在独立显卡接口上。 |
| 安装驱动时提示 "Operation not permitted" 或模块签名失败 | Secure Boot 阻止了未签名驱动模块的加载 | 1. 进入 BIOS 关闭 Secure Boot。 2. 若不想关闭，可在安装过程中根据提示设置 MOK 密码，重启后进入 MOK 管理界面完成密钥注册。 |
ubuntu-drivers devices 没有输出或找不到推荐驱动 |
软件源问题；显卡太新，官方源驱动暂未收录 | 1. 确保已启用 universe 和 multiverse 软件源。2. 添加 Graphics Drivers PPA 获取最新驱动： sudo add-apt-repository ppa:graphics-drivers/ppa && sudo apt update。3. 重新执行 ubuntu-drivers devices。 |
使用 .run 文件安装时报 GCC 版本错误 |
GCC 版本过低或未安装 | 安装 GCC 12：sudo apt install gcc-12 g++-12，并将其设为默认版本。 |
| 安装完成后，内核更新导致驱动失效 | DKMS 未正确安装或未启用 | 确保已安装 dkms。检查驱动模块是否已注册到 DKMS：dkms status。若没有，可手动添加。也可使用以下命令修复： sudo apt install --reinstall nvidia-driver-535。 |
nvidia-smi 输出 "No devices were found" 但驱动已安装 |
双显卡系统 GPU 运行模式问题 | 检查当前激活的 GPU：prime-select query。可使用 sudo prime-select nvidia 切换到 NVIDIA 显卡并重启。 |
| TTY 模式下中文乱码 | 系统语言设置问题 | 输入 export LANG="UTF-8" 和 export LANGUAGE="UTF-8" 临时解决。 |
| 安装驱动后 WiFi 消失 | 内核更新导致无线网卡驱动未适配新内核 | 在 GRUB 高级选项中回退到旧内核启动；或重新安装无线网卡驱动。 |
8. 💎 总结
- 安装顺序：NVIDIA 驱动必须在所有其他开发环境之前安装，这是确保后续环境稳定性的关键。
- 推荐方法：首选
ubuntu-drivers autoinstall命令或“软件和更新”的图形界面。 - 关键步骤：
- 彻底禁用 Nouveau 开源驱动（通过正规渠道安装时系统会自动处理）。
- 安装
dkms等必要的编译依赖。 - 选择带有
recommended标记的驱动版本。 - 重启系统并用
nvidia-smi验证。
- 最后的办法：如果以上方法都失败，再考虑从 NVIDIA 官网下载
.run文件手动安装。 - 保持耐心：如果反复尝试还是装不上，可以暂时放弃该方式，尝试图形界面安装或官网手动安装。即使这个环节实在搞不定，随时重装系统也来得及，毕竟是环境配置的第一步。
🚀 第二步：安装 NVIDIA CUDA Toolkit
📌 安装适配提醒
CUDA Toolkit 的版本必须与你的 NVIDIA 驱动版本兼容（驱动支持的 CUDA 上限可通过
nvidia-smi查看）。请勿盲目使用文中的示例版本号（如 12.5）。建议操作：
- 执行
nvidia-smi，查看右上角的CUDA Version，记下这个版本号上限。- 将你的驱动版本、Ubuntu 版本、显卡型号告诉 AI 助手，询问推荐安装的 CUDA Toolkit 版本。
- 访问 NVIDIA CUDA Toolkit 官方下载页面，根据 AI 建议或官方兼容性列表选择正确的版本。
- 将下文中的
12.5、cuda_12.5.0_555.42.02_linux.run等示例替换为你实际选择的版本。
CUDA（Compute Unified Device Architecture）是 NVIDIA 推出的并行计算平台和编程模型。它让开发者能够使用 C++、Python 等语言编写程序，调用 GPU 中成百上千个核心来并行处理海量数据，是深度学习、科学计算等领域实现 GPU 加速的基石。
在安装之前，先理清几个核心概念，这能帮你理解后续步骤：
- NVIDIA 驱动：让操作系统能够识别和使用 GPU 硬件，是运行任何 CUDA 程序的基础。驱动的版本决定了你的系统最高能支持哪个版本的 CUDA。
- CUDA Toolkit：包含了编译器（
nvcc）、核心库、调试和优化工具等，是构建 CUDA 应用程序所需的开发套件。我们常说的“安装 CUDA”，实际就是在安装这个 Toolkit。 - cuDNN：在 CUDA Toolkit 之上，专门为深度神经网络提供极致优化的高性能加速库。
准备工作
① 确认驱动与 CUDA 版本的兼容性
在终端执行以下命令，确认 NVIDIA 驱动已正确安装，并查看其支持的最高 CUDA 版本：
nvidia-smi
输出示例：
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.154.05 Driver Version: 535.154.05 CUDA Version: 12.2 |
+-----------------------------------------------------------------------------+
其中 CUDA Version: 12.2 表示当前驱动最高支持 CUDA 12.2。你选择的 CUDA 版本不能超过这个数字。
注意：
nvidia-smi显示的是驱动支持的 CUDA 版本上限，而后续nvcc -V显示的是当前系统环境变量所指向的 CUDA Toolkit 版本。二者可能不同，这是正常现象，关键是确保你安装的 CUDA Toolkit 版本不高于驱动支持的上限。
② 检查系统环境
确保已安装必要的编译工具：
sudo apt update
sudo apt install build-essential gcc make
CUDA 下载及安装
📌 推荐方式：建议使用 runfile 进行安装。这种方式灵活可控，能自定义安装组件，方便在已安装驱动的情况下，只安装 CUDA Toolkit，从而避免驱动冲突。
步骤 1：下载 CUDA Toolkit 安装包
- 访问 NVIDIA CUDA Toolkit 官方下载页面。
- 在页面上按顺序选择你的系统环境：
- Operating System: Linux
- Architecture: x86_64
- Distribution: Ubuntu
- Version: 22.04
- Installer Type: runfile (local)
- 选择后，页面下方会显示
wget下载命令，复制该命令并在终端中执行即可下载安装包。例如：
（本文以 CUDA 12.5.0 为例，请根据你的实际需求调整）wget https://developer.download.nvidia.com/compute/cuda/12.5.0/local_installers/cuda_12.5.0_555.42.02_linux.run
步骤 2：运行安装程序
-
进入下载目录，赋予安装文件执行权限并运行：
cd ~/Downloads chmod +x cuda_12.5.0_555.42.02_linux.run sudo sh cuda_12.5.0_555.42.02_linux.run -
阅读许可协议后，输入
accept并按回车确认。 -
在出现的
CUDA Installer菜单中，使用上下方向键移动，空格键选择/取消选项。- 关键操作：由于我们已在第一步中安装了 NVIDIA 驱动，这里务必取消勾选
Driver选项，避免驱动覆盖导致冲突。 - 确保勾选了
CUDA Toolkit。 - 根据需要选择其他组件（如
CUDA Samples），然后移动光标到Install并回车。
- 关键操作：由于我们已在第一步中安装了 NVIDIA 驱动，这里务必取消勾选
-
等待安装完成，会出现类似以下的成功提示：
=========== = Summary = =========== Driver: Not Selected Toolkit: Installed in /usr/local/cuda-12.5/
但是博主始终还是建议使用上面的方法安装，因为这样更保险
💡 备选方案：通过网络仓库（APT）安装
如果更习惯使用
apt进行包管理，也可以采用此方法，它更省心、便于后续更新。
- 安装
cuda-toolkit元包：sudo apt install nvidia-cuda-toolkit- 安装完成后，它会自动配置好环境变量，重启终端后即可使用。
- 注意：APT 源中的 CUDA 版本可能不是最新的，且安装路径为
/usr/lib/cuda/，与 runfile 的默认路径不同。如需特定版本或最新版本，还是推荐使用 runfile 方式。
配置环境变量
为了让系统能够找到 CUDA 的可执行文件（如 nvcc）和动态链接库，需要将其路径添加到环境变量中。
# 打开用户配置文件（根据你使用的 shell，可能是 ~/.bashrc 或 ~/.zshrc）
nano ~/.bashrc
# 或 nano ~/.zshrc
在文件末尾添加以下内容（请将版本号 12.5 替换为你实际安装的版本）：
# CUDA Environment Variables
export PATH=/usr/local/cuda-12.5/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.5/lib64:$LD_LIBRARY_PATH
保存并退出编辑器，然后执行以下命令使配置立即生效：
source ~/.bashrc # 或 source ~/.zshrc
💡 提示：如果要为所有用户设置环境变量，可以将上述
export语句添加到/etc/profile或/etc/environment文件中。
验证 CUDA 安装
完成以上步骤后，打开一个新的终端窗口，输入以下命令：
nvcc --version
# 或
nvcc -V
如果安装成功，会显示你刚安装的 CUDA 版本信息，例如：
nvcc: NVIDIA (R) Cuda compiler driver
Copyright (c) 2005-2024 NVIDIA Corporation
Built on Wed_Nov__6_00:00:00_PDT_2024
Cuda compilation tools, release 12.5, V12.5.40
此时，也可以再次运行 nvidia-smi，你会看到右上角的 CUDA Version: 12.2（表示驱动最高支持 12.2），与你 nvcc -V 显示的 12.5 不同，这是正常现象，因为 nvcc 显示的是你安装的 CUDA Toolkit 版本，而 nvidia-smi 显示的是驱动 API 的版本。
常见问题与排坑指南
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
nvcc -V 提示“nvcc: command not found” |
环境变量未正确配置 | 1. 检查 ~/.bashrc 中的 PATH 配置是否正确。2. 确认 CUDA 安装路径 /usr/local/cuda-12.5/bin 下是否有 nvcc 文件。3. 执行 source ~/.bashrc 或重启终端。 |
运行 CUDA 程序时提示 libcudart.so.12 找不到 |
动态链接库路径未配置 | 1. 检查 ~/.bashrc 中的 LD_LIBRARY_PATH 配置是否正确。2. 执行 sudo ldconfig 更新系统库缓存。3. 检查 /usr/local/cuda-12.5/lib64 目录下是否有该库文件。 |
nvidia-smi 与 nvcc -V 显示的 CUDA 版本不一致 |
驱动版本与 CUDA Toolkit 版本不同 | 这是正常现象。nvidia-smi 显示的是驱动支持的最高 CUDA 版本，而 nvcc -V 显示的是当前安装的 CUDA Toolkit 版本。只要 CUDA Toolkit 版本不高于驱动支持的最高版本，就不会有问题。 |
| 安装 CUDA 后系统黑屏或无法进入桌面 | 安装时未取消 Driver 选项，覆盖了原有驱动 |
1. 进入 TTY 模式（Ctrl+Alt+F2）。2. 卸载 CUDA： sudo /usr/local/cuda-12.5/bin/cuda-uninstaller。3. 重新安装驱动，然后重装 CUDA，记得取消勾选 Driver。 |
| 内核更新后 CUDA 程序无法运行 | 内核版本与驱动不兼容，DKMS 未生效 | 1. 在 GRUB 引导菜单中选择旧版本内核启动。 2. 重新安装驱动并确保 DKMS 已启用。 |
sudo sh cuda_*.run 提示权限不足 |
文件未添加可执行权限 | 执行 chmod +x cuda_*.run 赋予执行权限后再运行。 |
💎 总结
- 安装顺序：NVIDIA 驱动 → CUDA Toolkit → cuDNN，顺序不能乱。
- 版本选择：CUDA 版本不能高于
nvidia-smi显示的CUDA Version。 - 安装方式：首选 runfile 方式，灵活可控，但安装时务必取消勾选 Driver 选项，避免驱动冲突。
- 环境变量：安装后务必配置
PATH和LD_LIBRARY_PATH，并执行source使其生效。 - 验证成功：执行
nvcc -V能正确输出版本信息，即表示 CUDA 安装成功。
📦 第三步：安装 NVIDIA cuDNN
📌 安装适配提醒
cuDNN 版本必须与你已安装的 CUDA 主版本严格匹配（例如 CUDA 12.x 必须搭配 cuDNN for CUDA 12.x）。不同 cuDNN 版本的安装包名、仓库地址均有差异。
建议操作：
- 通过
nvcc --version确认你已安装的 CUDA 主版本号（如 12.5）。- 访问 NVIDIA cuDNN 官方下载页面，登录后根据你的 CUDA 版本选择合适的 cuDNN 版本。
- 将你的 CUDA 版本告诉 AI 助手，询问推荐安装的 cuDNN 版本及对应的安装命令。
- 下文中的
cudnn-local-repo-ubuntu2204-9.x.y、libcudnn9等均为示例，请替换为你实际下载的文件名和包名。
cuDNN（CUDA Deep Neural Network library）是 NVIDIA 专门为深度神经网络打造的一个 GPU 加速库。它可以为卷积、池化、归一化、激活函数等标准操作提供高度优化的实现，是 PyTorch、TensorFlow 等几乎所有主流深度学习框架的底层加速引擎。
cuDNN 和 CUDA 的关系：CUDA 是 NVIDIA 的并行计算平台，提供底层的 GPU 编程接口；cuDNN 则是在 CUDA 之上构建的、专门针对深度神经网络优化的函数库。两者必须版本匹配才能正常工作。
1. 准备工作
1.1 注册 NVIDIA 开发者账号
cuDNN 的下载需要登录 NVIDIA 开发者账号，这是必须完成的一步。
- 访问 NVIDIA cuDNN 官方下载页面
- 点击页面右上角的“Login”，如果还没有账号，选择“Create an account”注册
- 填写邮箱、姓名、国家等基本信息，完成邮箱验证后即可登录
1.2 确认已安装的 CUDA 版本
在终端执行以下命令，确认你已经安装的 CUDA 版本：
nvcc --version
# 或
nvcc -V
输出示例：
nvcc: NVIDIA (R) Cuda compiler driver
Cuda compilation tools, release 12.5, V12.5.40
记下 CUDA 的主版本号（例如 12.5 的主版本是 12.x），后续下载 cuDNN 时必须选择对应的版本。
💡 提示：cuDNN 的版本命名规则通常为
cuDNN v8.9.x for CUDA 12.x，你需要确保 cuDNN 所支持的 CUDA 版本与你系统已安装的 CUDA 版本匹配。
1.3 确认 GPU 驱动与 CUDA 版本兼容性
你可以通过 nvidia-smi 命令查看当前驱动支持的最高 CUDA 版本：
nvidia-smi
输出示例：
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.154.05 Driver Version: 535.154.05 CUDA Version: 12.2 |
+-----------------------------------------------------------------------------+
其中 CUDA Version: 12.2 表示当前驱动最高支持 CUDA 12.2，你可以安装 CUDA 12.x 系列的任意版本（向下兼容），但不能超过 12.2。
1.4 安装 zlib 依赖（仅 tar 方式安装需要）
如果你计划通过 tar 包方式手动安装 cuDNN，需要先安装 zlib：
sudo apt update
sudo apt install zlib1g
2. 下载 cuDNN
登录 NVIDIA 开发者账号后，访问 cuDNN 下载页面，根据你的 CUDA 版本选择对应的 cuDNN 版本。
版本选择建议：
- 推荐：选择与你 CUDA 版本匹配的最新 cuDNN 版本
- 深度学习框架开发：优先参考你使用的框架（PyTorch/TensorFlow）官方推荐的 cuDNN 版本
- GPU 架构参考：RTX 30/40 系显卡推荐 CUDA 12.x + cuDNN ≥ 8.9
NVIDIA 提供了两种安装包格式：
- Debian 包（
.deb） ：与系统的包管理器集成，便于后续更新和维护，推荐使用 - Tar 压缩包（
.tar.xz） ：通用格式，适用于各种 Linux 发行版，但需要手动复制文件
根据你选择的安装方式，下载对应的文件。下载后，记下文件的保存路径。
3. 安装 cuDNN（三种方式任选其一）
方法一：Debian 包网络安装（推荐）
这是官方推荐的方式，通过添加 NVIDIA 软件仓库，可以直接使用 apt 安装和管理 cuDNN，后续更新也最方便。
步骤 1：添加 NVIDIA CUDA 软件仓库
首先，按照 NVIDIA CUDA Ubuntu 安装指南 添加网络仓库（如果你之前安装 CUDA 时已经添加过，可以跳过此步）。
步骤 2：安装 cuDNN
添加仓库后，直接通过 apt 安装：
sudo apt update
sudo apt install cudnn
系统会自动选择与当前 CUDA 版本兼容的 cuDNN 版本进行安装。
这里还是建议查看版本以后再作这些内容，这一套开发链必须版本对应上不然会出问题
💡 提示：如果你需要安装特定版本的 cuDNN，可以先查看仓库中可用的版本：
apt list -a cudnn*然后指定版本安装：
sudo apt install cudnn=版本号
方法二：Debian 包本地安装
如果你下载的是 .deb 文件，可以使用以下命令安装：
步骤 1：安装本地仓库包
# 进入下载目录
cd ~/Downloads
# 安装本地仓库包（以 cuDNN 9.x 为例）
sudo dpkg -i cudnn-local-repo-ubuntu2204-9.x.y_1.0-1_amd64.deb
步骤 2：导入 GPG 密钥并更新
# 复制 GPG 密钥
sudo cp /var/cudnn-local-repo-*/cudnn-*-keyring.gpg /usr/share/keyrings/
# 更新软件源
sudo apt update
步骤 3：安装 cuDNN 库
# 查看可用版本
apt list -a libcudnn*
# 安装（版本号需根据实际情况替换）
sudo apt install libcudnn9
💡 提示：如果需要开发头文件，还需安装对应的开发包：
sudo apt install libcudnn9-dev
方法三：Tar 压缩包手动安装（备选方案）
这种方式适用于任何 Linux 发行版，但需要手动复制文件。
步骤 1：解压 cuDNN 压缩包
# 进入下载目录
cd ~/Downloads
# 解压 tar 包
tar -xvf cudnn-linux-x86_64-8.9.x.y_cuda12-archive.tar.xz
步骤 2：复制文件到 CUDA 安装目录
# 进入解压后的目录
cd cudnn-linux-x86_64-8.9.x.y_cuda12-archive
# 复制头文件
sudo cp include/cudnn*.h /usr/local/cuda/include/
# 复制库文件
sudo cp lib/libcudnn* /usr/local/cuda/lib64/
# 设置正确的文件权限
sudo chmod a+r /usr/local/cuda/include/cudnn*.h /usr/local/cuda/lib64/libcudnn*
⚠️ 注意：如果你将 CUDA 安装在了其他路径（例如
/opt/cuda），请将命令中的/usr/local/cuda替换为实际的 CUDA 安装路径。
4. 验证 cuDNN 安装
安装完成后，需要验证 cuDNN 是否正确安装和配置。
4.1 检查 cuDNN 版本信息
cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR -A 2
如果 cuDNN 已经正确安装，将会显示类似以下信息：
#define CUDNN_MAJOR 8
#define CUDNN_MINOR 9
#define CUDNN_PATCHLEVEL 1
--
#define CUDNN_VERSION (CUDNN_MAJOR * 1000 + CUDNN_MINOR * 100 + CUDNN_PATCHLEVEL)
这表示安装的 cuDNN 版本为 8.9.1。
💡 提示：对于较新版本的 cuDNN（9.x 以上），头文件可能为
cudnn.h，可以尝试：cat /usr/local/cuda/include/cudnn.h | grep CUDNN_MAJOR -A 2或者直接查看版本号定义：
grep -r "CUDNN_VERSION" /usr/local/cuda/include/cudnn*.h
4.2 运行 cuDNN 示例程序（可选，更严格的验证）
如果你想更全面地验证 cuDNN 是否能正常工作，可以编译并运行官方提供的示例程序：
# 复制示例程序到用户目录
cp -r /usr/src/cudnn_samples_v8/ $HOME/
cd $HOME/cudnn_samples_v8/mnistCUDNN
# 编译示例程序
sudo make clean && sudo make
# 运行 MNIST 示例
./mnistCUDNN
如果运行成功，你会在输出末尾看到 Test passed! 的字样，说明 cuDNN 已经能够正常调用 GPU 进行神经网络计算。
💡 提示：如果
/usr/src/cudnn_samples_v8/目录不存在，说明你可能只安装了运行时库，没有安装示例程序。可以通过以下命令安装：sudo apt install libcudnn8-samples # 或对于 cuDNN 9.x sudo apt install libcudnn9-samples
5. 常见问题与排坑指南
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
执行 cat /usr/local/cuda/include/cudnn_version.h 提示“没有那个文件或目录” |
cuDNN 头文件未正确复制；CUDA 安装路径不同 | 1. 检查 CUDA 的实际安装路径：which nvcc 或 ls -l /usr/local/cuda。2. 如果 CUDA 安装在 /opt/cuda，则头文件路径应为 /opt/cuda/include/。3. 重新执行 tar 方式的复制步骤，使用正确的路径。 |
运行 ./mnistCUDNN 时报错 error while loading shared libraries: libcudnn.so.8 |
动态链接库路径未正确配置 | 1. 确认库文件存在：ls -l /usr/local/cuda/lib64/libcudnn*。2. 添加库路径到环境变量： export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH。3. 或更新链接器缓存： sudo ldconfig。 |
| 下载 cuDNN 时找不到对应 CUDA 版本的选项 | NVIDIA 网站页面设计变更；该版本组合已不再提供 | 1. 在下载页面的“Archived cuDNN Releases”区域查找旧版本。 2. 确认你的 CUDA 主版本号（如 12.x），选择兼容的 cuDNN 版本。 |
sudo apt install cudnn 提示“无法定位软件包” |
NVIDIA 软件仓库未正确添加 | 1. 按照 NVIDIA CUDA Ubuntu 安装指南 重新添加仓库。 2. 执行 sudo apt update 后再试。 |
| 编译 cuDNN 示例时提示“nvcc: command not found” | CUDA 工具链未正确安装或环境变量未配置 | 1. 确认 CUDA 已安装：ls /usr/local/cuda/bin/nvcc。2. 添加 CUDA 到 PATH： export PATH=/usr/local/cuda/bin:$PATH。 |
| cuDNN 示例编译成功但运行时报 CUDA 驱动版本不匹配 | 驱动版本过旧，不支持当前 CUDA 版本 | 1. 运行 nvidia-smi 查看驱动支持的 CUDA 最高版本。2. 如果已安装的 CUDA 版本超过了驱动支持范围，需要升级驱动或降级 CUDA。 |
6. 💎 总结
- 安装时机：cuDNN 必须在 NVIDIA 驱动和 CUDA 安装完成之后安装。
- 版本匹配：cuDNN 版本必须与你已安装的 CUDA 主版本兼容（例如 CUDA 12.x 对应 cuDNN for CUDA 12.x）。
- 推荐方式：首选通过 NVIDIA 官方仓库的
sudo apt install cudnn网络安装，这是最省心、最易维护的方式。 - 验证成功：执行
cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR -A 2能够输出版本号信息，即表示安装成功。 - 后续步骤：cuDNN 安装完成后，可以继续安装 PyTorch/TensorFlow 等深度学习框架，它们会自动调用 cuDNN 进行加速。
📦 第四步：安装 PyTorch
（然后这里的安装基本上可以去找相关的镜像站来安装，作者测试的南京大学的镜像站是最快的，可以达到几十mb每秒
然后这里的全局安装推荐那些只做视觉开发的人）
🎯 方案一：pip 直接全局安装（最推荐，无需虚拟环境）
📌 安装适配提醒
PyTorch 版本必须与你已安装的 CUDA 版本匹配（例如 CUDA 12.1 对应
cu121标签）。直接从官网获取安装命令是最安全的方式。建议操作：
- 访问 PyTorch 官网 Get Started 页面，在 “Compute Platform” 中选择与你 CUDA 版本一致的选项。
- 如果官网速度慢，可以使用下文中的南京大学镜像站或清华镜像源加速。
- 下文中的
cu121、cu118、2.4.1等版本号均为示例，请以官网生成的命令为准。
对于视觉开发来说，这是最省心、最干净的方案。直接用 pip 把 PyTorch 装到系统环境里，不用折腾虚拟环境，也不用忍受 Conda 那巨大的体积和复杂的依赖关系。视觉开发任务相对单一，不太会出现依赖冲突，所以全局安装完全够用，开箱即用，省时省力。
准备工作
① 确认 Python 版本
PyTorch 2.x 系列推荐 Python 3.8 及以上版本，最新版推荐 Python 3.10 或更高。打开终端执行：
python3 --version
如果版本过低，建议从 Python 官网下载安装。
② 升级 pip 到最新版
过旧的 pip 版本可能导致安装失败。执行：
pip3 install --upgrade pip
③ 确认 NVIDIA 驱动状态
确保你的 GPU 驱动已经装好，并且驱动版本能支持你想要的 CUDA 版本。执行：
nvidia-smi
右上角的 CUDA Version 就是驱动支持的最高 CUDA 版本。你选的 PyTorch 版本里带的 CUDA 版本不能超过这个数。
安装步骤
步骤 1：访问 PyTorch 官网获取命令
前往 PyTorch 官网，在 "Start Locally" 区域选择：
- PyTorch Build: Stable
- Your OS: Linux
- Package: Pip
- Language: Python
- Compute Platform: 选择与你驱动匹配的 CUDA 版本（如 CUDA 12.1）
页面会自动生成安装命令，直接复制使用即可。常见版本示例：
# CUDA 12.1 版本
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
# CUDA 11.8 版本
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
步骤 2（可选但强烈推荐）：配置国内镜像源加速
在国内网络环境下，从官方源下载可能很慢甚至失败。推荐使用清华镜像源，下载速度可以从不足 200KB/s 提升到 5~50MB/s，一个完整的 PyTorch 安装包通常能在 40 秒内完成。
临时加速方案（单次生效）：
pip3 install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple
永久配置（推荐），后续所有 pip 命令都会自动走清华源：
mkdir -p ~/.pip
cat > ~/.pip/pip.conf << EOF
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
timeout = 120
EOF
备选镜像：阿里云 PyTorch Wheels
阿里云也提供了 PyTorch 的 Wheels 镜像，但需要注意使用 -f 参数而不是 -i，因为这些镜像不提供完整的索引服务：
pip3 install torch==2.4.1 torchvision torchaudio -f https://mirrors.aliyun.com/pytorch-wheels/cu121/
验证安装
装完后，打开终端进入 Python 环境，执行以下代码验证：
import torch
print("PyTorch 版本:", torch.__version__)
print("CUDA 是否可用:", torch.cuda.is_available())
if torch.cuda.is_available():
print("torch.version.cuda:", torch.version.cuda) # PyTorch 内置的 CUDA 运行时版本
print("GPU 设备名称:", torch.cuda.get_device_name(0))
看到 CUDA 是否可用: True 和你的显卡型号，就说明装成功了。
常见问题与排坑指南
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
torch.cuda.is_available() 返回 False |
① 装成了 CPU 版本；② NVIDIA 驱动没装好或版本太低 | ① 检查 torch.__version__ 是否包含 +cpu，有则重装 GPU 版。② 执行 nvidia-smi 确认驱动已加载，且驱动支持的 CUDA 版本不低于 PyTorch 要求的版本。 |
pip install 时报错 externally-managed-environment |
系统启用了 PEP 668 外部管理环境保护，禁止直接向系统 Python 安装包 | ① 使用 --break-system-packages 参数强行安装：pip3 install torch --break-system-packages。② 或者使用 pipx 工具（适合 CLI 工具）。 |
| 安装速度极慢或超时 | 网络访问官方源受限 | 按照上文配置清华镜像源，可以百倍提速。 |
安装完成后 import torch 报错 Illegal instruction |
CPU 太老，不支持 AVX 指令集 | 执行 grep avx /proc/cpuinfo 检查。若不支持，需安装旧版 PyTorch。 |
pip install 后其他用户用不了 PyTorch |
安装时没加 sudo -H，包被装到了当前用户的 .local 目录 |
使用 sudo -H pip3 install ... 重新安装，确保包被装到系统路径 /usr/local/lib/python3.x/dist-packages/。 |
运行时提示 libblas.so.3 等库找不到 |
缺少 BLAS/LAPACK 等数值库 | 执行 sudo apt-get install libopenblas-base liblapack3 安装缺失的库。 |
nvidia-smi 显示驱动正常，但 nvcc -V 提示找不到 |
CUDA Toolkit 未安装（pip 安装不需要） | pip 安装的 PyTorch 自带 CUDA 运行时，不需要单独安装 CUDA Toolkit，所以 nvcc 找不到是正常的，不用担心。 |
🎯 方案二：Conda 安装（备选方案）
如果你习惯使用 Conda 管理环境，或者需要同时维护多个不同 PyTorch 版本的项目，Conda 也是一个可靠的选择。但需要注意：Conda 会额外占用约 1-2 GB 的磁盘空间，且官方渠道的 CUDA 版本更新较慢。
准备工作
① 安装 Miniconda（如未安装）
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
# 按提示操作，安装完成后关闭并重新打开终端
② 创建独立环境（推荐）
conda create -n torch_env python=3.10
conda activate torch_env
💡 提示：为每个项目创建独立环境是最佳实践，可以避免不同项目之间的依赖冲突。
③ 配置国内镜像源（强烈推荐）
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/
conda config --set show_channel_urls yes
⚠️ 注意：不要添加已废弃的
pkgs/free频道，否则可能导致依赖解析缓慢或安装到过时版本。
安装步骤
访问 PyTorch 官网，选择：
- PyTorch Build: Stable
- Your OS: Linux
- Package: Conda
- Language: Python
- Compute Platform: 选择与你驱动兼容的 CUDA 版本
页面生成的命令示例：
# CUDA 12.1（Conda 官方当前最高支持版本）
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia
⚠️ 重要：截至 2025 年 6 月，Conda 官方渠道最高仅支持到
pytorch-cuda=12.1。若你需要 CUDA 12.8 等更高版本，请使用方案一（pip 安装）。
如果 Conda 在解决依赖时卡住（显示 "Solving environment" 很久），可以安装 mamba 加速：
conda install mamba -n base -c conda-forge
mamba install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia
验证安装
与方案一相同，在激活的 Conda 环境中运行 Python 验证：
import torch
print("PyTorch 版本:", torch.__version__)
print("CUDA 是否可用:", torch.cuda.is_available())
if torch.cuda.is_available():
print("torch.version.cuda:", torch.version.cuda)
print("GPU 设备名称:", torch.cuda.get_device_name(0))
Conda 方案常见问题
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
conda install 提示找不到 pytorch-cuda=12.8 |
Conda 官方渠道最高仅支持 CUDA 12.1 | 改用方案一（pip 安装），或降级使用 pytorch-cuda=12.1。 |
| 安装过程卡在 "Solving environment" | Conda 的 SAT 求解器处理复杂依赖耗时较长 | 使用 mamba 替代，或改用 pip 安装。 |
torch.cuda.is_available() 返回 False |
Conda 环境未正确激活，或 pytorch-cuda 包未安装 |
① 确认已执行 conda activate torch_env。② 检查已安装的包： conda list \| grep pytorch-cuda，若缺失则重装。 |
| 清华镜像源下载失败 | 镜像源不稳定或配置错误 | ① 检查配置：conda config --show channels。② 临时使用官方源： conda install pytorch ... -c pytorch -c nvidia --override-channels。 |
💎 最终总结
| 对比维度 | 方案一：pip 全局安装 | 方案二：Conda 安装 |
|---|---|---|
| 磁盘占用 | 小（仅 PyTorch 本身） | 大（额外 1-2 GB 基础环境） |
| CUDA 版本 | 支持最新版本（如 12.8） | 官方最高支持 12.1 |
| 环境隔离 | 无（全局生效） | 支持多环境隔离 |
| 上手难度 | 简单，一行命令 | 需先安装 Conda，学习基本命令 |
| 适用场景 | 单一视觉开发任务 | 多项目、多版本 PyTorch 并存 |
个人推荐：对于绝大多数视觉开发者，方案一（pip 全局安装） 是最简单、最省心的选择。除非你需要同时维护多个不同 PyTorch 版本的项目，否则完全没必要引入 Conda 的复杂度。
📦 第五步：安装 NVIDIA TensorRT
📌 安装适配提醒
TensorRT 版本必须与你已安装的 CUDA 版本精确匹配。错误的版本组合会导致安装失败或运行时错误。
建议操作：
- 通过
nvcc --version确认你的 CUDA 版本。- 访问 NVIDIA TensorRT 官方下载页面，根据你的 Ubuntu 22.04、CUDA 版本选择匹配的 TensorRT 版本。
- 将你的 CUDA 版本告诉 AI 助手，询问推荐安装的 TensorRT 版本及对应的 deb 包名称。
- 下文中的
nv-tensorrt-local-repo-ubuntu2204-10.x.x、tensorrt=10.x.x.x-1+cuda12.x等均为示例，请替换为你实际下载的文件名和版本号。- 重要：下文中的密钥路径仅为示例，实际执行
dpkg -i后终端会直接输出正确的 GPG 密钥复制命令，请以终端输出为准，不要盲目复制文中的示例路径。
⚠️ 重要提示：本文档为示例安装指南，旨在提供通用的安装思路和步骤参考。不同设备（显卡型号、CUDA版本、系统环境）需要安装的TensorRT版本可能完全不同。请务必在动手之前，先访问NVIDIA TensorRT官方下载页面，确认与你当前环境（Ubuntu版本、CUDA版本、cuDNN版本）完全匹配的TensorRT版本，再参照本文档的方法进行安装。版本不匹配是导致安装失败和运行时错误的最常见原因。
TensorRT 是 NVIDIA 推出的高性能深度学习推理优化器和运行时引擎。它可以将训练好的 PyTorch、TensorFlow 等模型进行极致优化，使推理速度提升数倍甚至数十倍，是视觉开发中模型部署和加速的关键环节。
TensorRT 提供了多种安装方式，官方推荐根据开发场景选择：
| 安装方式 | 适用场景 | 是否需要root | C++支持 | 安装速度 |
|---|---|---|---|---|
| pip (Python) | Python开发、快速原型验证 | 否 | 否 | ⚡ 最快（约2分钟） |
| Debian/RPM | 系统级安装、需要C++开发 | 是 | 是 | 快（约5分钟） |
| Tar/Zip | 多版本共存、无root权限安装 | 否 | 是 | 中等（约10分钟） |
| NGC Container | 隔离环境、Kubernetes部署 | 否（需Docker） | 是 | ⚡ 最快（约5分钟） |
对于 Ubuntu 22.04 视觉开发环境，推荐使用 Debian 本地仓库包（deb 包） 进行安装。这种方式能自动处理大部分依赖、提供完整的C++开发支持，且便于后续的更新和卸载。
准备工作
① 确认版本兼容性
TensorRT 必须与你之前安装的 CUDA 和 cuDNN 版本精确匹配。在下载之前，请先访问 NVIDIA TensorRT 官方下载页面，根据你的环境选择匹配的版本。
以下为常见版本组合参考（基于 Ubuntu 22.04 x86_64）：
| TensorRT 版本 | 支持的 CUDA 版本 | 建议搭配 |
|---|---|---|
| TensorRT 10.x | CUDA 12.x | 适合 RTX 30/40/50 系列显卡 |
| TensorRT 8.6.x | CUDA 12.0 ~ 12.2 | 稳定版本，广泛兼容 |
| TensorRT 8.5.x | CUDA 11.x | 适合 GTX 10/16 系列旧显卡 |
💡 提示：官方提供了详细的支持矩阵，你可以在上面查询各版本之间的精确兼容关系。
② 检查已安装的 CUDA 版本
执行以下命令确认你的 CUDA 版本：
nvcc --version
记下 CUDA 的主版本号（例如 12.4、12.5），后续下载 TensorRT deb 包时必须选择对应的 CUDA 版本。
③ 注册 NVIDIA 开发者账号
TensorRT 的下载需要登录 NVIDIA 开发者账号。访问 NVIDIA TensorRT 下载页面，完成登录后才能获取 deb 包的下载链接。
下载 TensorRT deb 包
- 访问 NVIDIA TensorRT 下载页面
- 选择与你系统匹配的选项：
- TensorRT Version: 选择最新稳定版（如 10.x）
- Operating System: Linux
- Architecture: x86_64
- Distribution: Ubuntu
- Ubuntu Version: 22.04
- CUDA Version: 选择与你已安装 CUDA 版本匹配的选项（如 CUDA 12.x）
- 选择 Debian Local Repo Package 进行下载
下载后得到一个类似 nv-tensorrt-local-repo-ubuntu2204-10.x.x_1.0-1_amd64.deb 的文件。
安装 TensorRT（deb 包方式）
步骤 1：安装本地仓库包
进入下载目录，使用 dpkg 安装 deb 包：
cd ~/Downloads
sudo dpkg -i nv-tensorrt-local-repo-ubuntu2204-10.x.x_1.0-1_amd64.deb
这个步骤只是将 TensorRT 的本地仓库添加到系统中，实际文件会被解压到 /var/nv-tensorrt-local-repo-ubuntu2204-10.x.x/ 目录下。
这里的这个密钥在执行完上面的步骤都是会在终端里面输出出来的所以下面的这个只做实例说明，不要直接粘贴使用，这个必须根据设备还有驱动来选择
步骤 2：导入 GPG 密钥并更新软件源
# 复制 GPG 密钥到系统密钥目录
sudo cp /var/nv-tensorrt-local-repo-ubuntu2204-10.x.x/*.pub /usr/share/keyrings/
# 更新软件源
sudo apt update
步骤 3：安装 TensorRT
⚠️ 关键提醒：执行以下命令时，请务必仔细阅读命令输出，确认
apt不会自动拉取 NVIDIA 驱动包。TensorRT 的 deb 仓库中可能包含驱动相关的依赖，如果系统检测到驱动版本不匹配，可能会尝试覆盖你之前精心安装的 NVIDIA 驱动，导致环境崩溃。
sudo apt install tensorrt
📌 说明：
sudo apt install tensorrt安装的是完整版运行时（Full Runtime），包含 Builder 和 Runtime 功能，可以构建和优化模型，适合开发环境使用，体积约 2GB。如果你只需要运行预构建的引擎（纯部署场景），可以选择体积更小的版本：
- Lean Runtime（约 500MB）：
sudo apt install tensorrt-lean- Dispatch Runtime（约 200MB）：
sudo apt install tensorrt-dispatch
步骤 4：安装 Python 绑定（如需要在 Python 中使用 TensorRT）
TensorRT 的 Python 包由两部分组成：tensorrt 元包和 tensorrt-bindings 底层绑定。pip install tensorrt 有时不会自动安装 tensorrt-bindings，导致导入时报错 ModuleNotFoundError: No module named 'tensorrt_bindings'。因此，建议同时安装两个包：
pip3 install tensorrt tensorrt-bindings
如果你只安装了 pip 版本而没有通过 apt 安装系统级的 TensorRT 库，运行时可能会提示缺少 libnvinfer.so 等共享库文件。通过 apt 安装完整的 TensorRT 系统包可以避免此问题。
可选：pip 快速安装（仅 Python 开发）
如果你只需要 Python 环境、不需要 C++ 开发支持，也可以直接用 pip 安装 TensorRT（无需 root 权限，约 2 分钟即可完成）：
pip3 install --upgrade pip
pip3 install tensorrt
如果使用 lean 或 dispatch 运行时，可以安装对应的 pip 包：
pip3 install tensorrt-lean # 仅运行预构建引擎
pip3 install tensorrt-dispatch # 最小化部署
如果你需要指定 CUDA 版本，可以添加 -cu12 后缀：
pip3 install tensorrt-cu12
配置环境变量
通过 deb 包安装 TensorRT 后，库文件和可执行文件会被自动放到系统标准路径中，通常无需额外配置环境变量：
- 库文件：
/usr/lib/x86_64-linux-gnu/ - 可执行文件（如
trtexec）：/usr/bin/trtexec
/usr/bin/ 已在系统 PATH 中，因此 trtexec 可以直接调用，无需额外配置。
💡 注意：部分旧版教程中可能会提到
/usr/src/tensorrt/bin/trtexec路径。/usr/src/tensorrt/是存放示例源代码的目录，而非可执行文件的安装位置。如果你需要编译示例程序，源代码位于/usr/src/tensorrt/samples/。
验证 TensorRT 安装
方法 1：检查版本信息
# 检查 TensorRT 库版本
dpkg -l | grep tensorrt
# 检查 Python 绑定版本（如已安装）
python3 -c "import tensorrt; print(tensorrt.__version__)"
方法 2：运行 trtexec 工具
trtexec 是 TensorRT 自带的命令行工具，安装后位于 /usr/bin/trtexec（已在系统 PATH 中），直接运行即可：
trtexec --help
如果命令未找到，说明 deb 包安装可能未完成，请检查 dpkg -l | grep tensorrt 的输出。
方法 3：编译并运行官方示例（更严格的验证）
# 进入 TensorRT 示例源代码目录
cd /usr/src/tensorrt/samples
# 编译所有示例
sudo make -j$(nproc)
# 进入编译输出目录
cd ../bin
# 运行 sample_mnist 示例
./sample_mnist
如果运行成功，你会在输出末尾看到类似以下信息：
&&&& PASSED TensorRT.sample_mnist
这表示 TensorRT 环境已经能够正常调用 GPU 进行推理加速了。
常见问题与排坑指南
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 安装 TensorRT 后 NVIDIA 驱动被覆盖或失效 | TensorRT 的 deb 仓库自动拉取了驱动包，覆盖了原有的驱动 | 安装前务必查看 apt install 将要安装的包列表，如果发现包含 nvidia-driver-* 相关包，需手动排除。如已发生，重新安装之前版本的 NVIDIA 驱动。 |
pip install tensorrt 后 import tensorrt 报错 ModuleNotFoundError: No module named 'tensorrt_bindings' |
pip 安装时未自动安装 tensorrt-bindings 包 |
手动安装 bindings：pip3 install tensorrt-bindings，建议直接使用 pip3 install tensorrt tensorrt-bindings。 |
trtexec 命令找不到 |
deb 包安装未完成，或使用了仅 pip 安装方式（pip 安装不包含 trtexec） |
检查 dpkg -l \| grep tensorrt 确认 deb 包安装状态；如果只用 pip 安装，trtexec 不会安装，需通过 apt 补充安装系统包。 |
Python 中 import tensorrt 报错 libnvinfer.so.10 找不到 |
只通过 pip 安装了 Python 包，系统级 TensorRT 库未安装 | 通过 apt 安装完整的 TensorRT 系统包：sudo apt install tensorrt。 |
运行示例时提示 cuda.h 找不到 |
CUDA 开发头文件未正确安装或路径未配置 | 确保 CUDA Toolkit 已正确安装，且头文件路径可访问。 |
| 下载 deb 包时找不到对应 CUDA 版本的选项 | 官网页面选项组合不存在 | 在下载页面的"Archived Releases"区域查找历史版本，或选择接近的 CUDA 版本（同大版本通常兼容）。 |
sudo apt update 时提示 GPG 密钥错误 |
密钥文件未正确复制或路径错误 | 重新执行 sudo cp /var/nv-tensorrt-local-repo-*/*.pub /usr/share/keyrings/，然后 sudo apt update 重试。 |
💎 总结
- 安装时机：TensorRT 必须在 NVIDIA 驱动、CUDA 和 cuDNN 全部安装完成之后安装。
- 版本匹配是关键：TensorRT 版本必须与你已安装的 CUDA 主版本兼容（例如 CUDA 12.x 对应 TensorRT for CUDA 12.x）。务必先在官网确认兼容性后再下载安装。
- 推荐方式：首选 Debian 本地仓库包（deb 包），能自动处理大部分依赖，且提供完整的 C++ 开发支持。
- Python 绑定：安装时使用
pip install tensorrt tensorrt-bindings同时安装两个包，避免运行时缺少 bindings 模块。 - 关键提醒：安装时注意不要被 TensorRT 的依赖覆盖了已有驱动，执行
apt install前先确认包列表。 - 路径说明：deb 包安装后，
trtexec位于/usr/bin/trtexec，无需额外配置环境变量；源代码和示例位于/usr/src/tensorrt/samples/。 - 验证成功：运行
trtexec --help或编译示例程序能正常工作，即表示安装成功。 - 后续步骤：TensorRT 安装完成后，可以开始将 PyTorch 等框架训练好的模型转换为 TensorRT 引擎，享受极致的推理加速。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
15
0- 0
已为社区贡献2条内容
所有评论(0)