我先把话放这儿凡是装了半天 detectron2 最后卡在 CUDA 和 PyTorch 对不上的人十有八九不是代码问题是版本矩阵问题。最近我在 CUDA 12.8 环境下配 PyTorch 2.8 detectron2原以为半小时搞定结果还是被几个细节点绊了一跤。这篇文章就是把我实际踩过的坑、验证过的命令、以及最后稳定跑起来的方案完整记录下来给同样被这套组合折磨的人一条能直接照抄的路。1. 装之前先把版本关系理清楚1.1 为什么 detectron2 对版本这么敏感detectron2 不是普通的 pip 包。它里面大量算子是用 CUDA 扩展写的编译的时候必须直接跟 PyTorch 的 C/CUDA 接口打交道。也就是说它并不是“装好就能用”的纯 Python 库而是在安装时根据你当前的 PyTorch 版本、CUDA 版本、GCC 版本现场生成二进制代码。这就带来一个连锁反应PyTorch 2.8 如果是在 CUDA 12.8 上编译的那 detectron2 在编译时也必须找到同一套 CUDA 工具链。如果你只装了 PyTorch 自带的 CUDA 运行库而没有系统层面的 CUDA Toolkit源码编译时CUDA_HOME找不到或者头文件版本不对立刻就会报一堆fatal error: cuda_runtime.h: No such file or directory。另一个点是 ABI 兼容。PyTorch 每个版本对 C ABI比如_GLIBCXX_USE_CXX11_ABI有固定要求detectron2 扩展编译时如果和你当前 PyTorch 的 ABI 不一致导入时就会报undefined symbol这种问题基本只能靠重新编译解决。1.2 版本匹配的基本逻辑先说结论CUDA 12.8 PyTorch 2.8 detectron2 是能跑的但必须满足下面这套对应关系。组件推荐版本关键说明NVIDIA 驱动Linux 550.54.14 或更高驱动必须支持 CUDA 12.8用nvidia-smi验证CUDA Toolkit12.8编译 detectron2 时需要nvcc和头文件PyTorch2.8.0安装时选择 cu128 轮子对应 CUDA 12.8Python3.9 ~ 3.12太老的新版 PyTorch 不兼容太新的可能影响常用第三方库GCC/G11 或更低CUDA 12.8 的 nvcc 对 GCC 13 支持有警告容易踩坑显卡架构Ampere/Ada/Hopper/Blackwell编译时需要指定TORCH_CUDA_ARCH_LIST这里面最容易被忽略的是 GCC 版本。CUDA 12.8 官方文档里明确列出了支持的 GCC 范围如果你系统默认 GCC 是 13那nvcc虽然能跑但会出警告而且 detectron2 某些算子编译时会报奇怪的模板错误。我建议直接用 GCC 11省心。还有一点你要是只看nvidia-smi里显示的 CUDA Version那只是驱动支持的版本上限并不代表你系统里装了对应的 CUDA Toolkit。很多人以为驱动显示 12.8 就万事大吉结果一编译就找不到nvcc。记住一句话驱动归驱动Toolkit 归 Toolkit两个都得有。2. 环境准备驱动与 CUDA Toolkit2.1 确认显卡驱动是否支持 CUDA 12.8先别急着装东西花两分钟确认驱动。终端里运行nvidia-smi看右上角的 CUDA Version这个数字表示当前驱动最高能支持到哪个 CUDA 版本。如果显示 12.8 或更高那驱动这关就过了。如果显示低于 12.8你得先升级驱动否则后面即使装了 PyTorch 也会在运行时报告驱动不兼容。另外在 Windows WSL2 环境里有一个常见认知误区WSL2 内部不需要安装 NVIDIA 驱动但要求 Windows 宿主机有新版驱动且 WSL2 里要能看到 GPU。验证方法nvidia-smi如果 WSL2 里能正常显示 GPU 信息说明宿主的驱动已经透传进来了。如果显示找不到请先回到 Windows 升级驱动别在 WSL2 里折腾驱动安装。这一步坑了非常多的人包括我。2.2 安装 CUDA 12.8 Toolkit 的两种思路我推荐用官方 runfile 方式安装这样可以精确控制安装路径也方便和系统已有的 CUDA 多版本共存。到 NVIDIA 官网下载对应 Linux 版本的 CUDA Toolkit 12.8 runfile然后执行wget https://developer.download.nvidia.com/compute/cuda/12.8.0/local_installers/cuda_12.8.0_xxx_linux.run sudo sh cuda_12.8.0_xxx_linux.run运行后会进入交互界面。这里有个小技巧如果你只是要用 Toolkit 编译而不是运行图形界面相关的东西可以不安装 Driver前提是驱动版本已经满足要求只选 CUDA Toolkit 和 CUDA Runtime。省得把系统已有的驱动搞乱。安装路径默认是/usr/local/cuda-12.8它同时会创建一个软链接/usr/local/cuda指向这个目录。我们编译 detectron2 时可以用软链接这样以后切换 CUDA 版本只需要改软链接。另一种思路是用 conda 安装 CUDA Toolkitconda install cuda -c nvidiaconda 装的 CUDA 会把所有东西放在 conda 环境里不会污染系统。但有个问题detectron2 源码编译时有的依赖会去找/usr/local/cuda而 conda 的 CUDA 路径在$CONDA_PREFIX下需要显式设置CUDA_HOME多一步功夫。我个人建议服务器上用 runfile虚拟环境里用 conda两者结合最舒服。2.3 配置环境变量和验证安装完 CUDA Toolkit 后必须把环境变量写进 shell 配置文件。我一般写在~/.bashrc里export CUDA_HOME/usr/local/cuda-12.8 export PATH$CUDA_HOME/bin:$PATH export LD_LIBRARY_PATH$CUDA_HOME/lib64:$LD_LIBRARY_PATH如果你用的是软链接/usr/local/cuda那可以直接写/usr/local/cuda但要注意确保软链接指向 12.8ls -l /usr/local/cuda确认后重启终端或者source ~/.bashrc然后用nvcc -V验证nvcc -V能看到 release 12.8 就对了。注意nvcc -V显示的版本才是真正编译用的 CUDA 版本不是nvidia-smi那个。还有个小细节有些机器上LD_LIBRARY_PATH如果同时包含了多个 CUDA 版本的 lib64运行时可能会加载错版本。我建议把 12.8 的路径放到最前面。这一点在 detectron2 运行时报CUDA driver version is insufficient时尤其值得检查。3. PyTorch 2.8 的安装与验证3.1 通过 pip 安装带 CUDA 12.8 的 PyTorchPyTorch 2.8 官方发布了对应 CUDA 12.8 的预编译包pip 安装时直接指定 index-url 即可pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128这里有个小坑很多人以为直接pip install torch默认就是 CUDA 版但事实上 PyPI 上的默认包通常是 CPU 版。如果你先装了 CPU 版后面 detectron2 编译时会检测不到 CUDA然后白折腾半天。务必用上面这个 index-url。另外如果是在干净的 conda 环境里装我建议先执行conda create -n detectron2 python3.10 conda activate detectron2 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128Python 版本选 3.10 是因为它既被 PyTorch 2.8 完全支持又与大部分 detectron2 依赖的稳定版本相匹配。实测 3.11、3.12 也能用但 3.10 目前踩坑最少。3.2 验证 PyTorch 是否真正使用 GPU装完先别着急装 detectron2花一分钟验证 torch 的 CUDA 状态。在 Python 里运行import torch print(torch.__version__) print(torch.version.cuda) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))正常情况下输出类似2.8.0 12.8 True NVIDIA GeForce RTX 4090如果torch.version.cuda显示12.8说明 PyTorch 就是基于 CUDA 12.8 编译的可以和你的 CUDA Toolkit 12.8 配套。如果显示None恭喜你装成 CPU 版了回去重装。还有一个很容易被忽略的点PyTorch 2.8 的cu128wheel 里已经包含了它所需的 CUDA 运行库所以在只做推理时即使系统没有安装 CUDA Toolkit 也能跑。但我们要编译 detectron2就必须有独立安装的 Toolkit。记住运行时 PyTorch 自带的库够用编译时不够用。3.3 一个小坑PyTorch 2.8 的 CUDA 版本标识有时候你会看到 PyTorch 的 wheel 命名是torch-2.8.0cu128其中cu128表示 CUDA 12.8。这里千万要分清PyTorch 的cu128和系统 CUDA Toolkit 的 12.8 不一定要求完全一致但最好保持一致。如果你系统装了 CUDA 12.4却用cu128的 PyTorch通常也能跑因为 PyTorch 自带的运行库会覆盖系统库。但 detectron2 编译的时候会同时使用系统 Toolkit 和 PyTorch 的头文件版本相差太远就可能出现模板实例化错误不好排查。所以我一直坚持系统工程上永远选择“同版本全家桶”避免将来自找麻烦。4. detectron2 源码编译安装4.1 为什么建议源码编译在 PyPI 上其实有detectron2的预编译轮子但那是针对特定 PyTorch 版本和 CUDA 版本构建的。你在 PyTorch 2.8 CUDA 12.8 环境下十有八九找不到完全对应的 wheel或者装完导入直接崩。一个可靠的原则是只要你的环境不是“发行版默认”就老老实实从源码编译。源码编译并不恐怖detectron2 的 setup 脚本会检查你当前的 PyTorch 和 CUDA 环境然后生成对应的扩展。它比你想象得更智能但前提是环境干净。4.2 准备 detectron2 源码和依赖先把源码拉下来git clone https://github.com/facebookresearch/detectron2.git cd detectron2 git checkout v0.6这里我特意推荐 checkout 到 v0.6因为当前 main 分支在 PyTorch 2.8 下偶尔会有一些小兼容性问题v0.6 这个 release 在 2.8 下已被大量社区验证过。你也可以不 checkout但出了问题别怪我没提醒。然后安装核心依赖pip install ninja pyyaml matplotlib tqdm其中ninja尤其重要因为它能大幅加速 CUDA 扩展编译。如果不装detectron2 会退回用 make编译速度慢到怀疑人生。如果你要用到 detectron2 的可视化功能还要装pip install opencv-python pillow这些是常规依赖建议一次性装全避免中途回头补装浪费编译时间。4.3 编译命令与关键参数在编译前一定要设置TORCH_CUDA_ARCH_LIST。这个变量决定了 nvcc 为哪些 GPU 架构生成机器码。如果你不设置detectron2 会调用 PyTorch 查询当前 GPU 能力通常也够用但有的时候会因为驱动版本或者 WSL2 透传的问题识别不准导致编译出来的扩展没法在当前卡上运行。以常见的几种 GPU 为例我是这样设的export TORCH_CUDA_ARCH_LIST7.5;8.0;8.6;9.0;12.0解释一下7.5对应 TuringRTX 20 系列8.0对应 Ampere A1008.6对应 Ampere 游戏卡RTX 30 系列9.0对应 Hopper H10012.0对应 BlackwellRTX 50 系列。如果你只有一张 4090Ada 架构sm_89可以额外加8.9。设的架构越多编译出来的二进制越大但兼容性越好。本地测试只留自己需要的架构编译最快export TORCH_CUDA_ARCH_LIST8.9然后执行pip install -e .这个过程会比较长通常几分钟到十几分钟。期间如果看到nvcc在疯狂编译那就对了。如果立马报错八成是 CUDA_HOME 没配好或者 GCC 版本不兼容。4.4 编译成功后的导入验证编译完成后先在项目目录外测试导入cd ~ python -c import detectron2; print(detectron2.__version__)如果输出0.6或对应版本号就成功了。接着验证 GPU 算子from detectron2.utils.visualizer import Visualizer print(detectron2 loaded OK)能正常加载说明 CUDA 扩展编译成功。此时再跑实例分割模型一般不会再报什么幺蛾子。5. 实测中常见报错与排查5.1 编译时提示找不到 nvcc 或 CUDA 版本不对这个错误常见形式是RuntimeError: No CUDA runtime is found, did you set CUDA_HOME correctly?排查思路按优先级来which nvcc确认 nvcc 是否在 PATH 里。nvcc -V确认版本是否是 12.8。echo $CUDA_HOME确认变量是否指向/usr/local/cuda-12.8。检查 PyTorch 的torch.version.cuda是否也是 12.8。如果 PyTorch 是 cu128但 CUDA_HOME 指向 12.4那最好统一成 12.8。如果因为项目原因不能改系统 CUDA可以在项目根目录下临时设置CUDA_HOME指向 12.8 的安装路径然后再运行安装命令。比如export CUDA_HOME/usr/local/cuda-12.8 pip install -e .5.2 报unsupported GNU version与 GCC 版本问题CUDA 12.8 的 nvcc 对 GCC 有版本上限如果你默认 GCC 是 13 或 14编译时会出现#error -- unsupported GNU version! gcc versions later than 12 are not supported!解决办法最简单的是安装一个 GCC 11并切换到它sudo apt install gcc-11 g-11然后设置export CC/usr/bin/gcc-11 export CXX/usr/bin/g-11注意nvcc在编译时也会用到宿主 GCC所以只在编译 detectron2 前设置这两个环境变量就够了。编译完恢复默认即可。5.3 导入 detectron2 时报 undefined symbol 或 libtorch_cuda 相关错误这类问题通常是你系统里存在多个 PyTorch 环境导入时把别的环境里的libtorch_cuda.so加载进来了。最直接的排查确认当前 Python 的torch.__file__指向的是 cu128 环境的路径。确认LD_LIBRARY_PATH里没有夹带其他 conda 环境的 lib 目录。重新编译 detectron2因为 undefined symbol 多半是编译时用的 PyTorch 头文件和运行时加载的 PyTorch 不是同一套。如果你之前用pip install -e .编译过改完环境后最好先卸载再重新编译pip uninstall detectron2 -y rm -rf build/ **/*.so pip install -e .5.4 运行时报 no kernel image is available这个报错经典到不能再经典RuntimeError: CUDA error: no kernel image is available for execution on the device原因是编译时TORCH_CUDA_ARCH_LIST里没有包含你当前 GPU 的架构。比如你是 RTX 3060sm_86但编译时只写了8.0RTX 3060 就无法运行。我的建议是如果你是通用环境直接设置一个范围较宽的架构列表。虽然编译时间稍微长一点但换来的是任何卡都能跑划算。如果已经编译过需要清掉缓存重新编译rm -rf build **/*.so python setup.py clean5.5 WSL2 下安装的额外提醒在 Windows WSL2 里装这套环境算是踩坑重灾区。核心要点不要尝试在 WSL2 内部装 NVIDIA 驱动宿主机的驱动会通过 WSL2 透传。WSL2 里执行nvidia-smi能看到 GPU只证明驱动透传成功不代表 CUDA Toolkit 已安装。在 WSL2 里的/usr/local/cuda路径建议和 Windows 下的路径分开管理避免混淆。如果从 Windows 的带 GUI 的 Python 环境切换到 WSL2要特别注意环境变量里的 CUDA 路径。我实际在 WSL2 里遇到过一个怪问题nvidia-smi正常显示 GPUtorch.cuda.is_available()也是True但 detectron2 编译后一运行就报CUDA_ERROR_UNKNOWN。后来发现是TORCH_CUDA_ARCH_LIST没设置导致编译出的 kernel 没有针对当前 GPU 架构生成。设置成对应架构后重编问题立刻消失。6. 最后的几个实用建议下面这几条是我反复踩坑后总结的算不上深奥但能帮你省掉大量时间。依赖装的顺序很重要。永远先装驱动再装 CUDA Toolkit再装 PyTorch最后编译 detectron2。如果中途发现版本不对宁可推倒重来也不要在一个乱七八糟的环境里打补丁。环境这东西越是脏乱越难定位问题。在这个组合里最脆弱的一环其实是 GCC。很多报错表面上是 CUDA 问题实际是 GCC 和 nvcc 的搭配问题。我建议把 GCC 11 作为标准配置写进自己的环境安装文档里不管以后装什么深度学习框架都用得上。还有一个心得编译 detectron2 之前先跑一个小的 PyTorch CUDA 验证脚本确认 GPU 计算没问题再开始编译。如果验证脚本都过不了编译了也白编译。如果你只是需要跑预训练模型做推理可以考虑直接用 detectron2 的官方 Docker 镜像省去全部编译过程。但如果需要自定义算子或修改模型结构自己编译是绕不开的。我个人倾向于自己编译可控性更高而且以后升级 PyTorch 版本时思路也会更清晰。最后分享一个小技巧把安装过程中遇到的所有报错命令和解决方案记录到一个 markdown 文件里因为下次换机器、换驱动、换 CUDA 版本时大概率还会遇到类似问题。有记录的话十分钟就能解决原本可能要折腾一晚上的问题。