open-mmlab/mmdetection · error · RuntimeError

Failed to import `cityscapesscripts`.Please try to install o

Error message

Failed to import `cityscapesscripts`.Please try to install official cityscapesscripts by "pip install cityscapesscripts"

What it means

CityscapesMetric.__init__ eagerly checks that cityscapesscripts is importable and raises RuntimeError at construction time (not eval time) if the optional dependency is missing.

Source

Thrown at mmdet/evaluation/metrics/cityscapes_metric.py:70

        file_client_args (dict, optional): Arguments to instantiate the
            corresponding backend in mmdet <= 3.0.0rc6. Defaults to None.
        backend_args (dict, optional): Arguments to instantiate the
            corresponding backend. Defaults to None.
    """
    default_prefix: Optional[str] = 'cityscapes'

    def __init__(self,
                 outfile_prefix: str,
                 seg_prefix: Optional[str] = None,
                 format_only: bool = False,
                 collect_device: str = 'cpu',
                 prefix: Optional[str] = None,
                 dump_matches: bool = False,
                 file_client_args: dict = None,
                 backend_args: dict = None) -> None:

        if not HAS_CITYSCAPESAPI:
            raise RuntimeError('Failed to import `cityscapesscripts`.'
                               'Please try to install official '
                               'cityscapesscripts by '
                               '"pip install cityscapesscripts"')
        super().__init__(collect_device=collect_device, prefix=prefix)

        self.tmp_dir = None
        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.'
        else:
            assert seg_prefix is not None, '`seg_prefix` is necessary when '
            'computing the CityScapes metrics'

        if outfile_prefix is None:
            self.tmp_dir = tempfile.TemporaryDirectory()
            self.outfile_prefix = osp.join(self.tmp_dir.name, 'results')

View on GitHub (pinned to cfd5d3a985)

Solutions

pip install cityscapesscripts
Verify import: python -c "from cityscapesscripts.evaluation import evalPixelLevelSemanticLabeling"
If Cityscapes official metric is not needed, replace with CocoMetric in the config

Example fix

# before
val_metric = dict(type='CityscapesMetric')  # RuntimeError at build
# after
# after installing cityscapesscripts:
val_metric = dict(type='CityscapesMetric')

Defensive patterns

Strategy: validation

Validate before calling

from mmdet.evaluation.metrics.cityscapes_metric import HAS_CITYSCAPESAPI
assert HAS_CITYSCAPESAPI, 'pip install cityscapesscripts before using CityscapesMetric'

Try / catch

try:
    CityscapesMetric()
except RuntimeError as e:
    if 'cityscapesscripts' in str(e):
        raise SystemExit('Install cityscapesscripts or switch to CocoMetric')
    raise

Prevention

Install cityscapesscripts before building configs containing CityscapesMetric
Conditionally choose metric class based on dependency availability

When it happens

Trigger: Instantiating CityscapesMetric in a config without cityscapesscripts installed; the import fails at mmdet import time so HAS_CITYSCAPESAPI is False.

Common situations: Training scripts that build metrics in eval hooks crashing on configs with CityscapesMetric; CI environments without optional extras.

Related errors

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