详细避坑教程Ubuntu22.04安装MMDetectionV3.3.0深度学习目标检测模块（Python、PyTorch、OpenMMLab等版本匹配）

本文提供了在 Ubuntu 22.04 系统上成功安装 MMDetection V3.3.0 的详细避坑指南。文章首先强调了环境版本匹配的重要性，给出了基于 Python 3.8、PyTorch 2.1.2（CUDA 12.1）、MMEngine 0.10.x 和 MMCV 2.1.0 的已验证配置。随后，教程分步讲解了从系统依赖安装、创建 Conda 虚拟环境、安装 PyTorch、正确安装 MMEngine 与 MMCV（关键锁定 MMCV 版本为 2.1.0），到源码编译安装 MMDetection 3.3.0 的完整流程。最后，提供了一个验证脚本，用于测试环境是否安装成功，确保模型能在 GPU 上正常初始化与推理。

环境匹配说明

我的主机是Ubuntu22.04版本，使用miniconda进行python环境管理。

目前已经成功安装好MMDetectionV3.3.0，这是最新的版本了。

我的环境详细如下：

GPU: NVIDIA RTX 3090
System: Linux / Ubuntu
Python: 3.8
PyTorch: 2.1.2 (CUDA 12.1)，版本高了也会报错哦
OpenMMLab: MMEngine 0.10.x, MMCV 2.1.0 (关键), MMDet 3.3.0

第一步：环境依赖安装

MMDetection 编译需要 C++ 编译器，也需要git来拉取源码。在创建 Python 环境前，请先确保系统装了这些工具。

打开终端运行：

sudo apt-get update
sudo apt-get install -y build-essential git
# 验证是否安装成功（应输出版本号）
gcc --version

第二步：创建 Conda 虚拟环境

使用 Python 3.8，这是 OpenMMLab 兼容性最稳定的版本之一。不要用太新版本哦，可能不支持！

# 1. 创建环境 (名称可自定义，这里叫 mmdet_rtx3090)
conda create -n mmdet_rtx3090 python=3.8 -y

# 2. 激活环境
conda activate mmdet_rtx3090

第三步：安装 PyTorch

不要安装高版本！建议安装v2.1.2

Previous PyTorch Versions

Linux and Windows
# CUDA 11.8
conda install pytorch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 pytorch-cuda=11.8 -c pytorch -c nvidia
# CUDA 12.1
conda install pytorch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 pytorch-cuda=12.1 -c pytorch -c nvidia
# CPU Only
conda install pytorch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 cpuonly -c pytorch

第四步：安装 MMEngine 和 MMCV

这是最容易版本冲突的地方。使用 openmim 工具，并强制锁定 MMCV 版本为 2.1.0。

# 1. 安装 OpenMMLab 的包管理工具 mim
pip install -U openmim

# 2. 安装 MMEngine (核心引擎)
mim install "mmengine==0.10.7"

# 3. 【绝对关键】安装 MMCV 2.1.0
# MMDetection 3.3.0 暂时不完全兼容 MMCV 2.2.x，必须锁死在 2.1.0
mim install "mmcv==2.1.0"

第五步：源码安装 MMDetection 3.3.0

为了方便你之后修改配置文件（Config）和查看源码，强烈建议使用源码安装，而不是 pip 直接安装。

# 1. 克隆代码仓库 (下载到当前目录)
git clone https://github.com/open-mmlab/mmdetection.git

# 2. 进入目录
cd mmdetection

# 3. 切换到 3.3.0 分支 (保持与你成功的环境一致)
git checkout v3.3.0

# 4. 编译并安装
# -v 显示详细日志，-e 开启可编辑模式
pip install -v -e .

第六步：验证脚本

创建一个名为 verify_install.py 的文件，填入以下代码并运行，看看有没有成功：

import torch, mmcv, mmdet, mmengine
import os
from mmdet.apis import init_detector, inference_detector

print("=" * 40)
print(f"CUDA Available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"GPU: {torch.cuda.get_device_name(0)}")
print("-" * 40)
print(f"PyTorch:   {torch.__version__}")
print(f"MMEngine:  {mmengine.__version__}")
print(f"MMCV:      {mmcv.__version__} (Should be 2.1.0)")
print(f"MMDet:     {mmdet.__version__}")
print("=" * 40)

# --- 关键修改：指定绝对路径 ---
# 根据你之前的日志，我的源码安装路径在 /home/wood/mmdetection
# 需要替换成你的安装路径下
MMDET_ROOT = '/home/wood/mmdetection'
config_file = os.path.join(MMDET_ROOT, 'configs/rtmdet/rtmdet_tiny_8xb32-300e_coco.py')
checkpoint_file = 'https://download.openmmlab.com/mmdetection/v3.0/rtmdet/rtmdet_tiny_8xb32-300e_coco/rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth'

print(f"正在加载配置文件: {config_file}")

# 简单的模型加载测试
try:
    if not os.path.exists(config_file):
        raise FileNotFoundError(f"找不到配置文件，请确认路径是否正确: {config_file}")

    # 加载模型
    model = init_detector(config_file, checkpoint_file, device='cuda:0')
    print("\n✅ Success: Model initialized on GPU! (环境安装完美)")

    #以此测试推理是否报错 
    dummy_img = torch.zeros((100, 100, 3), dtype=torch.uint8).cpu().numpy()
    result = inference_detector(model, dummy_img)
    print("✅ Success: Dummy Inference passed!")

except Exception as e:
    print(f"\n❌ Error: {e}")
    print("\n提示：请确保你已经 git clone 了 mmdetection 并且路径是 /home/wood/mmdetection")

运行结果如下：

/home/wood/miniconda3/envs/mmdet2/bin/python /home/wood/桌面/ModelTrain/OverlappingPolygonMMDetection/verify_install.py 
========================================
CUDA Available: True
GPU: NVIDIA GeForce RTX 3090
----------------------------------------
PyTorch:   2.1.2
MMEngine:  0.10.7
MMCV:      2.1.0 (Should be 2.1.0)
MMDet:     3.3.0
========================================
正在加载配置文件: /home/wood/mmdetection/configs/rtmdet/rtmdet_tiny_8xb32-300e_coco.py
Loads checkpoint by http backend from path: https://download.openmmlab.com/mmdetection/v3.0/rtmdet/rtmdet_tiny_8xb32-300e_coco/rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth
Downloading: "https://download.openmmlab.com/mmdetection/v3.0/rtmdet/rtmdet_tiny_8xb32-300e_coco/rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth" to /home/wood/.cache/torch/hub/checkpoints/rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth
The model and loaded state dict do not match exactly

unexpected key in source state_dict: data_preprocessor.mean, data_preprocessor.std


✅ Success: Model initialized on GPU! (环境安装完美)
/home/wood/miniconda3/envs/mmdet2/lib/python3.8/site-packages/torch/functional.py:504: UserWarning: torch.meshgrid: in an upcoming release, it will be required to pass the indexing argument. (Triggered internally at /opt/conda/conda-bld/pytorch_1702400400184/work/aten/src/ATen/native/TensorShape.cpp:3526.)
  return _VF.meshgrid(tensors, **kwargs)  # type: ignore[attr-defined]
✅ Success: Dummy Inference passed!