agentscope-ai/agentscope · error · ImportError

Please install pandas to use the Excel parser. You can insta

Error message

Please install pandas to use the Excel parser. You can install it by `pip install pandas` (or `pip install agentscope[rag]`).

What it means

The Excel parser needs the optional pandas dependency. Importing pandas inside parse() failed, so an ImportError with install instructions is raised, chained to the original ImportError.

Source

Thrown at src/agentscope/rag/_parser/_excel.py:245

        Returns:
            `list[Section]`:
                Sections in sheet order.  When ``separate_sheet=True``,
                text sections carry ``{"sheet": "<name>"}`` metadata
                and image sections add
                ``{"media_type": "image/..."}``.  When
                ``separate_sheet=False`` (default), all text is merged
                into a single section with ``metadata={}``.

        Raises:
            `FileNotFoundError`: If ``file`` is a ``str`` pointing to
                a path that does not exist.
            `ImportError`: If :mod:`pandas` is not installed.
            `ValueError`: If the bytes cannot be parsed.
        """
        try:
            import pandas as pd
        except ImportError as e:
            raise ImportError(
                "Please install pandas to use the Excel parser. "
                "You can install it by `pip install pandas` (or "
                "`pip install agentscope[rag]`).",
            ) from e

        if isinstance(file, str):
            excel_file = pd.ExcelFile(file)
        else:
            excel_file = pd.ExcelFile(io.BytesIO(file))

        workbook = None
        try:
            if self.include_image:
                try:
                    from openpyxl import load_workbook

                    if isinstance(file, str):
                        workbook = load_workbook(file)

View on GitHub (pinned to e90f1c7592)

Solutions

pip install pandas (or pip install 'agentscope[rag]')
Add pandas to your requirements/pyproject alongside agentscope
Pre-check availability and give users a friendly message if Excel parsing is optional in your app

Example fix

# before
parser = ExcelParser()  # later: ImportError at parse()

# after
# pip install 'agentscope[rag]'
parser = ExcelParser()

Defensive patterns

Strategy: validation

Validate before calling

try:
    import pandas  # noqa
    pandas_ok = True
except ImportError:
    pandas_ok = False
if not pandas_ok:
    raise SystemExit('pip install agentscope[rag] to enable Excel parsing')

Try / catch

try:
    parser.parse(f)
except ImportError as e:
    if 'pandas' not in str(e):
        raise
    logger.warning('Excel parsing disabled: install pandas')

Prevention

Install agentscope[rag] in environments that parse documents
Feature-detect optional parsers at startup

When it happens

Trigger: Calling ExcelParser.parse(...) in an environment where pandas is not installed (agentscope installed without the [rag] extra).

Common situations: pip install agentscope without extras; slim Docker images; CI environments missing optional deps.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/caad98f622555e01. Report an issue: GitHub.