在 GPU 服务器上编译 llama.cpp 时遇到 Could not find nvcc 报错，才发现 nvidia-smi 显示 CUDA 12.2 并不代表装了 CUDA Toolkit。本文用一张图讲清三者关系。

一句话总结

• NVIDIA Driver = 让系统识别 GPU 的驱动程序
• CUDA Version（nvidia-smi 显示的）= 驱动最高兼容的 CUDA 版本，不代表已安装
• CUDA Toolkit = 编译 GPU 程序所需的开发工具包（nvcc 编译器 + 库 + 头文件）

三层架构

各层职责

1. NVIDIA Driver（GPU 驱动）

操作系统与 GPU 硬件之间的桥梁。

包含组件	作用
nvidia-smi	查看 GPU 状态、温度、显存
libcuda.so	CUDA 运行时底层库

装好驱动后 nvidia-smi 就能用，但不能编译 CUDA 程序。

2. CUDA Version（nvidia-smi 右上角的数字）

+-----------------------------------------------+
| NVIDIA-SMI 535.288.01   CUDA Version: 12.2    |
+-----------------------------------------------+

这个 CUDA Version: 12.2 是驱动声明的最高兼容版本，含义是：

• 该驱动的 API 兼容 CUDA 12.2 及以下版本
• 不代表你安装了 CUDA Toolkit
• 不代表你有 nvcc 编译器

这是最容易踩的坑——看到这个数字就以为万事俱备了。

3. CUDA Toolkit（开发工具包）

编译 GPU 加速程序的完整工具链，需要单独安装。

包含组件	作用
nvcc	CUDA 编译器，CMake 找的就是它
头文件	cuda.h、cuda_runtime.h 等
数学库	cuBLAS、cuDNN、cuRAND 等
示例代码	CUDA samples

版本兼容规则

驱动版本 → 决定能支持的 Toolkit 最高版本（向下兼容）

Driver 535.x  最高支持 CUDA Toolkit 12.2
              也兼容 12.1, 12.0, 11.8, 11.7 ...

Driver 550.x  最高支持 CUDA Toolkit 12.4
              也兼容 12.3, 12.2, 12.1 ...

核心原则：Toolkit 版本 ≤ 驱动声明的 CUDA Version。

NVIDIA 官方兼容表：CUDA Toolkit Release Notes

实际报错场景

编译 llama.cpp 开启 -DGGML_CUDA=ON 时：

-- Could not find nvcc, please set CUDAToolkit_ROOT.
CMake Error at ggml/src/ggml-cuda/CMakeLists.txt:258 (message):
  CUDA Toolkit not found

原因就是：有驱动、有 GPU，但没装 CUDA Toolkit。

解决方案

Step 1：确认驱动支持的 CUDA 版本

nvidia-smi | head -3
# 看右上角 CUDA Version，比如 12.2

Step 2：安装对应版本的 CUDA Toolkit

以 CUDA 12.2 + Ubuntu 22.04 为例：

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
dpkg -i cuda-keyring_1.1-1_all.deb
apt-get update
apt-get install -y cuda-toolkit-12-2

Step 3：配置环境变量

export PATH=/usr/local/cuda-12.2/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.2/lib64:$LD_LIBRARY_PATH

# 验证
nvcc --version
# 应输出: release 12.2

建议写入 ~/.bashrc 持久化：

echo 'export PATH=/usr/local/cuda-12.2/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.2/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc

Step 4：编译 llama.cpp（附带实战验证）

从零开始编译，验证 CUDA 加速是否生效：

# 安装编译依赖
apt-get update
apt-get install -y pciutils build-essential cmake curl libcurl4-openssl-dev

# 克隆源码
git clone --depth 1 https://github.com/ggml-org/llama.cpp

# 编译（开启 CUDA 加速）
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=OFF \
    -DGGML_CUDA=ON

cmake --build llama.cpp/build --config Release -j$(nproc) \
    --clean-first \
    --target llama-cli llama-server llama-gguf-split

# 验证产物
ls llama.cpp/build/bin/llama-*

如果编译顺利通过且没有 CUDA Toolkit not found 报错，说明一切就绪。

一张表记住

组件	安装后能做什么	典型命令/文件
NVIDIA Driver	识别 GPU、查看状态	nvidia-smi
CUDA Toolkit	编译 GPU 程序	nvcc --version
应用（llama.cpp 等）	跑 GPU 推理	llama-server

三者缺一不可，自底向上依次依赖。

---

环境：Ubuntu 22.04 / NVIDIA Driver 535.288.01 / CUDA 12.2 / L20 48GB