MMDetection Cheat Sheet

1Install (mim)3.3

pip install -U openmim★
MIM is OpenMMLab's package manager — it resolves the correct prebuilt mmcv wheel for your exact PyTorch + CUDA. Install PyTorch first.
mim install mmengine "mmcv>=2.0.0" mmdet★
The 3.x stack. In MMCV 2.x the package is just mmcv (the old mmcv-full); mmcv-lite skips the CUDA ops. Don't pip install mmcv directly — use mim.
python -c "import mmdet; print(mmdet.__version__)" # 3.3.0
Confirm the install and version.
mim download mmdet --config rtmdet_tiny_8xb32-300e_coco --dest .
Fetch a config + pretrained checkpoint by name — the quickest way to get weights for the demo below.

2Inferencerun a pretrained model

from mmdet.apis import DetInferencer inf = DetInferencer("rtmdet_tiny_8xb32-300e_coco") inf("demo/demo.jpg", out_dir="outputs/", show=False)★
High-level API — give it a model name (weights auto-download), an image / folder / URL, and it runs + visualizes. Easiest entry point.
from mmdet.apis import init_detector, inference_detector model = init_detector(config, checkpoint, device="cuda:0") result = inference_detector(model, "img.jpg")★
Low-level API for full control. Returns a DetDataSample.
inst = result.pred_instances inst.bboxes · inst.scores · inst.labels★
Read predictions off pred_instances. Filter by score: inst[inst.scores > 0.3]. Masks live in inst.masks for segmentation models.

3The config systemeverything is a config

# my_config.py _base_ = "configs/rtmdet/rtmdet_tiny_8xb32-300e_coco.py"★
_base_ inheritance is the core idea — start from a shipped config and override only what changes. Configs live in configs/ (hundreds of them).
model = dict(bbox_head=dict(num_classes=3)) # override★
Dicts deep-merge onto the base. Point this at your class count, dataset, schedule, etc. (some models nest it, e.g. roi_head.bbox_head).
from mmengine.config import Config cfg = Config.fromfile("my_config.py")
Load a config in Python. Inspect the fully-merged result with python tools/misc/print_config.py my_config.py.
python tools/train.py cfg.py --cfg-options train_dataloader.batch_size=4
--cfg-options overrides any config key from the CLI — no file edit needed for quick experiments.

4Train & test CLItools/

python tools/train.py my_config.py --work-dir work_dirs/exp1★
Train from a config. Logs, checkpoints, and the merged config land in --work-dir. Add --amp for mixed precision, --resume to continue.
bash tools/dist_train.sh my_config.py 8 # 8 GPUs★
Multi-GPU via the distributed launcher (the config's 8xb32 naming = 8 GPUs × batch 32; scale LR if you change it).
python tools/test.py my_config.py checkpoint.pth --out results.pkl★
Evaluate a checkpoint — prints COCO mAP. --show-dir vis/ saves visualized predictions.
python tools/analysis_tools/analyze_logs.py plot_curve work_dirs/exp1/*/vis_data/*.json
Plot loss/mAP curves from the run's logs. tools/analysis_tools/ has confusion-matrix and error-analysis helpers too.

5Custom datasetCOCO is the easy path

# Convert your annotations to COCO JSON, then in the config: data_root = "data/mine/" metainfo = dict(classes=("cat", "dog", "bird"))★
COCO format is the least-friction route — MMDetection reads it natively via CocoDataset. Define your class names once in metainfo.
train_dataloader = dict(dataset=dict( data_root=data_root, metainfo=metainfo, ann_file="annotations/train.json", data_prefix=dict(img="train/")))★
Override the dataloader's dataset fields. Repeat for val_dataloader/test_dataloader and set val_evaluator.ann_file.
@DATASETS.register_module() class MyDataset(BaseDetDataset): ...
For non-COCO formats, register a dataset class with the registry so a config can reference it by name (type="MyDataset").

6Model zoowhat to pick

# two-stage: accurate Faster R-CNN · Mask R-CNN (instance seg) · Cascade R-CNN★
The classic high-accuracy family. Mask R-CNN adds instance segmentation.
# one-stage: fast RetinaNet · FCOS · YOLOX · RTMDet★
RTMDet is the modern speed/accuracy sweet spot and a good default. YOLOX for real-time.
# transformer (DETR family) DETR · Deformable DETR · DINO
DINO is the strongest transformer detector here. Also panoptic/segmentation: Mask2Former, Panoptic FPN.
# ~500 pretrained COCO checkpoints in the model zoo
Each configs/<method>/ folder lists variants + download links; use the config name with mim download / DetInferencer.

7MMEngine runtimethe Runner drives it

train_cfg = dict(type="EpochBasedTrainLoop", max_epochs=50, val_interval=1) optim_wrapper = dict(optimizer=dict(type="AdamW", lr=1e-4))★
MMEngine's Runner executes train/val/test loops from config. Set epochs, optimizer, and param_scheduler (warmup/decay) declaratively.
default_hooks = dict(checkpoint=dict(type="CheckpointHook", interval=1), logger=dict(type="LoggerHook", interval=50)) custom_hooks = [dict(type="EMAHook")]
Hooks extend the loop — checkpointing, logging, EMA, early behaviors — without touching training code.
visualizer = dict(vis_backends=[dict(type="TensorboardVisBackend")])
Swap in TensorBoard / WandB backends via the DetLocalVisualizer. cfg.compile = True enables torch.compile (PyTorch 2.0+).

8Deploy & exportMMDeploy

mim install mmdeploy★
MMDeploy is the sibling project that exports MMDetection models to production runtimes.
# export to ONNX / TensorRT / OpenVINO / ncnn via a deploy config python tools/deploy.py deploy_cfg.py model_cfg.py checkpoint.pth img.jpg
Deploy configs pick the backend (ONNX Runtime, TensorRT, OpenVINO…) and produce an optimized model + SDK.
# quick win: torch.compile the model for speed, no export
For pure-PyTorch serving, torch.compile (enabled in the config) is the low-effort speedup.

!Common gotchasread before shipping

install mmcv via mim, matched to torch+CUDA
The #1 pain: a prebuilt mmcv wheel must match your exact PyTorch + CUDA. Use mim install, not plain pip. The newest PyTorch/Python may have no wheel yet — check the compatibility table.
3.x is NOT 2.x
MMDetection 3.x (MMEngine, MMCV 2.x, mmcv) has different configs and APIs than 2.x (mmcv-full). Don't follow 2.x tutorials — the config schema changed.
num_classes must match everywhere
Set it in every head (some models have multiple / auxiliary heads). A mismatch silently tanks training or errors on load.
understand the merged config
_base_ inheritance means a change can cascade unexpectedly. Print the final merged config before trusting it.
COCO category ids vs model labels
COCO category ids aren't necessarily 0..N-1; model labels are 0-indexed. Set metainfo.classes in the right order so the mapping is correct.
low-activity maintenance
3.3.0 (Jan 2024) is the latest; OpenMMLab development has slowed. Pin known-good torch/mmcv versions; the very newest CUDA/PyTorch may need a community fork.

MMDetection cheat sheet