5 分钟一键安装 NVIDIA CUDA Toolkit

# 前言

为什么我们要安装 CUDA Toolkit？对 AI 开发者/学习者而言，安装 CUDA Toolkit 不是选择题，而是项目启动的必要前提：

PyTorch/TensorFlow 等 AI 框架启动时自动检测 CUDA Toolkit，而绝大多数的 AI 项目都基于这些基础框架

• ✅ CUDA Runtime 已安装 → 调用 GPU 加速，计算速度显著提升
• ❌ CUDA Runtime 未安装 → 只能使用 CPU 模式，计算速度不及 GPU 十分之一

因此 CUDA Toolkit 的安装成了 AI 学习/部署的第一个门槛。

# 使用 cuda-install.sh 自动安装

当我们手动安装 CUDA Toolkit 的时候，我们需要手动处理系统依赖、版本冲突；特别是对于之前对 Linux 不熟悉的新手而言，这些过程极易出错。因此本教程提供一个开源脚本 cuda-install.sh，能为我们自动完成以下任务：

• ✅ 配置 NVIDIA 官方仓库
• ✅ 自动安装 CUDA Toolkit 所需要的依赖
• ✅ 安装 CUDA Toolkit
• ✅ 可选安装 NVIDIA 容器工具包（用于 Docker GPU 支持）
• ✅ 支持主流 Linux 发行版（Ubuntu/Debian/RHEL/Fedora 等）

## 准备工作

1. 系统要求

   • 确认系统在支持列表中：目前脚本支持 Debian, Ubuntu, Fedora, RHEL, Rocky Linux, Oracle Linux, SLES, OpenSUSE 等发行版自动安装驱动
   • 已安装 NVIDIA 显卡驱动（可通过 nvidia-smi 命令验证），如未安装，可以参考上一篇文章的驱动安装方式

2. 下载脚本 从安全性的角度，我们建议在运行脚本前，提前下载脚本，如果有能力，建议自行对脚本内容进行审阅

   # 从 GitHub 下载安装脚本
   curl -fsSLO 'https://github.com/EM-GeekLab/nvidia-driver-installer/raw/refs/heads/main/cuda-install.sh'
    
   # 从 Gitee 镜像仓库下载安装脚本（适用于国内无法正常访问 GitHub 的用户）
   # curl -fsSLO 'https://gitee.com/EM_GeekLab/nvidia-driver-installer/raw/main/cuda-install.sh'
    
   chmod +x cuda-install.sh  # 添加执行权限

## 安装 CUDA Toolkit 的三种核心场景详解

### 1. 安装最新稳定版 CUDA（推荐新手首选）

执行命令：

sudo ./cuda-install.sh --cuda-version=auto

这是最推荐的安装方式，脚本会根据当前的系统版本配置软件仓库，并使用系统包管理器解析最适合的 CUDA 版本。适用于首次安装 CUDA、不需要特定版本的学习者或仅需要最新版本 CUDA 的用户。

### 2. 安装指定版本 CUDA（应对特殊需求）

执行命令：

sudo ./cuda-install.sh --cuda-version=12-9

⚠️ 注意：版本号格式必须为主版本-次版本（如 12-5、13-0），若输入错误版本（如12.9而非12-9），包管理器会无法匹配到所需的软件包。

典型使用场景：

• 复现论文时需要匹配作者使用的 CUDA 环境
• 生产环境需要固定版本避免兼容问题

### 3. 完整开发环境安装（容器/ Docker 用户必备）

执行命令：

./cuda-install.sh --type=all

这是最全面的安装方案，在安装 CUDA Toolkit 的同时，会自动安装 NVIDIA Container Toolkit，可用于配置 Docker 等容器化工具，用于在容器中使用 CUDA。

⚠️ 注意：容器环境需要进行额外的配置，如 Docker 需要执行以下命令进行配置：

sudo nvidia-ctk runtime configure --runtime=docker && \
sudo systemctl restart docker.service

配置容器工具具体请参考 NVIDIA 官方文档

## 一些额外配置

对于每个需要在命令行中调用如 nvcc 之类工具的用户，还有最后一步需要手动完成：将刚刚安装的 CUDA Toolkit 添加到你的 PATH 中。

如果你使用的 Shell 是 bash/zsh，请在你的 .bashrc/.zshrc 中添加一行：

export PATH="/usr/local/cuda/bin:$PATH"

如果你使用的是 Fish，请添加如下内容到你的配置文件中（通常是 $HOME/.config/fish/config.fish）：

set -gpx PATH "/usr/local/cuda/bin"

然后重启你的 Shell，即可在命令行中使用 nvcc

## 小结

使用此自动安装脚本可将新手安装 CUDA Toolkit 的时间从 1 小时缩短至 5 分钟，同时避免 90% 的常见错误。

但自动脚本难免有考虑不周的情况，建议搭配官方文档使用： 🔗 NVIDIA CUDA Toolkit 文档

如果遇到了脚本无法自动安装的情况，我们也欢迎在 GitHub Issues 中附上安装失败的日志，我们会对脚本的缺陷进行修复： 🔗 GitHub 仓库

# 使用 Conda 安装 CUDA Toolkit

诶，那有同学问了：“请问支持安装多个版本的 CUDA 吗？”

好问题！答案是：“不支持”

这并不是我们偷懒，而没有在脚本里面完善这一功能，而是由于脚本使用系统包管理器进行安装，从而导致了无法避免的依赖冲突问题；虽然有update-alternatives用于切换系统全局安装的 CUDA Toolkit 版本，但更常见的还是无法解决的冲突。

但并不代表就没办法实现多个版本的 CUDA Toolkit 切换了，而是我们需要采取别的方案，从根本上解决问题：使用 Conda 提供的虚拟环境进行安装。

安装 Conda 和 创建虚拟环境的部分我们在此不在赘述，如有需要，我们也可单独开一篇文章进行讲解。我们直奔主题，在激活你的 Conda 虚拟环境后，我们只需要执行以下命令即可完整 CUDA Toolkit 的安装：

conda install -c conda-forge cuda # 安装最新的 CUDA Toolkit
conda install -c conda-forge cuda=12.9.1 # 可以指定需要安装的版本（版本格式 XX.X.X）
conda install -c conda-forge cudnn # （可选）安装最新的 cuDNN

⚠️ 注意：使用 Conda 安装的 CUDA Toolkit 仅在虚拟环境被激活的时候可用，因此在使用前记得激活虚拟环境。

# 总结

综上，我们有两种简便的方式安装 CUDA Toolkit。由于 CUDA Toolkit 本身是软件开发工具，其特殊性决定了它不能像驱动一样实现彻底的傻瓜式安装，而必须结合实际需要选择合适的方案进行安装。

最后，如果我们的一键安装脚本对您有帮助的话，请在 🔗 GitHub 为我们点一个 Star。如果脚本/文章存在问题，也希望您能向我们及时反馈/指正。

# 后记

怎么这么多笔误，呜呜呜呜