{"record":{"id":"0490c7c8840217ba","repo":"docling-project/docling","slug":"the-python-docx-package-is-required-to-process-w","errorCode":null,"errorMessage":"The 'python-docx' package is required to process Word files. Install it with `pip install 'docling-slim[format-docx]'`.","messagePattern":"The 'python-docx' package is required to process Word files\\. Install it with `pip install 'docling-slim\\[format-docx\\]'`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/backend/msword_backend.py","lineNumber":389,"sourceCode":"\n    - Definition/call form: ``def fib(n):``, ``class Foo(Bar):``, ``for x in range(n):``\n    - Bare-expression form: ``while True:``, ``if x == 0:``, ``with open(f) as fh:``\n\n    Prose labels ending in ``:`` (e.g. ``\"Note:\"``) are excluded by the leading\n    keyword anchor combined with requiring at least one non-space character after\n    the keyword. Statement keywords that do not produce block headers (``return``,\n    ``import``) are omitted to avoid false positives on prose.\n    \"\"\"\n\n    @override\n    def __init__(\n        self,\n        in_doc: InputDocument,\n        path_or_stream: BytesIO | Path,\n        options: MsWordBackendOptions | None = None,\n    ) -> None:\n        if not _DOCX_AVAILABLE:\n            raise ImportError(_INSTALL_HINT) from _DOCX_IMPORT_ERROR\n        if options is None:\n            options = MsWordBackendOptions()\n        if in_doc.format == InputFormat.DOC:\n            path_or_stream = convert_to_modern_format(path_or_stream, \"doc\", \"docx\")\n        super().__init__(in_doc, path_or_stream, options)\n        self.XML_KEY = f\"{self._W_NS_CLARK}val\"\n        self.xml_namespaces = {\n            \"w\": \"http://schemas.microsoft.com/office/word/2003/wordml\"\n        }\n        self.blip_xpath_expr = etree.XPath(\n            \".//a:blip\", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES\n        )\n        self.vml_imagedata_xpath_expr = etree.XPath(\n            \".//v:imagedata\", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES\n        )\n        # self.initialise(path_or_stream)\n        # Word file:\n        self.path_or_stream: BytesIO | Path = path_or_stream","sourceCodeStart":371,"sourceCodeEnd":407,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/msword_backend.py#L371-L407","documentation":"ImportError raised by MsWordDocumentBackend.__init__ when the python-docx dependency is absent (module-level import failed). Docling's slim install omits format backends, so docx support must be added via the format-docx extra. The chained cause (_DOCX_IMPORT_ERROR) preserves the original import failure.","triggerScenarios":"Using docling-slim (or a minimal install) and passing a DOCX/DOC InputFormat document; the backend is selected by format, then __init__ raises immediately because _DOCX_AVAILABLE is False.","commonSituations":"Installing docling-slim to keep images lean, Docker images built from slim requirements, or CI environments that only installed the core package.","solutions":["pip install 'docling-slim[format-docx]' (or the full 'docling' meta-package which includes it).","Verify with python -c \"import docx\" that python-docx now imports.","In Dockerfiles, add the extra to the install layer and rebuild.","For offline/air-gapped environments, vendor the wheel into your index before installing the extra."],"exampleFix":"# before\npip install docling-slim\n# -> ImportError: The 'python-docx' package is required...\n\n# after\npip install 'docling-slim[format-docx]'","handlingStrategy":"validation","validationCode":"try:\n    import docx  # python-docx\n    DOCX_OK = True\nexcept ImportError:\n    DOCX_OK = False\nassert DOCX_OK, \"install 'docling-slim[format-docx]'\"","typeGuard":null,"tryCatchPattern":"try:\n    backend = MsWordDocumentBackend(in_doc, path)\nexcept ImportError as e:\n    logger.error('missing extra: %s', e)\n    raise","preventionTips":["Declare docling extras in requirements per format you ingest","Add a startup probe that imports optional deps for every enabled InputFormat","Pin 'docling-slim[format-docx]' (or full docling) in Dockerfiles"],"tags":["dependency","install","docx","extras"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}