agentscope-ai/agentscope · error · ImportError

Please install python-docx to use the Word parser. You can i

Error message

Please install python-docx to use the Word parser. You can install it by `pip install python-docx` (or `pip install agentscope[rag]`).

What it means

WordParser.parse() lazily imports python-docx and re-raises ImportError with install instructions when the package is missing. The rag extra bundles python-docx.

Source

Thrown at src/agentscope/rag/_parser/_word.py:268

        Returns:
            `list[Section]`:
                Sections in document order.

        Raises:
            `FileNotFoundError`: If ``file`` is a ``str`` pointing to
                a path that does not exist.
            `ImportError`: If :mod:`python-docx` is not installed.
            `ValueError`: If the bytes cannot be parsed.
        """
        try:
            from docx import Document as DocxDocument
            from docx.oxml import CT_P, CT_Tbl
            from docx.text.paragraph import Paragraph
            from docx.table import Table
            from docx.oxml.ns import qn
        except ImportError as e:
            raise ImportError(
                "Please install python-docx to use the Word parser. "
                "You can install it by `pip install python-docx` (or "
                "`pip install agentscope[rag]`).",
            ) from e

        if isinstance(file, str):
            doc = DocxDocument(file)
        else:
            doc = DocxDocument(io.BytesIO(file))

        sections: list[Section] = []
        text_buffer: list[str] = []

        def flush_text() -> None:
            if not text_buffer:
                return
            sections.append(
                Section(

View on GitHub (pinned to e90f1c7592)

Solutions

1. pip install 'agentscope[rag]'
2. or pip install python-docx
3. Add the extra to requirements.txt/pyproject dependencies
4. Rebuild the Docker image with the rag extra

Example fix

# before
pip install agentscope
# after
pip install 'agentscope[rag]'

import importlib.util
has_docx = importlib.util.find_spec('docx') is not None

try:
    parser.parse(f)
except ImportError as e:
    if 'python-docx' in str(e): raise RuntimeError('rag extra missing') from e
    raise

When it happens

Trigger: Calling WordParser.parse() in an environment where python-docx is not installed — e.g. pip install agentscope without [rag], or a slim Docker image.

Common situations: Minimal deployment images, CI environments, or a fresh venv where only the core agentscope package was installed.

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

• module {__name__!r} has no attribute {name!r}
• module 'agentscope.app.storage' has no attribute {name!r}
• The table_format must be one of 'markdown' or 'json', got {t

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