docling-project/docling · error · ImportError

The 'python-docx' package is required to process Word files.

Error message

The 'python-docx' package is required to process Word files. Install it with `pip install 'docling-slim[format-docx]'`.

What it means

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.

Source

Thrown at docling/backend/msword_backend.py:389

    - Definition/call form: ``def fib(n):``, ``class Foo(Bar):``, ``for x in range(n):``
    - Bare-expression form: ``while True:``, ``if x == 0:``, ``with open(f) as fh:``

    Prose labels ending in ``:`` (e.g. ``"Note:"``) are excluded by the leading
    keyword anchor combined with requiring at least one non-space character after
    the keyword. Statement keywords that do not produce block headers (``return``,
    ``import``) are omitted to avoid false positives on prose.
    """

    @override
    def __init__(
        self,
        in_doc: InputDocument,
        path_or_stream: BytesIO | Path,
        options: MsWordBackendOptions | None = None,
    ) -> None:
        if not _DOCX_AVAILABLE:
            raise ImportError(_INSTALL_HINT) from _DOCX_IMPORT_ERROR
        if options is None:
            options = MsWordBackendOptions()
        if in_doc.format == InputFormat.DOC:
            path_or_stream = convert_to_modern_format(path_or_stream, "doc", "docx")
        super().__init__(in_doc, path_or_stream, options)
        self.XML_KEY = f"{self._W_NS_CLARK}val"
        self.xml_namespaces = {
            "w": "http://schemas.microsoft.com/office/word/2003/wordml"
        }
        self.blip_xpath_expr = etree.XPath(
            ".//a:blip", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
        )
        self.vml_imagedata_xpath_expr = etree.XPath(
            ".//v:imagedata", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
        )
        # self.initialise(path_or_stream)
        # Word file:
        self.path_or_stream: BytesIO | Path = path_or_stream

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. pip install 'docling-slim[format-docx]' (or the full 'docling' meta-package which includes it).
2. Verify with python -c "import docx" that python-docx now imports.
3. In Dockerfiles, add the extra to the install layer and rebuild.
4. For offline/air-gapped environments, vendor the wheel into your index before installing the extra.

Example fix

# before
pip install docling-slim
# -> ImportError: The 'python-docx' package is required...

# after
pip install 'docling-slim[format-docx]'

try:
    import docx  # python-docx
    DOCX_OK = True
except ImportError:
    DOCX_OK = False
assert DOCX_OK, "install 'docling-slim[format-docx]'"

try:
    backend = MsWordDocumentBackend(in_doc, path)
except ImportError as e:
    logger.error('missing extra: %s', e)
    raise

When it happens

Trigger: 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.

Common situations: Installing docling-slim to keep images lean, Docker images built from slim requirements, or CI environments that only installed the core package.

Related errors

• The 'odfdo' package is required to process OpenDocument file
• Libreoffice not found
• LibreOffice is required to convert a .{source_suffix} file t
• LibreOffice did not produce the expected output: {converted_
• The 'openpyxl' package is required to process Excel files. I

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/0490c7c8840217ba. Report an issue: GitHub.