open-mmlab/mmdetection · error · RuntimeError

Package lvis is not installed. Please run "pip install git+h

Error message

Package lvis is not installed. Please run "pip install git+https://github.com/lvis-dataset/lvis-api.git".

What it means

LVISMetric.__init__ raises RuntimeError when the optional `lvis` package (LVIS API) is not importable. mmdet imports lvis lazily/optionally because it is not a hard dependency, and LVIS-based evaluation is impossible without it.

Source

Thrown at mmdet/evaluation/metrics/lvis_metric.py:95

    """

    default_prefix: Optional[str] = 'lvis'

    def __init__(self,
                 ann_file: Optional[str] = None,
                 metric: Union[str, List[str]] = 'bbox',
                 classwise: bool = False,
                 proposal_nums: Sequence[int] = (100, 300, 1000),
                 iou_thrs: Optional[Union[float, Sequence[float]]] = None,
                 metric_items: Optional[Sequence[str]] = None,
                 format_only: bool = False,
                 outfile_prefix: Optional[str] = None,
                 collect_device: str = 'cpu',
                 prefix: Optional[str] = None,
                 file_client_args: dict = None,
                 backend_args: dict = None) -> None:
        if lvis is None:
            raise RuntimeError(
                'Package lvis is not installed. Please run "pip install '
                'git+https://github.com/lvis-dataset/lvis-api.git".')
        super().__init__(collect_device=collect_device, prefix=prefix)
        # coco evaluation metrics
        self.metrics = metric if isinstance(metric, list) else [metric]
        allowed_metrics = ['bbox', 'segm', 'proposal', 'proposal_fast']
        for metric in self.metrics:
            if metric not in allowed_metrics:
                raise KeyError(
                    "metric should be one of 'bbox', 'segm', 'proposal', "
                    f"'proposal_fast', but got {metric}.")

        # do class wise evaluation, default False
        self.classwise = classwise

        # proposal_nums used to compute recall or precision.
        self.proposal_nums = list(proposal_nums)

View on GitHub (pinned to cfd5d3a985)

Solutions

  1. pip install git+https://github.com/lvis-dataset/lvis-api.git
  2. If offline, install from a mirror or vendored wheel of lvis-api, then verify with `python -c "import lvis"`
  3. Only use LVISMetric when you actually evaluate on LVIS annotations; use CocoMetric for COCO datasets

Example fix

// before
$ python tools/test.py config.py ckpt.pth  # RuntimeError: Package lvis is not installed
// after
$ pip install git+https://github.com/lvis-dataset/lvis-api.git
$ python tools/test.py config.py ckpt.pth
Defensive patterns

Strategy: validation

Validate before calling

try:
    import lvis  # noqa: F401
    has_lvis = True
except ImportError:
    has_lvis = False
if not has_lvis:
    raise SystemExit('Install lvis first: pip install git+https://github.com/lvis-dataset/lvis-api.git')

Try / catch

try:
    from mmdet.evaluation import LVISMetric
    evaluator = LVISMetric(ann_file=ann)
except RuntimeError as e:
    if 'lvis' in str(e):
        subprocess.check_call([sys.executable, '-m', 'pip', 'install',
            'git+https://github.com/lvis-dataset/lvis-api.git'])
        evaluator = LVISMetric(ann_file=ann)
    else:
        raise

Prevention

When it happens

Trigger: Instantiating LVISMetric (config with val_evaluator=dict(type='LVISMetric')) in an environment where `import lvis` failed, so the module-level lvis symbol is None.

Common situations: Running LVIS dataset evaluation in a fresh mmdet install without the extra dependency; a Docker image built from requirements.txt which omits the lvis api package; installing the wrong/renamed lvis package from PyPI instead of the GitHub API repo.

Related errors

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