Detectron2 Cheat Sheet

3Inference (DefaultPredictor)one image

cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST = 0.5 predictor = DefaultPredictor(cfg)★
Set the detection confidence threshold, then build the predictor (loads weights + preprocessing).
import cv2 img = cv2.imread("photo.jpg") # BGR, HWC outputs = predictor(img)★
Input is a BGR NumPy image (as from cv2.imread) — DefaultPredictor handles resize/normalize. One image at a time.
DefaultPredictor = single image, not batchednote
For throughput, build the model with build_model(cfg) + a data loader and batch yourself — DefaultPredictor is a convenience wrapper.

4Outputs (Instances)read predictions

inst = outputs["instances"].to("cpu")★
An Instances object on the GPU — move to CPU before reading in Python.
inst.pred_boxes · inst.scores · inst.pred_classes · inst.pred_masks★
Detections: boxes (Boxes, xyxy), confidences, class indices, and per-instance binary masks (segmentation models).
len(inst) · inst.pred_classes.tolist() · inst.pred_keypoints
Count detections; class indices map to names via the dataset's metadata (below). Keypoint models add pred_keypoints.

5Visualizedraw results

meta = MetadataCatalog.get(cfg.DATASETS.TRAIN[0]) v = Visualizer(img[:, :, ::-1], meta, scale=1.0)★
Note img[:, :, ::-1] — Visualizer wants RGB, but cv2 gives BGR. Metadata supplies class names & colors.
out = v.draw_instance_predictions(inst) cv2.imwrite("out.jpg", out.get_image()[:, :, ::-1])★
Draws boxes+masks+labels; convert back to BGR to save with cv2.
v.draw_dataset_dict(sample) # visualize ground-truth annotations
Sanity-check your registered dataset's labels before training.

6Register custom dataCOCO format

from detectron2.data.datasets import register_coco_instances register_coco_instances("my_train", {}, "train.json", "train/imgs")★
The easy path for COCO-format annotations: name, metadata, JSON, image dir. Register train & val separately.
DatasetCatalog.register("my_ds", my_loader_fn) MetadataCatalog.get("my_ds").thing_classes = ["cat", "dog"]★
For non-COCO formats: register a function returning a list of dataset dicts, and set class names in the metadata.
MetadataCatalog.get("my_train").thing_classes # the class names
Metadata (class names, colors) is what turns class indices back into labels in visualization & eval.

7Fine-tune (DefaultTrainer)transfer learning

cfg.DATASETS.TRAIN = ("my_train",); cfg.DATASETS.TEST = ("my_val",) cfg.MODEL.ROI_HEADS.NUM_CLASSES = 2 # your class count (no background)★
Set NUM_CLASSES to your class count (background is implicit). Start from zoo MODEL.WEIGHTS for transfer learning.
cfg.SOLVER.IMS_PER_BATCH = 2; cfg.SOLVER.BASE_LR = 0.00025 cfg.SOLVER.MAX_ITER = 1000; cfg.OUTPUT_DIR = "./out"★
Detectron2 counts iterations, not epochs. Tune LR/iters/batch to your dataset & GPU.
trainer = DefaultTrainer(cfg) trainer.resume_or_load(resume=False) trainer.train()★
resume=False = start from the pretrained weights (fine-tune). Checkpoints land in OUTPUT_DIR.

8EvaluationCOCO metrics

from detectron2.evaluation import COCOEvaluator, inference_on_dataset from detectron2.data import build_detection_test_loader★
Standard COCO mAP evaluation over a registered dataset.
ev = COCOEvaluator("my_val", output_dir="./out") loader = build_detection_test_loader(cfg, "my_val") inference_on_dataset(trainer.model, loader, ev)★
Returns AP/AP50/AP75 per category. Subclass DefaultTrainer.build_evaluator to eval during training.

9Tasks & configsmodel zoo

"COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml" # boxes★
Object detection. retinanet_* for one-stage.
"COCO-InstanceSegmentation/mask_rcnn_*" # boxes + masks★
Instance segmentation (Mask R-CNN). PointRend for crisp mask boundaries.
"COCO-Keypoints/*" · "COCO-PanopticSegmentation/*" · "LVIS/*"
Keypoints (pose), panoptic (things+stuff), long-tail (LVIS). ViTDet/MViTv2 backbones on main.
# newer configs use LazyConfig (.py) instead of yacs (.yaml)
Some recent models ship a Python LazyConfig; loaded via LazyConfig.load rather than get_cfg.

!Common gotchasread before shipping

install must match torch + CUDA
The #1 pain: a version mismatch fails at import or with CUDA errors. Use the build matching your exact PyTorch/CUDA, or build from source.
BGR in, RGB for Visualizer
Predictor takes cv2 BGR; Visualizer wants RGB (img[:, :, ::-1]). Mixing them gives blue-tinted output/wrong colors.
NUM_CLASSES excludes background
Set it to the number of your classes only. Off-by-one here silently wrecks training.
iterations, not epochs
SOLVER.MAX_ITER is total steps. Convert from epochs via dataset size / batch size yourself.
same yaml for config & weights
Config and checkpoint must correspond, or shapes mismatch on load.

Detectron2 cheat sheet