目录一、先搞懂 3 个核心概念避坑的前提1. cuda-toolkit ≠ cudatoolkit2. Conda 里的 CUDA ≠ 显卡驱动3. -c nvidia 和 nvidia/label/cuda-12.4.0 不是一回事二、完整安装步骤全程可复现步骤 1配置清华 Conda 镜像源解决国内下载慢步骤 2确定安装的CUDA-Toolkit 版本步骤 3创建独立的开发环境步骤 4安装 CUDA Toolkit 12.4版本锁定版步骤 5安装对应版本的 PyTorch步骤 6安装编译工具链步骤 7部署 LibTorch 2.6CUDA 12.4 版本三、LibTorch C 编译验证1. 编写测试代码2. 编写 CMakeLists.txt3. 编写编译运行脚本四、高频踩坑与解决方案1. 指定 12.4 版本结果还是装了最新版2. 编译时报错 cannot find -lnvToolsExt3. nvcc -V 显示的还是系统 CUDA 版本4. PyTorch 正常LibTorch 编译报 CUDA 版本不匹配五、最佳实践总结做 CUDA C 开发、LibTorch 自定义算子、PyTorch C 部署时由于在conda环境中安装的 CUDAToolkit 安装源不匹配导致后面使用 LibTorch 时一直出现错误折腾了整整一周才算把问题解决遂总结以下出现的问题和正确安装过程使用conda install cuda-toolkit12.4后 cmake 构建时一直识别不到cuda路径明明执行了conda install -c nvidia cuda-toolkit12.4结果装完一看是最新版编译 LibTorch 项目时疯狂报错找不到nvToolsExtPyTorch 跑起来没问题C 编译就说 CUDA 版本不匹配这些问题本质上都是对 conda 的 CUDA 包机制、频道优先级、依赖关系不理解导致的。本文结合实际踩坑经验给出一套从镜像源配置到编译验证的完整流程全程可复现避开一些关键的环境坑。一、先搞懂 3 个核心概念避坑的前提很多人装环境踩坑都是因为没分清几个长得很像的包和概念先理清楚再动手。1.cuda-toolkit≠cudatoolkitcuda-toolkit带横杠NVIDIA 官方发布的完整 CUDA 工具链包含nvcc编译器、CUDA 头文件、运行库、调试工具等是做 CUDA C 开发的必须包。cudatoolkit不带横杠PyTorch 团队打包的 CUDA 运行时依赖只有运行库没有编译器只能用来跑 PyTorch不能用来编译 C 代码。踩坑提醒如果你的目标是编译 LibTorch/CUDA C 代码一定要装带横杠的cuda-toolkit。2. Conda 里的 CUDA ≠ 显卡驱动显卡驱动系统层面的驱动程序决定了你的显卡最高能支持的 CUDA 版本用nvidia-smi查看。Conda 的 cuda-toolkitconda 环境内的开发工具链版本可以低于驱动支持的最高版本向下兼容用nvcc -V查看。简单说驱动是上限conda 里的是实际开发用的版本两者不需要一致。3.-c nvidia和nvidia/label/cuda-12.4.0不是一回事-c nvidiaNVIDIA 的主 conda 频道永远优先放最新版本的 CUDA 包。只写版本号的话conda 的 solver 经常会忽略版本约束直接装最新版。nvidia/label/cuda-12.4.0NVIDIA 的版本锁定标签频道频道里的整套 CUDA 工具链都固定在 12.4 版本是官方指定的安装旧版本 CUDA 的正确方式。这就是“指定 12.4 却装成最新版”的核心原因你用了主频道却想固定旧版本。二、完整安装步骤全程可复现步骤 1配置清华 Conda 镜像源解决国内下载慢默认 conda 源在国外下载速度极慢还容易中断先配置国内镜像。执行以下命令添加清华源# 清华 Anaconda main 源基础包 conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ # 清华 Anaconda r 源R语言相关包 conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r/ # 清华 Anaconda msys2 源Windows 相关工具 conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2/ # 清华 conda-forge 源社区包 conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/配置完成后建议开启严格频道优先级避免不同源的包版本错乱conda config --set channel_priority strict可以用以下命令查看已配置的源确认添加成功conda config --show channels注如果部分镜像地址出现访问异常可前往清华大学开源软件镜像站官网确认最新地址。步骤 2确定安装的CUDA-Toolkit 版本这里假设你的开发硬件上已经安装了NVIDIA驱动通过查看安装的驱动版本确定后面要安装CUDA-Toolkitnvdia-smi----------------------------------------------------------------------------------------- | NVIDIA-SMI 550.127.05 Driver Version: 550.127.05 CUDA Version: 12.4 | |--------------------------------------------------------------------------------------- | GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. | | | | MIG M. | || | 0 NVIDIA GeForce RTX 4080 ... Off | 00000000:06:00.0 On | N/A | | 0% 42C P8 13W / 295W | 106MiB / 16376MiB | 3% Default | | | | N/A | --------------------------------------------------------------------------------------- ----------------------------------------------------------------------------------------- | Processes: | | GPU GI CI PID Type Process name GPU Memory | | ID ID Usage | || | 0 N/A N/A 1822 G /usr/lib/xorg/Xorg 100MiB | -----------------------------------------------------------------------------------------可以看到我的设备最高支持的CUDA版本为 12.4这里我选择安装的 CUDA-Toolkit 为12.4步骤 3创建独立的开发环境强烈建议新建一个干净的 conda 环境不要在 base 环境里堆各种版本的依赖。这是避免“指定版本被强制升级”的关键——如果环境里已经有高版本的pytorch-cudaconda 会自动把cuda-toolkit拉高到匹配的版本。# 创建名为 cuda_dev 的环境指定 Python 3.11兼容性最佳 conda create -n cuda_dev python3.11 # 激活环境 conda activate cuda_dev步骤 4安装 CUDA Toolkit 12.4版本锁定版❌错误写法# 从 conda 官方下载的 CUDA-Toolkit 内容可能不全且环境变量设置不对导致 cmake 构建时识别不到 cuda 路径 conda install cuda-toolkit12.4 # 从NVIDIA官方下载的 CUDA-Toolkit 是正确的且可以识别但是版本约束很弱大概率装成最新版这会与后面的 libtorch 不兼容 conda install -c nvidia cuda-toolkit12.4✅正确写法官方推荐版本绝对锁定# 官方下载时一定要确保版本锁定否则后面构建链接 libtorch 时会出错 conda install nvidia/label/cuda-12.4.0::cuda-toolkit -c nvidia/label/cuda-12.4.0 --yes命令说明nvidia/label/cuda-12.4.0::cuda-toolkit强制cuda-toolkit这个包必须来自 12.4 标签频道-c nvidia/label/cuda-12.4.0将该标签频道加入本次安装的搜索源安装完成后验证版本是否正确nvcc -V nvcc: NVIDIA (R) Cuda compiler driver Copyright (c) 2005-2024 NVIDIA Corporation Built on Tue_Feb_27_16:19:38_PST_2024 Cuda compilation tools, release 12.4, V12.4.99 Build cuda_12.4.r12.4/compiler.33961263_0输出中包含release 12.4就说明安装成功。一定要用nvcc -V验证不要看nvidia-smi。步骤 5安装对应版本的 PyTorch安装和 CUDA 12.4 匹配的 PyTorch 套件注意pytorch-cuda的版本必须和cuda-toolkit对齐conda install pytorch torchvision torchaudio pytorch-cuda12.4 -c pytorch -c nvidia踩坑提醒不要省略pytorch-cuda12.4的版本号也不要写更高的版本否则会自动升级 CUDA 工具链之前的版本锁定就失效了。验证 PyTorch 的 CUDA 可用性python -c import torch; print(CUDA可用:, torch.cuda.is_available()); print(CUDA版本:, torch.version.cuda)输出True且版本为 12.4即为正常。步骤 6安装编译工具链LibTorch C 项目需要 CMake 和构建工具直接在 conda 环境内安装即可conda install cmake ninja make -yninja比传统make更快的构建工具推荐搭配 CMake 使用。步骤 7部署 LibTorch 2.6CUDA 12.4 版本根据自己安装的 CUDA-Toolkit 版本从 PyTorch 官网下载对应版本的 LibTorch 包libtorch-cxx11-abi-shared-with-deps-2.6.0cu124.zip链接https://download.pytorch.org/libtorch/cu124/libtorch-cxx11-abi-shared-with-deps-2.6.0%2Bcu124.zip注意选对cxx11 ABI、shared 版本、带依赖、CUDA 12.4解压到你创建的环境目录下我的环境路径时/anaconda3/envs/cuda_dev/unzip libtorch-cxx11-abi-shared-with-deps-2.6.0cu124.zip解压后会得到libtorch文件夹内含include、lib、share等目录。三、LibTorch C 编译验证环境装完好不好用跑一个最小测试项目就知道。1. 编写测试代码新建main.cpp#include torch/torch.h #include iostream int main() { // 创建随机 Tensor 并移到 GPU torch::Tensor tensor torch::rand({2, 3}).cuda(); std::cout GPU 上的 Tensor:\n tensor std::endl; // 打印 CUDA 状态 std::cout \nCUDA 是否可用: torch::cuda::is_available() std::endl; std::cout CUDA 设备数量: torch::cuda::device_count() std::endl; return 0; }2. 编写 CMakeLists.txt重点是强制 CMake 使用 conda 环境内的 CUDA避免它自动找到系统里的其他 CUDA 版本。cmake_minimum_required(VERSION 3.15) # 项目名称、版本、语言 project(HelloWorld VERSION 1.0.0 DESCRIPTION My first CMake project LANGUAGES CXX ) find_package(CUDA REQUIRED) find_package(Torch REQUIRED) message(------------------------------------------------------------) # 检查 CUDA 相关路径是否正确 message(STATUS CUDA Found: ${CUDA_FOUND}) message(STATUS CUDA Toolkit Root: ${CUDA_TOOLKIT_ROOT_DIR}) message(STATUS CUDA Include Dir: ${CUDA_INCLUDE_DIRS}) message(STATUS CUDA Library Dir: ${CUDA_LIBRARIES}) message(STATUS CUDA Runtime Library: ${CUDA_CUDART_LIBRARY}) message(STATUS CUDA nvcc Executable: ${CUDA_NVCC_EXECUTABLE}) # 检测项目相关路径是否正确 message(STATUS PROJECT_NAME:${PROJECT_NAME}) # MyProject message(STATUS PROJECT_VERSION:${PROJECT_VERSION}) # 1.2.3 message(STATUS PROJECT_VERSION_MAJOR:${PROJECT_VERSION_MAJOR}) # 1 message(STATUS PROJECT_VERSION_MINOR:${PROJECT_VERSION_MINOR}) # 2 message(STATUS PROJECT_VERSION_PATCH:${PROJECT_VERSION_PATCH}) # 3 message(STATUS PROJECT_SOURCE_DIR:${PROJECT_SOURCE_DIR}) # 项目根目录 message(STATUS PROJECT_BINARY_DIR:${PROJECT_BINARY_DIR}) # 构建目录 # 检查 LibTorch 相关路径是否正确 message(STATUS TORCH_INCLUDE_DIRS: ${TORCH_INCLUDE_DIRS}) message(STATUS TORCH_LIBRARIES: ${TORCH_LIBRARIES}) message(------------------------------------------------------------) # 创建可执行文件目标 add_executable(demo main.cpp) # 链接libtorch库 target_link_libraries(demo PRIVATE ${TORCH_LIBRARIES}) # C17是libtorch强制要求 target_compile_features(demo PRIVATE cxx_std_17) # Linux下libtorch需要RTTI、异常开关默认一般打开 #set(CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS} ${TORCH_CXX_FLAGS})3. 编写编译运行脚本rebuild.sh# 新建 build 目录rm-rfbuildmkdirbuildcdbuild cmake..\-DCMAKE_PREFIX_PATH/data/anaconda3/envs/cuda_dev/libtorchmake-j$(nproc)然后运行编译好的可执行程序./build/demo GPU 上的 Tensor:0.81650.01790.93220.41210.14420.9533[CUDAFloatType{2,3}]CUDA 是否可用:1CUDA 设备数量:1正常运行会输出 2x3 的随机张量以及 CUDA 可用状态说明整个开发环境配置完成。四、高频踩坑与解决方案1. 指定 12.4 版本结果还是装了最新版原因用了-c nvidia主频道solver 优先最新版或者环境里已有高版本pytorch-cuda依赖解决改用nvidia/label/cuda-12.4.0标签频道新建干净环境先装 CUDA再装 PyTorch2. 编译时报错cannot find -lnvToolsExt原因用了 conda-forge 源的cuda-toolkit组件阉割缺少 nvToolsExt 库解决卸载旧包用 NVIDIA 官方 label 频道的cuda-toolkit重新安装3.nvcc -V显示的还是系统 CUDA 版本原因conda 环境变量未生效或者系统 PATH 优先级高于 conda解决重新执行conda activate cuda_dev检查echo $PATH确保 conda 环境的bin目录在最前面4. PyTorch 正常LibTorch 编译报 CUDA 版本不匹配原因CMake 自动找到了系统里的 CUDA没用到 conda 环境内的解决在CMakeLists.txt开头显式指定CMAKE_CUDA_COMPILER和CUDAToolkit_ROOT为 conda 环境路径五、最佳实践总结环境隔离每个 CUDA 版本对应一个独立 conda 环境不要在 base 环境混用版本锁定固定 CUDA 版本一律用nvidia/label/cuda-x.x.x标签频道不要只写版本号安装顺序先装 CUDA Toolkit再装 PyTorch最后装其他依赖反向容易导致版本升级显式指定C 编译时显式指定 CUDA 路径不要依赖 CMake 的自动查找国内镜像优先配置国内镜像源提升下载速度和稳定性这套流程亲测可以稳定复现 CUDA 12.4 LibTorch 2.6 的开发环境解决了版本漂移、组件缺失、编译链接错误等常见问题。如果是做 LibTorch 扩展、CUDA 自定义算子开发这个环境可以直接作为基础环境使用。