open-mmlab/mmdetection · error · RuntimeError

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

Error message

COCOEvalCap is not installed, please install it by: pip install pycocoevalcap

What it means

COCOCaptionMetric computes captioning scores via COCOEvalCap from the pycocoevalcap package; at construction it raises RuntimeError if the optional import failed.

Source

Thrown at mmdet/evaluation/metrics/coco_caption_metric.py:44

    Args:
        ann_file (str): the path for the COCO format caption ground truth
            json file, load for evaluations.
        collect_device (str): Device name used for collecting results from
            different ranks during distributed training. Must be 'cpu' or
            'gpu'. Defaults to 'cpu'.
        prefix (str, optional): The prefix that will be added in the metric
            names to disambiguate homonymous metrics of different evaluators.
            If prefix is not provided in the argument, self.default_prefix
            will be used instead. Should be modified according to the
            `retrieval_type` for unambiguous results. Defaults to TR.
    """

    def __init__(self,
                 ann_file: str,
                 collect_device: str = 'cpu',
                 prefix: Optional[str] = None):
        if COCOEvalCap is None:
            raise RuntimeError(
                'COCOEvalCap is not installed, please install it by: '
                'pip install pycocoevalcap')

        super().__init__(collect_device=collect_device, prefix=prefix)
        self.ann_file = ann_file

    def process(self, data_batch, data_samples):
        """Process one batch of data samples.

        The processed results should be stored in ``self.results``, which will
        be used to computed the metrics when all batches have been processed.

        Args:
            data_batch: A batch of data from the dataloader.
            data_samples (Sequence[dict]): A batch of outputs from the model.
        """

        for data_sample in data_samples:

View on GitHub (pinned to cfd5d3a985)

Solutions

pip install pycocoevalcap
If METEOR fails, ensure a JRE is available (apt-get install default-jre) or use a scorer subset
Verify: python -c "from pycocoevalcap.tokenizer.ptbtokenizer import PTBTokenizer"

Example fix

# before
metric = COCOCaptionMetric(ann_file=...)  # RuntimeError
# after
# pip install pycocoevalcap
metric = COCOCaptionMetric(ann_file=...)

Defensive patterns

Strategy: validation

Validate before calling

try:
    from pycocoevalcap.cocoEval import COCOEvalCap  # noqa
except ImportError:
    raise SystemExit('pip install pycocoevalcap')

Try / catch

try:
    COCOCaptionMetric(ann_file)
except RuntimeError as e:
    if 'pycocoevalcap' in str(e):
        raise SystemExit('Install pycocoevalcap (and a JRE for METEOR)')
    raise

Prevention

Install pycocoevalcap and a JRE before caption eval
Smoke-test the import in CI environments

When it happens

Trigger: Instantiating COCOCaptionMetric without `pip install pycocoevalcap`; package installed but its Java/Perl-backed scorers (METEOR, ROUGE) fail to import on some systems.

Common situations: Evaluating image-captioning models in minimal docker images; systems lacking Java for pycocoevalcap's METEOR scorer.

Related errors

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