文档

CUDA Toolkit 安装 ​

cuda-toolkit-install.sh用于在主流Linux发行版安装系统级CUDA Toolkit，可同时保留多个CUDA 12.x版本

imrouter 节点优先使用私有 Toolkit

普通节点推荐执行./imrouter cuda install，将Toolkit安装到节点同级的runtime/cuda/，无需root权限且不会修改系统环境。本页脚本适用于还需要全局nvcc、开发头文件或/usr/local/cuda的机器

1. 使用前须知 ​

脚本仅支持Linux x86_64，可识别Ubuntu 20.04/22.04/24.04、Debian 11/12、RHEL系8/9、openSUSE/SLES；Fedora、Arch、Manjaro及未适配仓库的发行版会使用NVIDIA runfile

系统级安装需要root权限。默认只安装Toolkit，不修改已有NVIDIA驱动；如果机器还没有可用驱动，建议先阅读NVIDIA 显卡驱动安装

WSL可以使用本脚本安装Toolkit，但驱动必须由Windows宿主机提供，--with-driver在WSL中会被忽略

2. 下载并检查脚本 ​

bash
mkdir -p ~/imrouter-installers
cd ~/imrouter-installers
curl -fL https://www.imrouter.com/docs/scripts/cuda-toolkit-install.sh \
  -o cuda-toolkit-install.sh
chmod +x ./cuda-toolkit-install.sh
bash ./cuda-toolkit-install.sh --help

建议先阅读帮助信息并确认目标版本，再使用sudo执行。runfile安装包约3至4GB，应预留足够的/tmp和/usr/local空间

3. 选择 Toolkit 版本 ​

目标Toolkit不能超过当前驱动支持范围：

CUDA Toolkit最低驱动分支
12.2、12.4、12.6525
12.8535
12.9550

先检查当前驱动：

bash
nvidia-smi

nvidia-smi右上角的CUDA Version表示驱动最高支持的CUDA Runtime版本，不代表系统已经安装对应的CUDA Toolkit。Toolkit是否安装应使用nvcc --version检查

4. 执行安装 ​

交互式安装，默认选择CUDA Toolkit 12.9和仓库方式：

bash
sudo bash ./cuda-toolkit-install.sh

非交互安装默认版本：

bash
sudo bash ./cuda-toolkit-install.sh --yes

指定CUDA Toolkit 12.8：

bash
sudo bash ./cuda-toolkit-install.sh \
  --version 12.8 \
  --yes

指定runfile方式：

bash
sudo bash ./cuda-toolkit-install.sh \
  --version 12.8 \
  --method runfile \
  --yes

同时安装或升级驱动：

bash
sudo bash ./cuda-toolkit-install.sh \
  --version 12.9 \
  --with-driver \
  --yes

需要精确选择驱动分支或内核模块形态时，应先使用驱动专用脚本安装驱动，再运行Toolkit脚本，不要使用--with-driver

默认仓库缺少目标旧版本时，脚本会自动切换到runfile。已经安装相同版本时默认跳过；需要覆盖重装可增加--force

5. 环境变量和多版本共存 ​

不同版本分别安装在：

text
/usr/local/cuda-12.2
/usr/local/cuda-12.4
/usr/local/cuda-12.6
/usr/local/cuda-12.8
/usr/local/cuda-12.9

/usr/local/cuda软链接指向最后安装的版本。脚本会写入/etc/profile.d/cuda.sh，重新登录后环境变量自动生效；当前会话可以执行：

bash
source /etc/profile.d/cuda.sh

手动切换当前系统版本：

bash
sudo ln -sfn /usr/local/cuda-12.8 /usr/local/cuda
source /etc/profile.d/cuda.sh

切换软链接不会删除其他已安装版本

6. 验证安装 ​

bash
nvcc --version
readlink -f /usr/local/cuda
nvidia-smi

nvcc --version应显示目标Toolkit版本，nvidia-smi应正常显示GPU和驱动信息。若nvcc存在但CUDA程序提示驱动版本不足，应升级驱动或切换到驱动支持的较低Toolkit版本

如果只为imrouter节点准备运行环境，也可以跳过系统级安装，按照节点接入与管理使用节点自带的CUDA安装命令

imrouter 文档

Copyright © 2026 imrouter