{"record":{"id":"c8a73b0b64c543ba","repo":"docling-project/docling","slug":"the-openpyxl-package-is-required-to-process-exce","errorCode":null,"errorMessage":"The 'openpyxl' package is required to process Excel files. Install it with `pip install 'docling-slim[format-xlsx]'`.","messagePattern":"The 'openpyxl' package is required to process Excel files\\. Install it with `pip install 'docling-slim\\[format-xlsx\\]'`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/backend/msexcel_backend.py","lineNumber":297,"sourceCode":"    @override\n    def __init__(\n        self,\n        in_doc: InputDocument,\n        path_or_stream: BytesIO | Path,\n        options: MsExcelBackendOptions | None = None,\n    ) -> None:\n        \"\"\"Initialize the MsExcelDocumentBackend object.\n\n        Parameters:\n            in_doc: The input document object.\n            path_or_stream: The path or stream to the Excel file.\n            options: Backend options for Excel parsing.\n\n        Raises:\n            RuntimeError: An error occurred parsing the file.\n        \"\"\"\n        if not _OPENPYXL_AVAILABLE:\n            raise ImportError(_INSTALL_HINT) from _OPENPYXL_IMPORT_ERROR\n        if in_doc.format == InputFormat.XLS:\n            path_or_stream = convert_to_modern_format(path_or_stream, \"xls\", \"xlsx\")\n        if options is None:\n            options = MsExcelBackendOptions()\n        super().__init__(in_doc, path_or_stream, options)\n\n        self.page_range = in_doc.limits.page_range\n\n        # Current sheet group; set at the start of each sheet conversion\n        self.parent: GroupItem | None = None\n\n        # Lazy-initialized LibreOffice converter for EMF/WMF images\n        self.xlsx_to_pdf_converter: Callable | None = None\n        self.xlsx_to_pdf_converter_init: bool = False\n\n        self.workbook = None\n        try:\n            # Suppress the openpyxl warning for WMF/EMF images being dropped:","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/msexcel_backend.py#L279-L315","documentation":"ImportError raised by MsExcelDocumentBackend.__init__ when the optional dependency openpyxl is not installed in the current environment. docling-slim deliberately ships backends without their format dependencies; the message tells you exactly which extra to install. The original import failure is chained via `from _OPENPYXL_IMPORT_ERROR` so the true cause is visible.","triggerScenarios":"Instantiating DocumentConverter and converting an .xlsx file while running docling-slim (or full docling with a broken env) where `import openpyxl` failed. Also triggered for legacy .xls files, which are first converted to .xlsx and then still require openpyxl.","commonSituations":"Using docling-slim to keep images light, minimal Docker images, CI environments installed from a requirements subset, or accidentally installing docling-slim instead of docling. Version conflicts that make openpyxl uninstallable also surface here.","solutions":["Install the extra: `pip install 'docling-slim[format-xlsx]'` (or just `pip install openpyxl`).","Or switch to the full package: `pip install docling`.","Verify with `python -c 'import openpyxl'` before running conversion jobs.","In Dockerfiles, add the extra to the install line so it is not stripped by later layer pruning."],"exampleFix":"# before\npip install docling-slim\npython -c 'from docling.document_converter import DocumentConverter; DocumentConverter().convert(\"book.xlsx\")'  # ImportError\n\n# after\npip install 'docling-slim[format-xlsx]'\npython -c 'from docling.document_converter import DocumentConverter; print(DocumentConverter().convert(\"book.xlsx\").document.export_to_markdown()[:100])'","handlingStrategy":"validation","validationCode":"def xlsx_support_available() -> bool:\n    try:\n        import openpyxl  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif not xlsx_support_available():\n    raise SystemExit(\"pip install 'docling-slim[format-xlsx]'\")","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(xlsx_path)\nexcept ImportError as e:\n    if 'openpyxl' in str(e):\n        raise SystemExit(\"Missing dependency: pip install 'docling-slim[format-xlsx]'\") from e\n    raise","preventionTips":["Install format extras in the same commit that adds the file type to your pipeline.","Add `python -c 'import openpyxl'` to container smoke tests.","Prefer full `docling` when disk space is not constrained."],"tags":["excel","dependency","import","docling-slim"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}