如果你最近刚把计算卡换成 RTX 5090或者新到的机器直接就是一张 50 系显卡想在 Linux 上装 mmcv 跑检测模型大概率会撞上这个经典场景pip install mmcv要么直接提示找不到匹配版本要么好不容易装完import一跑就报 no kernel image is available。这套流程在 40 系显卡上明明很顺怎么一到 50 系就翻车这篇笔记就来拆清楚背后的原因并把源码编译的完整流程走一遍。内容不只针对 50 系玩家凡是拿到新架构显卡、发现预编译包装不上的朋友都能照着这套思路解决。先交代一下背景。mmcv 是 OpenMMLab 系列项目里负责提供底层算子NMS、ROIAlign、DCN 这类的组件很多检测分割代码都绕不开它而这类算子恰恰是 CUDA/C 写死的扩展属于编译期强依赖环境的东西。RTX 50 系改用 Blackwell 架构后GPU 的计算能力标号变成了 sm_120之前预编译好的通用 wheel 对新显卡来说就是听不懂的方言。源码编译本质就是让代码在你的机器上重新翻译成 sm_120 能懂的指令。下面我会从版本配对、依赖检查、完整编译命令到排错验证一层层展开。1. 50系显卡为什么装不上预编译版mmcv1.1 从sm_89到sm_120Blackwell改写了“方言”先讲一个基础概念GPU 的计算能力compute capability可以理解成一套硬件指令集的版本号。RTX 40 系是 Ada Lovelace 架构计算能力是 sm_89RTX 50 系是 Blackwell 架构消费级型号的计算能力直接跳到 sm_120。这个跳变不是简单的小版本升级而是指令集层面的更新——老的 CUDA 编译器不认它老的二进制也不一定能跑。mmcv 里的核心算子走的是 JIT/扩展编译机制它拿到的是一个源码文件.cu和.cpp真正干活前需要先调用 nvcc 编译成当前硬件能读懂的 cubin 文件。问题就出在这里你机器上的 nvcc 版本决定了它认不认 sm_120你要用的 mmcv 预编译 wheel也决定它内部是否打包了 sm_120 对应的 kernel。我打个比方。预编译 wheel 相当于提前录好的普通话版本适配了大多数主流显卡。可 Blackwell 这台设备只听得懂自己的地方方言你拿普通话录音去放它当然毫无反应。源码编译则是把文件拿到你本机让工具链现场用方言重新讲一遍。1.2 预编译wheel和本地源码编译的分界线预编译 wheel 不是不好而是它天然滞后。mmcv 官方发布带算子的完整版时要给不同 CUDA 版本和 PyTorch 版本组合提前构建每个组合又要编译几十个 CUDA 源文件工程量不小。新显卡刚出来时官方 CI 里很可能还没覆盖到 sm_120自然就没有对应架构的包。所以 50 系用户面临两种情况pip install mmcv找不到匹配版本直接报 No matching distribution found。装上了旧一点版本的预编译包但里面的算子没有 sm_120 的 kernel运行到具体函数时突然崩掉。这两种情况共同指向一个结论在当前这个时间点50 系想稳定用上完整的 mmcv源码编译是比等 wheel 更实际的选择。源码编译的另一个好处是你可以把TORCH_CUDA_ARCH_LIST设成自己这张卡的架构编译产物只针对它生成指令更精准运行性能也更稳妥。2. 动手前先对齐驱动、CUDA、PyTorch三者的版本关系很多人在源码编译卡住根本不是命令抄错了而是环境里驱动、CUDA、PyTorch 三者版本互相打架。这三样东西的关系可以简化成一句话驱动是底层基础CUDA Toolkit 提供编译器 nvccPyTorch 决定 mmcv 编译时盯住哪个 CUDA 版本。2.1 显卡驱动先过570这道门槛RTX 50 系在 Linux 下的驱动要求比较硬性建议装 570 系列或更新版本。如果你装老驱动比如 535、550系统可能根本不识别这张卡nvidia-smi直接报 No devices were found后面所有步骤都无从谈起。检查方法很简单nvidia-smi右上角能看到Driver Version。如果低于 570抓紧升级。在 Ubuntu 这类系统上一般用ubuntu-drivers devices查看推荐版本再配合apt install nvidia-driver-570这类命令安装。装完重启确认nvidia-smi能正常显示 GPU 型号和驱动版本再往下走。顺便提一个容易忽略的点驱动版本更多是向下兼容的逻辑新的驱动能支持旧卡旧驱动不一定支持新卡。所以 50 系用户别省事驱动直接往新了装。2.2 CUDA Toolkitsm_120的最低要求是12.8sm_120 这个计算能力不是所有 CUDA 版本都认识。CUDA 12.8 开始才正式支持 Blackwell 的 sm_120所以源码编译前你机器上至少要有 CUDA 12.8 的 Toolkit。这里说的不是 PyTorch wheel 里自带的那个 runtime而是包含 nvcc 编译器的那一整包工具链——没有 nvccmmcv 的 .cu 源文件根本编译不了。安装方式分两种场景有 root 权限直接走官方 runfile 或 deb 安装装完把 nvcc 路径加进 PATH。没有 root 权限或者不想污染系统环境用 conda 装也很干净conda create -n mmcv50 python3.10 -y conda activate mmcv50 conda install -c nvidia cuda-toolkit12.8 -y装完检查一下nvcc --version如果显示release 12.8或更高说明编译器就绪。注意nvcc和驱动的版本是可以有差异的驱动 570 配合 CUDA Toolkit 12.8/12.9 都很常见两者有独立的 minor version compatibility 机制不必强行一模一样。2.3 PyTorch版本mmcv编译时需要它当“锚点”PyTorch 是 mmcv 编译时的锚点。mmcv 的 setup 脚本会读取当前环境里 torch 的版本和它自带的 CUDA 版本然后按这个基准去生成扩展。如果你装的是 CPU 版 PyTorch后面即便强行编译结果也是没有 CUDA 算子的残废版本。所以顺序必须是先装带 GPU 支持的 PyTorch再编译 mmcv。RTX 50 系建议装 PyTorch 2.7 以上它对 sm_120 已经有完整支持。安装命令我直接给一份实际跑通过的conda activate mmcv50 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128装完确认python -c import torch; print(torch.__version__, torch.version.cuda, torch.cuda.get_device_capability())正常输出里torch.version.cuda应该是 12.8 或更高get_device_capability()应该返回(12, 0)也就是你机器上的卡能跑 sm_120。这一步确认完三件套才算真正对齐。提示torch.version.cuda和nvcc --version的版本最好保持一致或互相兼容。我在实际踩坑时遇到过两边版本差太远mmcv 编译期间链接 CUDA 库时直接报 undefined symbol 的情况。所以尽量把 conda 里的 cuda-toolkit 版本和 PyTorch wheel 自带的 CUDA 版本选成同一个大版本最省事。3. 源码编译前最后检查依赖工具与三个决定成败的环境变量三件套对齐后别急着敲编译命令。先检查系统里三个工具再理解三个环境变量。工具少了会当场报错环境变量设置错了编译成功了也是白费运行起来一样崩。3.1 编译工具链gcc、make、ninja一个都不能少源码编译需要 C 编译器和构建工具。最低要求是 gcc/g 5.4 以上但 CUDA 12.8 对 gcc 版本有上界要求实测 gcc 11 或 12 都比较稳。装法sudo apt install build-essential ninja-build -y如果用的是 conda 环境也可以直接让 conda 管理conda install -c conda-forge gxx_linux-64 ninja -y检查版本gcc --version ninja --version make --versionninja 很关键mmcv 的 CUDA 算子能并行编译就靠它。用 make 也能编但速度慢且容易把内存顶满。强烈建议把 ninja 装上。3.2 MMCV_WITH_OPS和FORCE_CUDA决定mmcv“含金量”源码编译时的两个关键环境变量一个是MMCV_WITH_OPS一个是FORCE_CUDA。MMCV_WITH_OPS1表示编译时带上完整的 C/CUDA 算子扩展。如果不设置你得到的其实是个轻量版 mmcvNMS、ROIAlign、DCN 这些核心能力全都没有下游算法一跑就崩。另一个FORCE_CUDA1则是强制走 CUDA 编译路径。正常情况下 setup 脚本会做检测万一它没检测到 GPU 环境就退回去编一个纯 CPU 版本白白浪费时间。所以完整编译命令开头应该是MMCV_WITH_OPS1 FORCE_CUDA1 ...这两个变量几乎就是我想装一个能用的完整 mmcv的官方暗号。3.3 TORCH_CUDA_ARCH_LIST写错等于白编译这可能是整个流程里最容易被忽略的变量也是最容易编译成功但全部白干的地方。TORCH_CUDA_ARCH_LIST告诉编译系统你要为哪些 GPU 架构生成 kernel。50 系是 sm_120写错成8.6对应 30 系或9.0对应 Hopper编译过程不会报错但产出物里根本没有 sm_120 的指令跑起来就是经典报错 no kernel image is available。对 50 系显卡正确写法是TORCH_CUDA_ARCH_LIST12.0PTX这里的12.0对应 sm_120PTX是额外生成一层 PTX 字节码驱动后续可以动态编译兼容性更好。如果只在这张卡上跑不打算换其他型号写12.0也行。我习惯加上PTX因为谁知道哪天会不会临时插一张别的 Blackwell 卡。如果你实在懒得设PyTorch 2.7 以上通常能自动识别本机显卡架构并填充这个值。但自动识别依赖 PyTorch 恰好认识这张新卡而且自动识别出的结果不一定包含 PTX。为了可预测性我还是建议显式写出来。4. 三条编译路线逐一走一遍从MIM到手动编译环境就绪后真正动工。我推荐按省心程度排序三条路线都实测过大家按自己的偏好选。4.1 MIM自动编译最省心的路径OpenMMLab 官方推荐的安装管理工具是 MIMOpenMMLab 包管理工具。它的一个好处是会自动检测本机的 PyTorch 和 CUDA 版本然后帮你决定是装预编译包还是走源码编译。pip install openmim -y mim install mmcv2.2.0 --build加--build参数MIM 就会在预编译包不匹配的情况下自动执行源码编译不需要你手动 clone 仓库或者记一堆环境变量。第一次跑这个命令会看到 nvcc 输出刷屏这属于正常现象等它完成即可。MIM 这条路线适合环境刚配好、想最快跑通、不想费脑记命令的朋友。但有一个细节要注意MIM 判断 CUDA 版本时读的是torch.version.cuda不是系统nvcc的版本。如果这两个版本差太远MIM 选择的编译基准可能和你系统里的 CUDA Toolkit 对不上所以最稳妥的做法还是先在 2.2 节里把两者统一好。4.2 git clone手动编译整个过程都在眼皮底下MIM 虽然省心但如果你之后要改 mmcv 源码、加调试信息或者想精确控制每次编译的参数走一遍手动 git clone 更踏实。整个流程如下conda activate mmcv50 git clone https://github.com/open-mmlab/mmcv.git cd mmcv MMCV_WITH_OPS1 FORCE_CUDA1 TORCH_CUDA_ARCH_LIST12.0PTX pip install -e . -v逐步解释一下git clone默认拉到最新主分支。如果你想要稳定版本先用git tag --list看有哪些 release 标签然后 checkout 到最新稳定 tag比如git checkout v2.2.0或当时更新的版本。pip install -e .是开发模式把当前目录以可编辑方式安装进 Python 环境。好处是后续对 mmcv 源码的改动立刻生效不用反复重装。如果不想保留源码目录去掉-e直接pip install .也行。-v让 pip 输出详细日志编译卡住时方便定位是哪一个 .cu 文件出了问题建议保留。编译期间你会看到类似creating mmcv/_ext.cpython-310-x86_64-linux-gnu.so的信息然后是一长串 nvcc 编译的 .cu 文件列表。走到这一步说明环境变量全都生效了耐心等就行。4.3 pip源码安装不想要源码目录的轻量选项还有一种方案不需要 clone 仓库直接让 pip 从 PyPI 拉源码包并在本地编译pip install mmcv2.2.0 -vvv --no-binary mmcv --no-cache-dir--no-binary mmcv的意思是不要用 PyPI 上现成的二进制 wheel强制从源码构建。--no-cache-dir防止 pip 拿缓存里的旧 wheel 凑数。对只想临时编译一个版本、不打算接触源码的朋友这条最省事。不过说实话这条路线在排错时不如 git clone 直观一旦编译失败你很难从 pip 的日志里看到完整的源码路径和上下文。我的建议是如果你预感后面可能要反复编译直接走 4.2 的方式如果只是临时试一下再用这个轻量方案。4.4 编译中的三个“刺客”并行度、磁盘、缓存源码编译主要有三个坑提前说一下避免踩雷。第一个是并行度。mmcv 会调用 ninja 并行编译几十个 CUDA 文件每编译一个文件都会吃很多内存。如果你机器内存不够大比如 16GB 以下或者正在跑别的任务可以用MAX_JOBS限制并行数MAX_JOBS4 MMCV_WITH_OPS1 FORCE_CUDA1 TORCH_CUDA_ARCH_LIST12.0PTX pip install -e . -vMAX_JOBS4代表最多同时编 4 个文件速度慢一点但内存压力小很多不容易把机器卡死。第二个是磁盘空间。CUDA 编译过程的中间文件很占地方一套完整编译下来 5GB 到 10GB 很常见。如果编译到一半提示No space left on device先看看/tmp和 conda 环境所在分区别急着重装系统。第三个是缓存目录。mmcv 的扩展产物会缓存到用户目录下的~/.cache/torch_extensions。如果你前一次编译失败过、或者改了架构参数重新编译旧缓存可能造成新编译看起来成功但行为诡异。遇到这种情况果断清理rm -rf ~/.cache/torch_extensions然后再编译一次。5. 装完不等于完事50系环境下的验证与排错编译完成不代表大功告成。我习惯装完后做一轮快速验证确认 mmcv 的 GPU 算子真的能在这张 50 系显卡上跑起来而不是仅仅 import 不报错。5.1 验证mmcv是否真的能跑GPU算子开一个 Python 交互环境依次跑import torch import mmcv print(mmcv version:, mmcv.__version__) print(CUDA available:, torch.cuda.is_available()) print(GPU capability:, torch.cuda.get_device_capability()) from mmcv.ops import nms boxes torch.tensor([[10, 10, 20, 20], [15, 15, 25, 25]], dtypetorch.float32, devicecuda) scores torch.tensor([0.9, 0.8], devicecuda) keep nms(boxes, scores, iou_threshold0.5) print(NMS keep indices:, keep)如果最后能正常输出tensor([0, 1], devicecuda:0)这样的结果说明 NMS 这个核心 CUDA 算子真正在硬件上跑通了。很多人的轮子就坏在这一步import 能过一调用算子就崩。所以这一步千万别省。5.2 运行时报错排查一张表看懂怎么处理结合我自己的排错经历50 系环境下常见的报错基本就是下面几种按表对照处理通常能省不少时间。报错特征根本原因处理办法ImportError: libcudart.so.xx: cannot open shared object fileconda 环境里 CUDA 库路径没有生效export LD_LIBRARY_PATH$CONDA_PREFIX/lib:$LD_LIBRARY_PATH或者重新激活 conda 环境CUDA error: no kernel image is available for execution on the device当前库的 kernel 没有为 sm_120 生成确认编译时TORCH_CUDA_ARCH_LIST写成12.0PTX清理~/.cache/torch_extensions后重编RuntimeError: The detected CUDA version ... mismatches ...nvcc 版本与 PyTorch 内置 CUDA 版本不匹配检查nvcc --version和torch.version.cuda把两者统一到同一个大版本比如 12.8nvcc fatal : Unsupported gpu architecture compute_120本机 nvcc 版本低于 12.8升级 CUDA Toolkit 到 12.8 或更高重新确认nvcc --version编译时internal compiler errorgcc 版本超出 CUDA 支持范围换 gcc 11 或 12或者用 conda 单独装一套低版本 gcc 再编最有迷惑性的是第二种no kernel image。它有个特点是编译全程没报错、import 也可能正常可一跑具体算子就崩。第一次遇到的人很容易怀疑是不是卡坏了其实根子往往就是TORCH_CUDA_ARCH_LIST没设对或者用了老版本的预编译包。回到 3.3 节重新对一遍就解决了。5.3 换PyTorch版本后必须重编mmcv这些缓存一定要清最后说一个后来才想明白的坑mmcv 的扩展是跟着 PyTorch 版本走的。今天你用 PyTorch 2.7 编译好的 mmcv明天因为某个项目要求升级到 PyTorch 2.8mmcv 很可能直接起不来。这不是你操作有问题而是 C 扩展的 ABI 依赖了 PyTorch 内部的接口换版本就得重新编译。重编前除了刚才说的~/.cache/torch_extensions还要清一下 mmcv 项目目录下的build文件夹cd mmcv rm -rf build rm -rf ~/.cache/torch_extensions然后重复第 4.2 节的编译命令。这一步不做大概率会撞上 undefined symbol 这类链接错误而且报错信息还看不太明白。我在实际使用中还有一个习惯把完整编译命令存成一个build_mmcv.sh脚本放在固定目录。每次升级驱动、换 PyTorch、或者换到新机器直接改一两个版本变量就能跑不用重新回忆环境变量的写法。源码编译这件事方法论本身很简单——版本对齐、变量写对、缓存清干净剩下就真的是等着编译进度条走完了。希望这篇笔记能让你在 50 系显卡这条路上少折腾几个晚上。
