open-mmlab/mmdetection · error · RuntimeError

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

When DetInferencer.postprocess runs pred2dict on a data_sample containing 'pred_panoptic_seg', it needs the panopticapi package to encode the panoptic segmentation to COCO RLE format. If the optional import of VOID (from panopticapi.utils) failed at module load, VOID is None and this RuntimeError is raised with install instructions. It is a missing-optional-dependency error, not a logic bug.

Source

Thrown at mmdet/apis/det_inferencer.py:633

                'scores': pred_instances.scores.tolist()
            }
            if 'bboxes' in pred_instances:
                result['bboxes'] = pred_instances.bboxes.tolist()
            if masks is not None:
                if 'bboxes' not in pred_instances or pred_instances.bboxes.sum(
                ) == 0:
                    # Fake bbox, such as the SOLO.
                    bboxes = mask2bbox(masks.cpu()).numpy().tolist()
                    result['bboxes'] = bboxes
                encode_masks = encode_mask_results(pred_instances.masks)
                for encode_mask in encode_masks:
                    if isinstance(encode_mask['counts'], bytes):
                        encode_mask['counts'] = encode_mask['counts'].decode()
                result['masks'] = encode_masks

        if 'pred_panoptic_seg' in data_sample:
            if VOID is None:
                raise RuntimeError(
                    'panopticapi is not installed, please install it by: '
                    'pip install git+https://github.com/cocodataset/'
                    'panopticapi.git.')

            pan = data_sample.pred_panoptic_seg.sem_seg.cpu().numpy()[0]
            pan[pan % INSTANCE_OFFSET == len(
                self.model.dataset_meta['classes'])] = VOID
            pan = id2rgb(pan).astype(np.uint8)

            if is_save_pred:
                mmcv.imwrite(pan[:, :, ::-1], out_img_path)
                result['panoptic_seg_path'] = out_img_path
            else:
                result['panoptic_seg'] = pan

        if is_save_pred:
            mmengine.dump(result, out_json_path)

View on GitHub (pinned to cfd5d3a985)

Solutions

pip install git+https://github.com/cocodataset/panopticapi.git
If behind a firewall, clone the repo and pip install ./panopticapi
If already installed, verify python -c 'from panopticapi.utils import id2rgb, rgb2id' works and fix any underlying import error (often numpy-related)
If you don't need panoptic output dicts, avoid the code path that calls pred2dict with panoptic predictions

Example fix

# before
$ pip list | grep panopticapi  # (nothing)
res = inferencer('img.jpg')  # RuntimeError
# after
$ pip install git+https://github.com/cocodataset/panopticapi.git
res = inferencer('img.jpg')

Defensive patterns

Strategy: validation

Validate before calling

try:
    from panopticapi.utils import id2rgb, rgb2id  # noqa: F401
    HAS_PANOPTICAPI = True
except ImportError:
    HAS_PANOPTICAPI = False
assert HAS_PANOPTICAPI, 'pip install git+https://github.com/cocodataset/panopticapi.git'

Type guard

null

Try / catch

try:
    out = inferencer(imgs)
except RuntimeError as e:
    if 'panopticapi' in str(e):
        raise SystemExit('Missing dependency: pip install git+https://github.com/cocodataset/panopticapi.git')
    raise

Prevention

Declare panopticapi in requirements for any panoptic-model deployment
Add a startup capability check when the config's model type is a panoptic variant (MaskFormer/Mask2Core panoptic heads)
Pin a numpy version compatible with panopticapi if the import fails silently

When it happens

Trigger: Running DetInferencer on a panoptic segmentation model (e.g., MaskFormer/Mask2Former panoptic configs) with pred2dict invoked (default when results are converted to dicts), in an environment where panopticapi is not installed or failed to import.

Common situations: Environments that installed mmdet without the panoptic extra; CI images missing the git dependency; panopticapi import errors due to numpy version incompatibilities (which also leave VOID as None).

Related errors

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