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.

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)

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.