agentscope-ai/agentscope · error · ImportError

Please install pypdf to use the PDF parser. You can install…

Error message

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

What it means

The PDF parser needs the optional pypdf dependency. Its import inside parse() failed, raising ImportError with install instructions chained to the original error.

Solutions

pip install pypdf (or pip install 'agentscope[rag]')
Pin pypdf in your project dependencies
Feature-detect at startup if PDF ingestion is optional

Example fix

# before
PDFParser().parse('doc.pdf')  # ImportError

# after
# pip install 'agentscope[rag]'
PDFParser().parse('doc.pdf')

Defensive patterns

Strategy: validation

Validate before calling

try:
    import pypdf  # noqa
    pdf_ok = True
except ImportError:
    pdf_ok = False

Try / catch

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

Prevention

Include agentscope[rag] in deployment images
Check optional deps before enabling document ingestion features

When it happens

Trigger: Calling PDFParser.parse(...) without pypdf installed (agentscope installed without [rag] extra).

Common situations: Base agentscope install in slim containers; forgetting optional extras in deployment images.

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/e40b35365a8783c4. Report an issue: GitHub.

Appendix: source

Thrown at src/agentscope/rag/_parser/_pdf.py:69

            `list[Section]`:
                One Section per page, in document order.  Each
                section's metadata holds ``{"page": <starting at 1>}``.

        Raises:
            `FileNotFoundError`: If ``file`` is a ``str`` pointing to
                a path that does not exist.
            `ImportError`: If :mod:`pypdf` is not installed.
            `ValueError`: If the bytes cannot be parsed as PDF.
        """
        if isinstance(file, str):
            with open(file, "rb") as fp:
                file = fp.read()

        try:
            from pypdf import PdfReader
            from pypdf.errors import PdfReadError
        except ImportError as e:
            raise ImportError(
                "Please install pypdf to use the PDF parser. "
                "You can install it by `pip install pypdf` (or "
                "`pip install agentscope[rag]`).",
            ) from e

        try:
            reader = PdfReader(io.BytesIO(file))
        except PdfReadError as e:
            raise ValueError(
                f"Failed to parse {filename!r} as PDF: {e}",
            ) from e

        sections: list[Section] = []
        for page_idx, page in enumerate(reader.pages, start=1):
            text = page.extract_text() or ""
            sections.append(
                Section(
                    content=TextBlock(text=text),

View on GitHub (pinned to e90f1c7592)