from mmcv.runner找不到模块？版本兼容问题

Question

在使用 MMDetection 或 MMCV 相关项目时，常出现 `from mmcv.runner import xxx` 报错“ModuleNotFoundError: No module named 'mmcv.runner'”的问题。这主要源于 MMCV 版本升级导致的模块结构调整：自 MMCV v2.0 起，原 `mmcv.runner` 模块被拆分至 `mmengine`，旧接口不再可用。用户若安装了新版 `mmcv-full` 或 `mmengine`，但代码仍沿用旧导入方式，便会引发兼容性错误。解决方案包括：降级 MMCV 至 1.7.x 版本，或根据官方迁移指南将 `mmcv.runner` 替换为 `mmengine.runner` 并适配新 API。建议严格遵循 MMDetection 等框架指定的依赖版本，避免版本冲突。

Answer 1

1. 问题背景与现象描述

在使用 MMDetection 或 MMCV 相关项目时，开发者常遇到如下报错：

ModuleNotFoundError: No module named 'mmcv.runner'

该错误通常出现在尝试执行 from mmcv.runner import xxx 语句时。尽管代码逻辑正确且历史版本中运行无误，但在新环境中却无法导入模块。这一现象的根本原因在于 MMCV 自 v2.0 版本起进行了重大架构重构，将原本位于 mmcv.runner 的训练控制器、钩子（Hook）、Runner 等核心组件迁移至独立的 mmengine 库中。

因此，旧版代码若未同步更新导入路径和 API 调用方式，即使成功安装了 mmcv-full 或 mmengine，仍会因找不到 mmcv.runner 模块而抛出异常。

2. 技术演进脉络：从 MMCV 到 MMEngine

为理解此问题的深层成因，需回顾 OpenMMLab 生态的技术演进：

1. MMCV v1.x 时代：所有训练流程控制逻辑集中于 mmcv/runner/ 目录下，包括 Runner、Hooks、EpochBasedRunner 等。
2. MMCV v2.0 分拆：为提升模块解耦性与可复用性，OpenMMLab 将训练引擎部分剥离至新项目 MMEngine，原 mmcv.runner 功能由 mmengine.runner 接管。
3. 依赖关系反转：自 MMDetection 3.0 起，默认依赖 mmengine 和 mmcv>=2.0，不再兼容 mmcv.runner 接口。

这一变化标志着 OpenMMLab 进入“引擎-算法”分层架构时代，但同时也带来了广泛的向后兼容挑战。

3. 常见错误场景分析

场景编号	环境配置	代码行为	结果
1	mmcv-full==1.7.1	from mmcv.runner import Runner	✅ 成功导入
2	mmcv-full==2.0.0	from mmcv.runner import Runner	❌ ModuleNotFoundError
3	mmcv-full==2.0.0 + mmengine	from mmengine.runner import Runner	✅ 成功导入
4	MMDetection 3.0 + mmcv < 2.0	启动训练脚本	⚠️ 可能出现 API 不匹配警告
5	自定义项目引用旧教程代码	沿用 mmcv.runner 钩子机制	❌ 运行时报错

4. 解决方案对比与实施路径

方案一：降级 MMCV 至 v1.7.x

适用于维护旧项目或快速验证原型，命令如下：

pip install "mmcv-full<2.0" -f https://download.openmmlab.com/mmcv/dist/index.html

优点是改动最小；缺点是无法享受 MMEngine 提供的新特性（如分布式训练优化、日志系统增强等），且长期存在安全与性能隐患。

方案二：迁移到 MMEngine 新 API

推荐用于新项目或可持续维护系统。关键迁移步骤包括：

• 替换导入语句：from mmcv.runner import EpochBasedRunner → from mmengine.runner import EpochBasedRunner
• 调整 Runner 初始化参数，例如 optimizer_config 已被移除，需通过 build_optim_wrapper 配置
• Hook 注册方式变更：由 register_hook() 改为通过 cfg.train_cfg.hooks 声明式配置

参考官方迁移指南：MMEngine Migration Guide

5. 架构演化图示：模块迁移流程

graph TD
    A[MMCV v1.x] --> B[mmcv.runner]
    B --> C{Training Control}
    C --> D[Runner]
    C --> E[Hooks]
    C --> F[Logging]

    G[MMCV v2.0+] --> H[Core CV Operators]
    I[MMEngine] --> J[mmengine.runner]
    J --> K[Runner]
    J --> L[Hooks]
    J --> M[Logger]
    
    style B fill:#f9f,stroke:#333
    style J fill:#bbf,stroke:#333
    style G fill:#f96,stroke:#333
    style I fill:#6fb,stroke:#333

    linkStyle 0 stroke:#f00;
    linkStyle 1 stroke:#0c0;

6. 最佳实践建议

为避免此类版本冲突，提出以下工程化建议：

• 锁定依赖版本：使用 requirements.txt 或 conda-env.yml 明确指定 mmcv-full==1.7.1 或 mmengine>=0.10.0
• 启用虚拟环境隔离：每个项目使用独立 Conda 或 venv 环境，防止全局污染
• 自动化检测脚本：部署前运行检查脚本，验证是否存在 mmcv.runner 导入
• 持续集成兼容性测试：CI 流程中包含多版本 MMCV 测试矩阵
• 文档标注 API 兼容性：团队内部 Wiki 标注各代码库适用的 MMCV/MMEngine 版本范围