open-mmlab/mmdetection · error · ImportError

panopticapi is not installed, please install it by: pip inst

Error message

panopticapi is not installed, please install it by: pip install git+https://github.com/cocodataset/panopticapi.git.

What it means

LoadPanopticAnnotations needs COCO's panopticapi package (specifically utils.rgb2id) to convert RGB panoptic PNGs into instance id maps. Its __init__ imports panopticapi and raises ImportError with a git install URL if unavailable, since panopticapi is not a normal PyPI dependency.

Source

Thrown at mmdet/datasets/transforms/loading.py:572

            argument for :func:``mmcv.imfrombytes``.
            See :fun:``mmcv.imfrombytes`` for details.
            Defaults to 'cv2'.
        backend_args (dict, optional): Arguments to instantiate the
            corresponding backend in mmdet >= 3.0.0rc7. Defaults to None.
    """

    def __init__(self,
                 with_bbox: bool = True,
                 with_label: bool = True,
                 with_mask: bool = True,
                 with_seg: bool = True,
                 box_type: str = 'hbox',
                 imdecode_backend: str = 'cv2',
                 backend_args: dict = None) -> None:
        try:
            from panopticapi import utils
        except ImportError:
            raise ImportError(
                'panopticapi is not installed, please install it by: '
                'pip install git+https://github.com/cocodataset/'
                'panopticapi.git.')
        self.rgb2id = utils.rgb2id

        super(LoadPanopticAnnotations, self).__init__(
            with_bbox=with_bbox,
            with_label=with_label,
            with_mask=with_mask,
            with_seg=with_seg,
            with_keypoints=False,
            box_type=box_type,
            imdecode_backend=imdecode_backend,
            backend_args=backend_args)

    def _load_masks_and_semantic_segs(self, results: dict) -> None:
        """Private function to load mask and semantic segmentation annotations.

View on GitHub (pinned to cfd5d3a985)

Solutions

pip install git+https://github.com/cocodataset/panopticapi.git
Alternatively copy the single panopticapi/utils.py into your project or PYTHONPATH if git access is blocked
Confirm with python -c "from panopticapi import utils" before rerunning

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec('panopticapi') is None:
    raise SystemExit('pip install git+https://github.com/cocodataset/panopticapi.git')

Prevention

Install panopticapi before running any panoptic config
Pin it in requirements with a direct-URL git entry

When it happens

Trigger: Building a data pipeline containing dict(type='LoadPanopticAnnotations', ...) (panoptic segmentation / maskformer-style configs) when panopticapi is not installed in the environment.

Common situations: Running panoptic (PanopticFPN, Mask2Former) configs in a fresh env; installing mmdet via pip which does not pull panopticapi; using forked panopticapi that shadowed the name but failed to import.

Related errors

AI-assisted analysis of open-mmlab/mmdetection@cfd5d3a985 (2026-08-27). Data as JSON: /api/errors/671d271c1484f879. Report an issue: GitHub.