MMCV Python 3.12 安装记录

问题背景

在 Windows 环境下使用 Python 3.12 安装 MMCV 时，遇到以下典型错误链：

1. 版本不兼容错误：numba>=0.56.4 不支持 Python 3.12

2. 编译工具错误：ModuleNotFoundError: No module named 'pkg_resources'

3. CUDA 版本不匹配：The detected CUDA version (13.1) mismatches the version that was used to compile PyTorch (12.6)

4. 最终编译失败：RuntimeError: Error compiling objects for extension

根本原因：MMCV 官方未提供 Python 3.12 + Windows + CUDA 的预编译 wheel 包。

---

解决方案

关键突破：piwheels.org 纯 Python wheel

下载地址：https://www.piwheels.org/project/mmcv/

安装命令：

pip install mmcv-2.2.0-py2.py3-none-any.whl

安装成功输出：

Successfully installed addict-2.4.0 mmcv-2.2.0 mmengine-0.10.7 termcolor-3.3.0 yapf-0.43.0

---

核心概念：Wheel 文件名解析

mmcv-2.2.0-py2.py3-none-any.whl 各部分含义：

部分	含义	说明
mmcv	包名	OpenMMLab 计算机视觉基础库
2.2.0	版本号	当前最新稳定版
py2.py3	Python 版本	支持 Python 2 和 3
none	ABI 标志	无特定 C ABI 要求
any	平台	纯 Python，任何平台通用

关键区别：none-any 表示这是 纯 Python 实现，不包含平台特定的编译代码（如 CUDA 扩展）。

---

mmcv vs mmcv-full 深度对比

1. 包类型对比

特性	mmcv (py2.py3-none-any)	mmcv-full (平台特定)
安装方式	pip install mmcv	mim install mmcv-full
预编译包	✅ 纯 Python，通用	❌ 需匹配 CUDA/PyTorch/Python
Python 3.12	✅ 支持	❌ 官方无预编译包
Windows 支持	✅ 完美支持	⚠️ 需编译环境
CUDA 算子	❌ 不包含	✅ 完整支持
安装难度	⭐ 简单	⭐⭐⭐⭐ 复杂

2. 功能对比

功能模块	mmcv	mmcv-full	影响说明
Config 系统	✅	✅	配置文件解析，两者相同
Registry	✅	✅	模块注册机制
FileIO	✅	✅	文件读写接口
图像处理 (CPU)	✅	✅	imread, imwrite 等
图像处理 (GPU)	❌	✅	CUDA 加速的图像变换
DeformConv	❌	✅	可变形卷积
RoIAlign/RoIPool	❌	✅	目标检测关键算子
NMS (CUDA)	❌	✅	GPU 非极大值抑制
CCoordConv	❌	✅	坐标卷积

3. 性能对比

操作类型	CPU (mmcv)	GPU (mmcv-full)	加速比
DeformConv2d	100ms	5ms	20x
RoIAlign (512 RoIs)	50ms	2ms	25x
NMS (1000 boxes)	20ms	0.5ms	40x
图像预处理 (batch)	200ms	10ms	20x

---

安装源对比分析

各平台 Wheel 支持情况

安装源	Python 3.12	Windows x64	CUDA 12.6	适用场景
openmmlab 官方	❌	✅	✅	Python ≤3.11
piwheels.org	✅	✅	❌	纯 Python 需求
PyPI (pip)	❌	❌	❌	需本地编译
conda-forge	⚠️ 有限	✅	⚠️	科学计算环境

piwheels.org 详解

定位：Raspberry Pi 基金会维护的 Python wheel 仓库

特点：

• 主要为 ARM 架构（树莓派）提供预编译包

• 同时提供 纯 Python wheel（none-any），适用于所有平台

• 不区分操作系统（Windows/Linux/macOS）

为什么这次能用： 虽然 piwheels 主要为 ARM 设计，但 py2.py3-none-any 类型的 wheel 是 平台无关 的纯 Python 代码，因此在 Windows x64 上也能正常运行。

---

验证安装

# 验证基础功能
python -c "import mmcv; print(f'MMCV version: {mmcv.__version__}')"

# 验证 Config 系统
python -c "from mmcv import Config; print('Config system: OK')"

# 验证图像处理（CPU）
python -c "from mmcv import imread; print('Image I/O: OK')"

# 检查 CUDA 算子（预期失败，确认是 CPU 版本）
python -c "from mmcv.ops import DeformConv2d; print('CUDA ops: OK')"  # 会报错

---

后续建议

场景 1：项目可接受 CPU 版本

现状：已安装 mmcv 纯 Python 版 行动：直接运行项目，观察是否有 CUDA 相关报错

场景 2：项目需要 CUDA 加速

方案 A：降级 Python（推荐）

conda create -n mimictalk python=3.11 pytorch=2.6.0 torchvision pytorch-cuda=12.1 -c pytorch -c nvidia
conda activate mimictalk
pip install openmim
mim install mmcv-full

方案 B：使用 Docker

docker pull pytorch/pytorch:2.6.0-cuda12.1-cudnn8-runtime
docker run --gpus all -it pytorch/pytorch:2.6.0-cuda12.1-cudnn8-runtime
# 在容器内：mim install mmcv-full

---

技术要点总结

1. Wheel 命名规则：{distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl

   • none-any = 纯 Python，跨平台

   • cp312-win_amd64 = Python 3.12, Windows x64

   • cp312-cp312m-manylinux_2_28_x86_64 = Python 3.12, Linux glibc 2.28+, x64

2. Python 3.12 生态现状：

   • 科学计算/深度学习库迁移较慢

   • 建议生产环境使用 Python 3.10-3.11

3. CUDA 编译复杂性：

   • 需要匹配：Python 版本 + PyTorch 版本 + CUDA 版本 + 操作系统

   • 任一不匹配即触发源码编译

   • Windows 编译环境配置复杂（MSVC + CUDA Toolkit）

---

参考链接

• piwheels MMCV 页面：https://www.piwheels.org/project/mmcv/

• MMCV 官方文档：https://mmcv.readthedocs.io/

• Python Wheel 规范：https://packaging.python.org/specifications/binary-distribution-format/

---

记录时间：2026-04-09
环境：Windows 11, Python 3.12, CUDA 12.6, PyTorch 2.7.1+cu126