{"record":{"id":"55a07c1da59c22f1","repo":"agentscope-ai/agentscope","slug":"please-install-python-docx-to-use-the-word-parser","errorCode":null,"errorMessage":"Please install python-docx to use the Word parser. You can install it by `pip install python-docx` (or `pip install agentscope[rag]`).","messagePattern":"Please install python-docx to use the Word parser\\. You can install it by `pip install python-docx` \\(or `pip install agentscope\\[rag\\]`\\)\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/agentscope/rag/_parser/_word.py","lineNumber":268,"sourceCode":"\n        Returns:\n            `list[Section]`:\n                Sections in document order.\n\n        Raises:\n            `FileNotFoundError`: If ``file`` is a ``str`` pointing to\n                a path that does not exist.\n            `ImportError`: If :mod:`python-docx` is not installed.\n            `ValueError`: If the bytes cannot be parsed.\n        \"\"\"\n        try:\n            from docx import Document as DocxDocument\n            from docx.oxml import CT_P, CT_Tbl\n            from docx.text.paragraph import Paragraph\n            from docx.table import Table\n            from docx.oxml.ns import qn\n        except ImportError as e:\n            raise ImportError(\n                \"Please install python-docx to use the Word parser. \"\n                \"You can install it by `pip install python-docx` (or \"\n                \"`pip install agentscope[rag]`).\",\n            ) from e\n\n        if isinstance(file, str):\n            doc = DocxDocument(file)\n        else:\n            doc = DocxDocument(io.BytesIO(file))\n\n        sections: list[Section] = []\n        text_buffer: list[str] = []\n\n        def flush_text() -> None:\n            if not text_buffer:\n                return\n            sections.append(\n                Section(","sourceCodeStart":250,"sourceCodeEnd":286,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/rag/_parser/_word.py#L250-L286","documentation":"WordParser.parse() lazily imports python-docx and re-raises ImportError with install instructions when the package is missing. The rag extra bundles python-docx.","triggerScenarios":"Calling WordParser.parse() in an environment where python-docx is not installed — e.g. pip install agentscope without [rag], or a slim Docker image.","commonSituations":"Minimal deployment images, CI environments, or a fresh venv where only the core agentscope package was installed.","solutions":["pip install 'agentscope[rag]'","or pip install python-docx","Add the extra to requirements.txt/pyproject dependencies","Rebuild the Docker image with the rag extra"],"exampleFix":"# before\npip install agentscope\n# after\npip install 'agentscope[rag]'","handlingStrategy":"try-catch","validationCode":"import importlib.util\nhas_docx = importlib.util.find_spec('docx') is not None","typeGuard":null,"tryCatchPattern":"try:\n    parser.parse(f)\nexcept ImportError as e:\n    if 'python-docx' in str(e): raise RuntimeError('rag extra missing') from e\n    raise","preventionTips":["Install agentscope[rag] in deployment images","Check find_spec('docx') before enabling Word parsing in UIs"],"tags":["import","dependencies","optional-extra","word"],"backgroundTag":"missing-optional-dependency","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}