roboflow/supervision · error · ImportError

`metrics` extra is required to run the function. Run `uv pip

Error message

`metrics` extra is required to run the function. Run `uv pip install 'supervision[metrics]'` or `uv add supervision --extra metrics`.

What it means

ImportError raised by ensure_pandas_installed() when a supervision metrics API needs pandas (for dataframe/plot outputs) but pandas is not installed. The metrics functionality is an optional extra; the helper converts a confusing ModuleNotFoundError into an actionable message. Install the 'metrics' extra to get pandas (and plotting deps).

Source

Thrown at src/supervision/metrics/utils/utils.py:5

def ensure_pandas_installed() -> None:
    try:
        import pandas  # noqa
    except ImportError:
        raise ImportError(
            "`metrics` extra is required to run the function."
            " Run `uv pip install 'supervision[metrics]'` or"
            " `uv add supervision --extra metrics`."
        )

View on GitHub (pinned to 7f254d9784)

Solutions

1. Run: uv pip install 'supervision[metrics]' (or pip install 'supervision[metrics]')
2. In a uv-managed project: uv add supervision --extra metrics
3. Or install pandas directly: pip install pandas

Example fix

# before
$ pip install supervision  # no extras
mp.plot()  # ImportError

# after
$ pip install 'supervision[metrics]'
mp.plot()

try:
    import pandas  # noqa: F401
    HAS_PANDAS = True
except ImportError:
    HAS_PANDAS = False

if not HAS_PANDAS:
    print('Install the metrics extra: pip install "supervision[metrics]"')

try:
    result = metric.plot()
except ImportError as e:
    if 'metrics` extra' in str(e):
        raise SystemExit("Missing dependency. Run: pip install 'supervision[metrics]'") from e
    raise

When it happens

Trigger: Calling a metrics API whose output builds a pandas DataFrame (e.g. MeanAveragePrecision.plot() or similar .plot()/.pandas output paths that call ensure_pandas_installed()) in an environment where pandas is absent.

Common situations: Fresh install of supervision without extras (pip install supervision); slim Docker images that trimmed pandas; CI environments installing only the base package.

Related errors

• edges is a dict but class_id is None; KeyPoints must have cl
• No edges defined for class_id={class_id}.
• from_inference() operates on a single result at a time.You c
• 2D boolean mask row count {mask.shape[0]} does not match obj
• 2D boolean mask column count {mask.shape[1]} does not match

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/ce03339949e9e92c. Report an issue: GitHub.