MMDetection 安装教程（避坑版）

✅ MMDetection 安装教程（避坑版）

适用场景：WSL2 / Ubuntu 24.04 / Python 3.8 / CUDA 11.8
说明：由于 MMDetection 官方文档未及时更新，直接按其教程安装容易出现版本冲突。本教程使用 MIM 工具 和 预编译版本，确保兼容性。

🔧 步骤 0：安装 Miniconda（如未安装）

# 下载 Miniconda
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

# 安装
bash Miniconda3-latest-Linux-x86_64.sh

# 激活 conda（重启终端或运行）
source ~/.bashrc

🐍 步骤 1：创建并激活 Conda 虚拟环境

注意：必须使用 Python 3.8，以保证与 MMCV、MMDet 的兼容性。

conda create --name openmmlab python=3.8 -y
conda activate openmmlab

📦 步骤 2：安装 PyTorch 与 torchvision（CUDA 11.8）

使用阿里云镜像加速安装（推荐）：

pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 \
  -f https://mirrors.aliyun.com/pytorch-wheels/cu118/

✅ 验证是否安装成功：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

输出应类似：

2.1.0
True

💡 若你无法使用 CUDA，请将 device='cuda:0' 改为 'cpu'。

🛠️ 步骤 3：使用 MIM 安装 MMEngine 和 MMCV

MIM 是 OpenMMLab 的官方包管理工具，可自动解决依赖。

# 安装 MIM
pip install -U openmim

# 安装 MMEngine 和 MMCV（指定兼容版本）
mim install "mmengine==0.10.7"
mim install "mmcv==2.1.0"

✅ 说明：

• mmcv==2.1.0 是完整版（含 CUDA ops），强烈推荐
• 若安装失败，请检查 PyTorch 和 CUDA 版本是否匹配（见知识库链接）

📥 步骤 4：安装 MMDetection

mim install "mmdet==3.3.0"

✅ mim 会自动解析依赖并安装正确版本，避免 pip 冲突。

✅ 步骤 5：验证安装（下载配置文件）

mim download mmdet --config rtmdet_tiny_8xb32-300e_coco --dest .

该命令会下载以下两个文件到当前目录：

• rtmdet_tiny_8xb32-300e_coco.py（模型配置）
• rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth（预训练权重）

🧪 步骤 6：测试推理（验证模型运行）

确保你有一个测试图片 demo/demo.jpg，或替换为任意本地图片路径。

from mmdet.apis import init_detector, inference_detector

config_file = 'rtmdet_tiny_8xb32-300e_coco.py'
checkpoint_file = 'rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth'

# 初始化模型（可选 device='cuda:0' 使用 GPU）
model = init_detector(config_file, checkpoint_file, device='cpu')

# 推理
result = inference_detector(model, 'demo/demo.jpg')

# 打印结果
print(result)

✅ 成功标志：输出检测框和类别信息，无报错。

📚 参考资料

• MMDetection 官方文档：https://mmdetection.cn/en/latest/get_started.html
• MMCV 安装说明：https://mmcv.readthedocs.io/zh-cn/latest/get_started/installation.html
• PyTorch 镜像（阿里云）：https://mirrors.aliyun.com/pytorch-wheels/cu118/

⚠️ 常见问题与建议

✅ 恭喜！你已成功安装 MMDetection 并完成推理测试！

接下来可以尝试训练自定义数据集或使用其他模型（如 Faster R-CNN、YOLO 等）。