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

CocoPanopticMetric.__init__ requires the unofficial `panopticapi` package (pq_compute from cocodataset) to compute Panoptic Quality. The import is guarded (`panopticapi is None`), and if it's missing the constructor raises RuntimeError with the pip command. Panoptic segmentation eval is impossible without it.

Source

Thrown at mmdet/evaluation/metrics/coco_panoptic_metric.py:85

            names to disambiguate homonymous metrics of different evaluators.
            If prefix is not provided in the argument, self.default_prefix
            will be used instead. Defaults to None.
    """
    default_prefix: Optional[str] = 'coco_panoptic'

    def __init__(self,
                 ann_file: Optional[str] = None,
                 seg_prefix: Optional[str] = None,
                 classwise: bool = False,
                 format_only: bool = False,
                 outfile_prefix: Optional[str] = None,
                 nproc: int = 32,
                 file_client_args: dict = None,
                 backend_args: dict = None,
                 collect_device: str = 'cpu',
                 prefix: Optional[str] = None) -> None:
        if panopticapi is None:
            raise RuntimeError(
                'panopticapi is not installed, please install it by: '
                'pip install git+https://github.com/cocodataset/'
                'panopticapi.git.')

        super().__init__(collect_device=collect_device, prefix=prefix)
        self.classwise = classwise
        self.format_only = format_only
        if self.format_only:
            assert outfile_prefix is not None, 'outfile_prefix must be not'
            'None when format_only is True, otherwise the result files will'
            'be saved to a temp directory which will be cleaned up at the end.'

        self.tmp_dir = None
        # outfile_prefix should be a prefix of a path which points to a shared
        # storage when train or test with multi nodes.
        self.outfile_prefix = outfile_prefix
        if outfile_prefix is None:
            self.tmp_dir = tempfile.TemporaryDirectory()

View on GitHub (pinned to cfd5d3a985)

Solutions

pip install git+https://github.com/cocodataset/panopticapi.git
Verify with `python -c "import panopticapi"` in the SAME env used for training
Add the install line to your Dockerfile/CI script so eval jobs have it

Example fix

# before: RuntimeError on CocoPanopticMetric(...)
# after
pip install git+https://github.com/cocodataset/panopticapi.git
python -c 'import panopticapi; print("ok")'

Defensive patterns

Strategy: validation

Validate before calling

try:
    import panopticapi  # noqa
    ok = True
except ImportError:
    ok = False
assert ok, 'pip install git+https://github.com/cocodataset/panopticapi.git before panoptic eval'

Type guard

def panoptic_eval_available() -> bool:
    try:
        import panopticapi  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

try:
    CocoPanopticMetric(...)
except RuntimeError as e:
    if 'panopticapi' in str(e):
        subprocess.check_call([sys.executable, '-m', 'pip', 'install',
            'git+https://github.com/cocodataset/panopticapi.git'])
    raise

Prevention

Install panopticapi in every env/Dockerfile that runs panoptic configs
Guard the import in setup scripts and fail fast with a clear message
Test `import panopticapi` in CI before panoptic eval jobs

When it happens

Trigger: Instantiating CocoPanopticMetric (a panoptic seg val_evaluator) in an environment where `import panopticapi` failed; fresh mmdetection install without the extra panoptic dependency; CI images built from requirements.txt which does not include panopticapi.

Common situations: Running a panoptic config (e.g. Panoptic FPN) for the first time; new conda/docker env; panopticapi installed into a different Python env than the one running training.

Related errors

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