run-llama/llama_index · error · ImportError

pandas is required for this function. Please install it with

Error message

pandas is required for this function. Please install it with `pip install pandas`.

What it means

get_retrieval_results_df needs pandas to build summary DataFrames of retrieval metrics (hit_rate, mrr, ...). pandas is an optional dependency of llama-index-core, so the function imports it lazily and raises ImportError with install instructions when it is absent.

Source

Thrown at llama-index-core/llama_index/core/evaluation/notebook_utils.py:21

from collections import defaultdict
from typing import Any, List, Optional, Tuple

from llama_index.core.evaluation import EvaluationResult
from llama_index.core.evaluation.retrieval.base import RetrievalEvalResult

DEFAULT_METRIC_KEYS = ["hit_rate", "mrr"]


def get_retrieval_results_df(
    names: List[str],
    results_arr: List[List[RetrievalEvalResult]],
    metric_keys: Optional[List[str]] = None,
) -> Any:
    """Display retrieval results."""
    try:
        import pandas as pd
    except ImportError:
        raise ImportError(
            "pandas is required for this function. Please install it with `pip install pandas`."
        )

    metric_keys = metric_keys or DEFAULT_METRIC_KEYS

    avg_metrics_dict = defaultdict(list)
    for name, eval_results in zip(names, results_arr):
        metric_dicts = []
        for eval_result in eval_results:
            metric_dict = eval_result.metric_vals_dict
            metric_dicts.append(metric_dict)
        results_df = pd.DataFrame(metric_dicts)

        for metric_key in metric_keys:
            if metric_key not in results_df.columns:
                raise ValueError(f"Metric key {metric_key} not in results_df")
            avg_metrics_dict[metric_key].append(results_df[metric_key].mean())

View on GitHub (pinned to afd0fef371)

Solutions

pip install pandas
Or add pandas to your project's dependencies/requirements so eval environments always have it
If you can't install pandas, compute averages manually from RetrievalEvalResult.metric_vals_dict instead of this helper

Example fix

# before
from llama_index.core.evaluation.notebook_utils import get_retrieval_results_df
df = get_retrieval_results_df(names, results)  # ImportError

# after
# pip install pandas
df = get_retrieval_results_df(names, results)

Defensive patterns

Strategy: validation

Validate before calling

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

if pandas_available():
    df = get_retrieval_results_df(names, results)
else:
    df = None  # aggregate manually from result.metric_vals_dict

Try / catch

try:
    df = get_retrieval_results_df(names, results)
except ImportError as e:
    if "pandas" in str(e):
        logger.error("pip install pandas to use notebook eval helpers")
    raise

Prevention

Include pandas in any environment running eval notebooks/helpers
Declare pandas as a project dependency when eval tooling is part of the repo
Fallback path: average metric_vals_dict values manually without pandas

When it happens

Trigger: Calling get_retrieval_results_df(names, results_arr) in an environment where `import pandas` fails (pandas not installed).

Common situations: Minimal llama-index installs (llama-index-core only) in notebooks or CI; slim Docker images; copying notebook eval helpers into a service that never installed pandas.

Related errors

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/a75cdd9474587896. Report an issue: GitHub.