{"id":7419,"library":"mmdet","title":"MMDetection: OpenMMLab Detection Toolbox and Benchmark","description":"MMDetection is an open-source object detection toolbox based on PyTorch, part of the OpenMMLab project. It provides a comprehensive collection of detection, instance segmentation, and object grounding algorithms, along with a benchmark for various computer vision tasks. Currently at version 3.3.0, it features frequent updates, including state-of-the-art models like Grounding DINO and various Transformer-based detectors, and integrates closely with other OpenMMLab libraries like MMEngine and MMCV.","status":"active","version":"3.3.0","language":"en","source_language":"en","source_url":"https://github.com/open-mmlab/mmdetection","tags":["object detection","computer vision","deep learning","OpenMMLab","PyTorch","transformer","grounding DINO","object tracking","instance segmentation"],"install":[{"cmd":"pip install openmim\nmim install 'mmcv>=2.0.0' # or 'mmcv-lite>=2.0.0'\nmim install mmdet","lang":"bash","label":"Recommended installation with MIM"},{"cmd":"pip install 'torch>=1.8.0,<2.3.0' 'torchvision>=0.9.0,<0.16.0' # Adjust for your CUDA version\npip install -U openmim\nmim install 'mmengine>=0.7.1'\nmim install 'mmcv>=2.0.0' # or 'mmcv-lite>=2.0.0'\n# Clone and install mmdet from source for editable mode or latest features\ngit clone https://github.com/open-mmlab/mmdetection.git\ncd mmdetection\npip install -v -e .","lang":"bash","label":"From source (with PyTorch and core OpenMMLab deps)"}],"dependencies":[{"reason":"Core deep learning framework. MMDetection 3.x requires PyTorch 1.8+.","package":"torch","optional":false},{"reason":"Companion library for PyTorch, providing datasets, models, and image transformations.","package":"torchvision","optional":false},{"reason":"OpenMMLab's foundational library for training deep learning models, used as the new runner in MMDetection 3.x.","package":"mmengine","optional":false},{"reason":"OpenMMLab's foundational library for computer vision, providing common utilities and CUDA operators. MMDetection 3.x requires MMCV 2.0.0+.","package":"mmcv","optional":false},{"reason":"OpenMMLab's unified package manager, simplifies installation of OpenMMLab projects and their dependencies.","package":"openmim","optional":true},{"reason":"Required for COCO dataset evaluation.","package":"pycocotools","optional":true}],"imports":[{"note":"For MMDetection 3.x, DetInferencer is the recommended high-level API for inference, replacing direct calls to init_detector and inference_detector used in 2.x.","wrong":"from mmdet.apis import init_detector, inference_detector","symbol":"DetInferencer","correct":"from mmdet.apis import DetInferencer"},{"note":"Common import for extending or customizing detector models.","symbol":"BaseDetector","correct":"from mmdet.models import BaseDetector"}],"quickstart":{"code":"import os\nimport torch\nfrom mmdet.apis import DetInferencer\nimport mmcv # For image loading if not using DetInferencer's internal loading\n\n# Ensure an image file exists for the demo\n# For simplicity, create a dummy image or download one\nimg_path = 'demo_image.jpg'\nif not os.path.exists(img_path):\n    # Using a common utility to create a simple dummy image\n    from PIL import Image\n    img = Image.new('RGB', (640, 480), color = 'red')\n    img.save(img_path)\n    print(f\"Created dummy image: {img_path}\")\n\n# Initialize the DetInferencer with a pre-trained model.\n# The model weights will be automatically downloaded.\n# Using device='cpu' for broader compatibility.\n# rtmdet_tiny is a lightweight model for quick demo.\ninferencer = DetInferencer(model='rtmdet_tiny_8xb32-300e_coco', device='cpu')\n\n# Perform inference on the image\n# The result contains detections, bounding boxes, labels, and scores.\nresult = inferencer(img_path, show=False) # show=False to prevent immediate display\n\n# Print detected objects (example for the first image if batched)\nif isinstance(result['predictions'], list) and len(result['predictions']) > 0:\n    first_image_predictions = result['predictions'][0]\n    print(f\"Detected objects in {img_path}:\")\n    for box, label, score in zip(first_image_predictions['bboxes'], first_image_predictions['labels'], first_image_predictions['scores']):\n        print(f\"  Label: {label}, Score: {score:.2f}, BBox: {list(map(int, box))}\")\n\n# To save the visualization, specify an output directory\noutput_dir = 'mmdet_output'\nos.makedirs(output_dir, exist_ok=True)\ninferencer(img_path, out_dir=output_dir)\nprint(f\"Inference results saved to {output_dir}\")\n\n# Clean up the dummy image and output directory (optional)\nos.remove(img_path)\n# For a full cleanup, you might also remove output_dir recursively\n# import shutil; shutil.rmtree(output_dir)\n","lang":"python","description":"This quickstart demonstrates how to perform inference using MMDetection 3.x's `DetInferencer` class. It downloads a pre-trained `rtmdet_tiny` model, runs inference on a dummy image, prints the detected objects, and saves the visualization to a specified output directory."},"warnings":[{"fix":"Refer to the official migration guide (from 2.x to 3.x) and update configuration files, API calls, and data processing logic. Ensure `mmengine` and `mmcv>=2.0.0` are installed.","message":"MMDetection 3.x introduced significant breaking changes compared to 2.x, including a completely revamped config system, data pipelines, API, and a new dependency on MMEngine.","severity":"breaking","affected_versions":"3.0.0 and later"},{"fix":"Upgrade your Python environment to 3.7 or a later supported version (e.g., 3.8, 3.9, 3.10, 3.11).","message":"Python 3.6 support has been deprecated since MMDetection 2.28.0. MMDetection 3.x officially requires Python 3.7 or newer.","severity":"deprecated","affected_versions":"2.28.0 and later (especially 3.x)"},{"fix":"Always install `mmcv` (or `mmcv-full` for older versions) using `mim install` or explicitly check compatibility tables in the official documentation before manual installation. Ensure `mmcv` version matches MMDetection and PyTorch/CUDA versions.","message":"MMCV version compatibility is crucial. Mismatches between MMDetection, PyTorch, and MMCV versions (especially `mmcv-full` vs `mmcv` in v2.x) are a very common source of installation and runtime errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify that your PyTorch, CUDA toolkit, and MMCV (especially custom ops) are compiled with compatible CUDA versions and GCC. Use `python mmdet/utils/collect_env.py` to diagnose the environment. Reinstall PyTorch and MMCV if necessary, ensuring correct CUDA versions.","message":"Runtime errors like 'undefined symbol', 'DLL load failed', 'invalid device function', or 'no kernel image is available for execution' often stem from CUDA, PyTorch, and MMCV compilation mismatches.","severity":"gotcha","affected_versions":"All versions with GPU support"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Uninstall any existing `mmcv` or `mmcv-full`: `pip uninstall mmcv mmcv-full`. Then, use `mim install mmcv>=2.0.0` (for MMDetection 3.x) or consult the specific compatibility table for your MMDetection version.","cause":"Incorrect or incompatible installation of MMCV. In MMDetection 2.x, it was `mmcv-full`, but for 3.x, it's `mmcv` (or `mmcv-lite` for CPU-only). Version mismatches are common.","error":"ModuleNotFoundError: No module named 'mmcv._ext' OR AssertionError: MMCV==xxx is used but incompatible. Please install mmcv>=xxx, <=xxx."},{"fix":"Always provide the path to a valid configuration file. Example: `python tools/train.py configs/rtmdet/rtmdet_s_8xb32-300e_coco.py`.","cause":"When running training or testing scripts (e.g., `tools/train.py`), the configuration file specifying the model, dataset, and training parameters was not provided.","error":"train.py: error: the following arguments are required: config"},{"fix":"For MMDetection 3.x, use `from mmdet.apis import DetInferencer` for high-level inference. If it's a general import error, ensure MMDetection is correctly installed (`pip install -e .` from source or `mim install mmdet`).","cause":"This usually indicates trying to use an MMDetection 2.x API (`init_detector`, `inference_detector`) in a MMDetection 3.x environment, or general issues with `mmdet` installation.","error":"ImportError: cannot import name 'init_detector' from 'mmdet.apis'"},{"fix":"Reduce batch size, decrease image resolution, use gradient accumulation, or enable automatic mixed precision (AMP) training if your model and PyTorch version support it. Check `gpu_assign_thr` or `find_unused_parameters=True` in config for specific scenarios.","cause":"Training or inference with high-resolution images, large batch sizes, or complex models exceeds the available GPU memory.","error":"GPU out of memory (OOM)"}]}