都说Windows是深度学习的第一生产力可真到了配环境这一步生产力就变成了拆盲盒。尤其MMDetection看着GitHub上给的安装命令一行行复制粘贴好像挺简单但只要你用的是Windows并且刚好需要安装指定版本整套流程就会变得很魔幻。今天这篇教程就专门解决这个问题目标非常明确在Win10系统上从零开始把MMDetection 2.19.0跑起来配套安装mmcv-full 1.3.17并且这套思路可以直接延展到往后更新的MMDetection版本。先说清楚这篇文章适合谁看。你已经装了Python和CUDA但是装MMDetection的时候各种报错装不进去或者你刚接触目标检测框架想在本地Windows环境跑一下训练和推理再或者你是被网上那些“Linux一键安装”教程劝退的Windows用户想找一个真正能把坑提前踩平的流程。这三种情况都可以直接照这篇教程操作。另外说明一下标题写的2.19.0是目前一个非常稳定的分支但本文所有安装逻辑、版本选择策略、踩坑排查方法对更新的MMDetection版本同样适用。因为重点不是让你背命令而是把“版本对应关系”和“安装原理”搞清楚只要这两点通了后面升级版本就是换个数字的事。1. 整体安装思路与版本规划1.1 为什么Windows装MMDetection容易翻车先别急着敲命令换个角度想清楚一个问题MMDetection不是一个独立软件而是一个依赖链条很长的框架。它底层是PyTorchPyTorch依赖CUDA而MMDetection的核心组件都要通过mmcv-full和CUDA算子打交道。这条链上任何一环的版本对不上结果就是运行时报错或者import失败。Windows系统之所以比Linux更容易翻车主要因为三点第一第三方库的预编译wheel包发布不全。很多工具链作者默认用户用LinuxWindows版本的wheel要么没有要么版本滞后。mmcv-full就是个典型它的Windows wheel只发布到特定版本号想安装比较新的版本就只能本地源码编译而源码编译对Visual Studio工具链有硬性要求。第二路径和系统环境差异。Windows下CUDA的安装位置、Python解释器的路径、conda环境的激活方式都跟Linux不一样。很多教程是Linux用户写的默认路径都是/usr/local/cudaWindows用户照着操作自然找不到文件。第三mmdetection的源码在Windows上偶尔会触发一些编译行为。某些算子在Windows环境下的编译方式比Linux更严格动不动就抛fatal error C1083这类问题很多新手看到这个就直接劝退了。1.2 版本对应关系这一步决定后面是否顺利MMDetection、mmcv-full、PyTorch、CUDA这四者之间有一套严格的版本对应关系。不能说“我装最新版PyTorch就行”也不能说“mmcv越新越好”。选错了后面无论如何都跑不起来。MMDetection 2.19.0对应的官方要求是Python 3.6到3.9之间PyTorch 1.5以上mmcv-full版本需不低于1.2.4。但实际踩下来的结论是pytorch在1.8到1.10之间会省心很多我这篇文章推荐PyTorch 1.8.2 CUDA 10.2这个组合理由后面详说。mmcv-full则强烈建议安装1.3.17因为这是官方为2.19.0推荐并测试过的最稳版本。提示MMDetection每个版本的release页面上都会写明对应的mmcv-full版本范围。装任何新版本之前第一件事不是去搜教程而是去GitHub看release notes里面写着官方测过的mmcv版本。照着官方推荐装大概率不会出大问题自己随意组合就是在为难自己。1.3 推荐的安装组合与完整流程概览结合实际操作经验我推荐的组合是Python 3.8 PyTorch 1.8.2 CUDA 10.2 mmcv-full 1.3.17 MMDetection 2.19.0。选这个组合的原因有三个。Python 3.8是目前MMDetection生态兼容性最好的版本3.9能用但没3.8稳3.7以下的很多新库都不能装。PyTorch 1.8.2这个版本在所有Windows环境下的wheel包都非常完整不需要本地编译安装起来速度快而且不会出幺蛾子。CUDA 10.2则是当年PyTorch官方支持最成熟的版本跟mmcv-full 1.3.17的匹配度最好。完整流程分四步走准备基础环境Python、CUDA、Visual Studio工具链创建conda虚拟环境并安装PyTorch通过官方预编译wheel安装mmcv-full安装MMDetection并进行验证测试这个顺序是强制的基础环境没搞定后面的步骤就是空中楼阁。下面按顺序一步步说清楚。2. 安装前的环境准备与检查2.1 Python与Conda环境准备Python版本我上面说了直接选3.8就行。如果你电脑上已经装了其他版本的Python也没关系后续操作都在conda虚拟环境里进行不会干扰你现有的环境。这里强烈建议使用conda来管理环境不管你用的是Anaconda还是Miniconda都行如果电脑上啥也没有直接装Miniconda体量小而且够用。安装conda后打开Anaconda Prompt或者普通的命令行窗口先确认conda命令可用conda --version然后创建独立的环境。这一步不要嫌麻烦独立环境能保证你的项目依赖不跟其他项目互相污染后面排查问题也方便很多conda create -n openmmlab python3.8 conda activate openmmlab激活之后后续所有安装命令都在这同一个命令行窗口里执行不要中途关掉或者换窗口否则环境会丢这是新手最容易忽略的细节。2.2 CUDA与显卡驱动检查很多人搞混一个概念显卡驱动和CUDA Toolkit不是一回事。驱动是显卡运行的底层支撑CUDA Toolkit是基于驱动之上提供的并行计算开发环境。检查驱动能不能支持CUDA看的是驱动版本而PyTorch要调用计算资源本质上用的是CUDA Toolkit通过conda或pip装下来的那套库文件。在命令行输入nvidia-smi如果正常输出了显卡信息说明驱动没问题。右上角的CUDA Version: 10.2或11.x之类的字样表示你的驱动最高能支持的CUDA版本。比如驱动支持到CUDA 11.4那么装CUDA 10.2的PyTorch和mmcv完全没问题向下兼容的。有些教程会教你额外单独安装一个CUDA Toolkit但如果你选择PyTorch 1.8.2cudatoolkit 10.2这个组合完全不需要额外装CUDA Toolkit。因为conda会自动帮你在环境里装好cudatoolkit整套运行时依赖是跟着PyTorch走的。2.3 Visual Studio Build Tools绕不开的Windows编译环境这一节是Windows专属的重灾区无数人在这里功亏一篑。mmcv-full 1.3.17在Windows下的官方wheel只有特定版本我推荐安装的这个版本能直接用预编译wheel。但问题是Python轮子在加载扩展模块时或者后续你自己安装其他OpenMMLab系列组件时系统可能会触发本地源码编译。没有C编译环境就会报找不到cl.exe或者C1083之类的错误。标准解决办法是安装Visual Studio Build Tools不需要装完整的Visual Studio IDE那个太占空间。去微软官网下载Visual Studio Build Tools安装器运行时选择“使用C的桌面开发”这一项工作负载右侧默认勾选的组件保持不动再额外勾选最新版Windows 10 SDK。安装时间会比较长建议找个随时能联网的时间段来装。注意安装完Visual Studio Build Tools之后需要重启一次电脑或者至少重启命令行窗口环境变量才能生效。没有这一步后面如果触发编译操作系统还是找不到编译器。2.4 Git的安装与配置MMDetection是通过pip安装的但官方源码通常从GitHub拉取。虽然预编译wheel不强制要求Git但后续下载demo推理用的权重文件、克隆官方示例仓库都离不开它。去Git官网装Windows版安装时一路默认即可。安装完验证一下git --version到这里基础环境就全部就绪了。接下来进入真正的安装环节。3. 安装PyTorch整个依赖链条的地基3.1 PyTorch版本选择与CUDA匹配PyTorch版本选择是整个安装流程中最关键的一步。你不能随便装新版因为mmcv-full 1.3.17对PyTorch版本有明确的兼容范围要求。直接给出结论PyTorch 1.8.2加CUDA 10.2版是mmcv-full 1.3.17的最佳搭档。这个结论怎么来的第一需要查阅当时mmcv-full官方文档里面列出了PyTorch 1.3到1.8是经过测试的稳定范围第二PyTorch 1.8.2是1.x系列里最成熟稳定的一个patch版本安装包完整Windows下的wheel分发做得最广第三CUDA 10.2作为conda包直接安装不需要系统级权限对个人开发机最友好。3.2 使用官方conda命令安装在之前创建并激活的openmmlab环境中输入以下命令conda install pytorch1.8.2 torchvision0.9.2 torchaudio0.8.2 cudatoolkit10.2 -c pytorch这里需要注意一个细节torchvision的版本必须和pytorch对应。PyTorch 1.8.2对应torchvision 0.9.2这是官方固定匹配的版本对不能随意换。换错了虽然Python包能装进去但运行时会报一堆版本不匹配的警告严重时还会直接报错。安装完成后验证PyTorch是否正常、CUDA是否可用python -c import torch; print(torch.__version__); print(torch.cuda.is_available())如果输出1.8.2加上True说明PyTorch和CUDA全部就绪。这里有个常见问题值得说一下很多人明明显卡是NVIDIA的但torch.cuda.is_available()返回False。这种问题八成是cudatoolkit没装全或者conda channels的优先级设置导致装成了CPU版。检查方式很简单再次运行上面的命令时看版本号后面有没有cu102后缀如果是cpu就说明装错了源。3.3 踩坑提示不要用最新版本PyTorch有人会问我直接装最新的PyTorch 2.x不行吗在MMDetection 2.19.0这个框架版本下真的不建议。原因是MMDetection 2.19.0内部的很多算子实现是基于旧版PyTorch API写的PyTorch 2.x改了很多内部接口。虽然OpenMMLab团队后来推出了适配新版PyTorch的MMDetection 3.x但在2.19.0这个版本上强行配新PyTorch只会带来无谓的兼容性麻烦。既然目的是跑起2.19.0就乖乖用与之匹配的PyTorch 1.8.2这是最省时省力的教科书式组合。4. 安装mmcv-full最核心也最折磨人的一环4.1 为什么必须装mmcv-full而不是mmcv先区分一个概念。MMDetection的底层依赖于mmcv而mmcv分为两个发行版mmcv和mmcv-full。前者是一个精简版只包含基础模块不包含CUDA算子后者包含所有CUDA算子目标检测、实例分割这些核心功能全部依赖这些算子。直接说结论装MMDetection必须装mmcv-full。只装mmcv的话等import MMDetection的时候就会报错ModuleNotFoundError: mmcv._ext这个错误出现的频率极高基本属于每个新手都会踩的坑。4.2 直接使用预编译wheelWindows用户的最佳路径Windows用户装mmcv-full有两个选择源码编译或者预编译wheel。源码编译需要配好Visual Studio环境后自行运行setup.py过程漫长不说还经常出现各种莫名其妙的编译错误实际体验非常糟糕。预编译wheel则是官方直接提供编译好的安装包一条pip命令直接装完省时省力。mmcv-full的预编译wheel在官方文档里可以找到对应的下载链接。不同版本、不同Python、不同CUDA版本都有对应的不同链接格式通常是https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html需要注意一个小坑wheel下载页面上的索引目录结构是cu102/torch1.8.0虽然需要安装的是PyTorch 1.8.2但当年mmcv官方编译时基于的是1.8.0构建这个版本范围内wheel包是互相兼容的直接用即可。选定对应目录后在环境里执行pip install mmcv-full1.3.17 -f https://download.openmmlab.com/mmcv/dist/cu102/torch1.8.0/index.html这里的-f参数指定了额外的wheel搜索地址pip会在官方PyPI之外自动去这个页面上寻找对应版本号的wheel包。只要版本号匹配就会直接下载并安装预编译好的安装包不需要本地做任何编译。4.3 源码编译方案与失败原因分析那万一你需要的mmcv-full版本在官方wheel页面找不到怎么办比如某些更新版本的mmcv-full并没有提供Windows预编译包。这时候就得走源码编译的路线了。源码编译的前提条件在前面已经准备好就是Visual Studio Build Tools。接着从GitHub拉取mmcv源码在对应版本tag上直接执行安装git clone -b v1.3.17 https://github.com/open-mmlab/mmcv.git cd mmcv pip install -e .但实操过程中源码编译会绕不开两个经典问题。一是ninja构建工具在某些情况下会跟Visual Studio的编译器冲突报出ninja: error: loading build.ninja这一类问题二是某些算子的编译特别吃内存和显存编译过程中卡死或者直接报killed的都有。Windows用户如果真走到这一步建议优先检查MSVC环境变量是否生效并且关闭杀毒软件对构建目录的实时防护能显著降低编译失败概率。不过再次强调1.3.17这个版本有官方预编译wheel没必要自讨苦吃走编译路线。4.4 验证mmcv-full是否安装成功安装完成后运行下面这段验证代码用get_arch这个接口检查CUDA架构信息顺便验证_ext模块是否存在python -c import mmcv; from mmcv.ops import get_compiling_cuda_version, get_compiler_version; print(mmcv.__version__); print(get_compiling_cuda_version()); print(get_compiler_version())如果输出类似1.3.17 10.2 MSVC 19.xx说明mmcv-full安装成功CUDA算子和编译器信息都正常。如果报错ModuleNotFoundError: No module named mmcv._ext说明装成了精简版mmcv需要重装mmcv-full。5. 安装MMDetection 2.19.0与验证测试5.1 使用pip直接安装mmcv-full搞定之后MMDetection的安装就变得很简单了。在同一个conda环境里执行pip install mmdet2.19.0pip会自动拉取依赖并安装常用的opencv-python、matplotlib、terminaltables等依赖包会自动一并装好。整个安装过程一般不会报错如果报错多数是因为网络问题换国内镜像源重试即可pip install mmdet2.19.0 -i https://pypi.tuna.tsinghua.edu.cn/simple5.2 源码安装方式与适用场景如果你不满足于简单调用API想改源码或者看内部实现细节可以选择源码安装git clone -b v2.19.0 https://github.com/open-mmlab/mmdetection.git cd mmdetection pip install -e .源码安装的好处是mmdetection目录下所有.py文件直接可见可改改完立即生效非常适合深度学习和目标检测的学习者来研究框架内部机制。缺点是目录最好不要随便移动位置因为-e模式生成的egg-link文件指向的路径变了import就会失败。5.3 快速验证能不能跑通一个推理Demo装完之后先做基础验证检查版本统一性python -c import mmdet; print(mmdet.__version__)输出2.19.0就说明MMDetection安装成功。但这只是第一步真正检验安装质量的方式是跑一个完整的推理Demo。从MMDetection官网下载一个faster_rcnn的预训练权重文件放到一个项目目录里然后写个脚本加载模型并对一张测试图进行推理。只要能顺利输出检测框结果整条安装链条才算真正打通。这里贴一个快速验证的脚本核心代码from mmdet.apis import init_detector, inference_detector config_file configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py checkpoint_file faster_rcnn_r50_fpn_1x_coco_20200130-047c8118.pth model init_detector(config_file, checkpoint_file, devicecuda:0) result inference_detector(model, test.jpg) model.show_result(test.jpg, result, out_fileoutput.jpg)第一次跑推理时程序会自动下载对应的config文件或者初始化一些缓存时间可能会久一点耐心等就行。如果这一步能顺利跑出结果整个安装流程就算完美收官了。6. 高频报错与解决方案速查6.1 环境配置类的常见报错报错信息原因解决方案ModuleNotFoundError: No module named mmcv._ext装了精简版mmcv而不是mmcv-full卸载mmcv按本文方法重装mmcv-fulltorch.cuda.is_available()返回False装成了CPU版PyTorch或cudatoolkit没装全检查是否从正确渠道安装使用conda install重装带CUDA的PyTorchnvcc not found没有单独安装CUDA Toolkit或环境变量未配置当前方案下不需要单独配置确认PyTorch自带cudatoolkit是否正常即可fatal error C1083Visual Studio Build Tools未安装或未重启安装VS Build Tools的C桌面开发负载重启电脑后再试6.2 安装过程类的经典报错报错信息原因解决方案No matching distribution found for mmcv-full1.3.17使用了错误版本的版本号交互方式或镜像源无法重定向到官方wheel使用-f参数指定官方wheel索引页不要只写pip install mmcv-full1.3.17ninja: error: loading build.ninja源码编译时ninja与MSVC环境变量冲突在环境中执行set DISTUTILS_USE_SDK1后再编译或者直接换预编译wheel方案下载超时中断网络问题使用国内镜像源但注意wheel预编译包必须走官方链接undefined symbol或DLL加载错误mmcv、PyTorch、CUDA三者版本不匹配严格按本文组合重装PyTorch 1.8.2 CUDA 10.2 mmcv-full 1.3.176.3 排查工具与调试技巧遇到问题先别慌有几个通用排查套路值得养成习惯。第一分清报错发生在import阶段还是运行阶段。import torch就报错说明PyTorch本身有问题import mmcv报错问题在mmcv相关依赖from mmdet.apis import init_detector报错多半是MMDetection依赖不完整。逐层向上排查效率高得多。第二检查conda环境是否激活成功。这是很多人忽略的低级错误命令行里(openmmlab)前缀没出现所有包都装到了base环境导致各种import不到。每次打开新窗口第一件事就是确认环境前缀。第三用pip list查看已安装版本确认所有关键包的版本号完全匹配目标组合。一个命令能解决很多怀疑人生的时刻pip list | findstr /i torch mmcv mmdet7. 新版本MMDetection的安装适配经验7.1 版本升级的核心逻辑文章标题里说了这套方法适用于最新版本MMDetection。其实这句话的底层逻辑很简单无论MMDetection版本怎么更新它的安装套路都是固定的——先装PyTorch再装对应版本的mmcv-full最后装MMDetection本体。变的只是具体版本号组合。比如你想装MMDetection 2.25.0那就要去它的release页面查看对应的mmcv-full版本要求再看mmcv-full需要哪个范围的PyTorch最后反推conda安装命令里的版本号。版本对应关系永远是自上而下的框架 - 底层库 - 深度学习框架 - CUDA。实际动手时最高效的办法是先看MMDetection官方文档里的installation页面上面会列出每个分支版本推荐的mmcv-full版本组合表格照着选就行。7.2 从2.x升级到3.x的注意事项如果你装好了2.19.0之后想更进一步试试MMDetection 3.x这里提前提醒三个区别第一mmcv-full这个包名在3.x生态里已经废弃了统一改名为mmcv且不再区分精简版和完整版安装逻辑变成了pip install mmcv2.0.0第二PyTorch最低版本要求提高了官方推荐最低PyTorch 1.8以上但实际测试下来1.11起步会更稳第三MMDetection 3.x的配置文件格式做了大规模重写直接用2.x的配置是跑不起来的。不过万变不离其宗先把2.19.0这套流程吃透理解版本对应关系的内在逻辑未来升级任何新版本都只是查文档、改版本号、重装一遍的问题不会再被折腾得焦头烂额。8. 写在最后的实操体会这套环境我前后踩了不下三轮从一开始在Linux上装得顺风顺水到转战Windows之后被各种编译问题捶打再到后来把每个报错都整理成表格、总结成规律整个过程印象太深了。如果你现在正卡在某一步我的建议是别在报错信息上死磕太久停一下重新捋一遍版本链条往往问题就出在某个版本的匹配关系上。实际操作中还有一个小技巧值得分享在你所有安装命令都成功执行之后建议把整个环境打包记录一下方便以后快速重建。用conda导出环境配置清单不时看一下对自己装过什么心里有数conda env export environment.yaml后续如果想在另一台电脑上复现这套环境不需要再一个个手动装包直接一条命令重建爽快得很。这种操作习惯比任何安装教程都更能帮你节省时间。
