docling-project/docling · error · ImportError

The 'openpyxl' package is required to process Excel files. I

Error message

The 'openpyxl' package is required to process Excel files. Install it with `pip install 'docling-slim[format-xlsx]'`.

What it means

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.

Source

Thrown at docling/backend/msexcel_backend.py:297

    @override
    def __init__(
        self,
        in_doc: InputDocument,
        path_or_stream: BytesIO | Path,
        options: MsExcelBackendOptions | None = None,
    ) -> None:
        """Initialize the MsExcelDocumentBackend object.

        Parameters:
            in_doc: The input document object.
            path_or_stream: The path or stream to the Excel file.
            options: Backend options for Excel parsing.

        Raises:
            RuntimeError: An error occurred parsing the file.
        """
        if not _OPENPYXL_AVAILABLE:
            raise ImportError(_INSTALL_HINT) from _OPENPYXL_IMPORT_ERROR
        if in_doc.format == InputFormat.XLS:
            path_or_stream = convert_to_modern_format(path_or_stream, "xls", "xlsx")
        if options is None:
            options = MsExcelBackendOptions()
        super().__init__(in_doc, path_or_stream, options)

        self.page_range = in_doc.limits.page_range

        # Current sheet group; set at the start of each sheet conversion
        self.parent: GroupItem | None = None

        # Lazy-initialized LibreOffice converter for EMF/WMF images
        self.xlsx_to_pdf_converter: Callable | None = None
        self.xlsx_to_pdf_converter_init: bool = False

        self.workbook = None
        try:
            # Suppress the openpyxl warning for WMF/EMF images being dropped:

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Install the extra: `pip install 'docling-slim[format-xlsx]'` (or just `pip install openpyxl`).
2. Or switch to the full package: `pip install docling`.
3. Verify with `python -c 'import openpyxl'` before running conversion jobs.
4. In Dockerfiles, add the extra to the install line so it is not stripped by later layer pruning.

Example fix

# before
pip install docling-slim
python -c 'from docling.document_converter import DocumentConverter; DocumentConverter().convert("book.xlsx")'  # ImportError

# after
pip install 'docling-slim[format-xlsx]'
python -c 'from docling.document_converter import DocumentConverter; print(DocumentConverter().convert("book.xlsx").document.export_to_markdown()[:100])'

def xlsx_support_available() -> bool:
    try:
        import openpyxl  # noqa: F401
        return True
    except ImportError:
        return False

if not xlsx_support_available():
    raise SystemExit("pip install 'docling-slim[format-xlsx]'")

try:
    result = converter.convert(xlsx_path)
except ImportError as e:
    if 'openpyxl' in str(e):
        raise SystemExit("Missing dependency: pip install 'docling-slim[format-xlsx]'") from e
    raise

When it happens

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

Common situations: 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.

Related errors

• The 'python-pptx' package is required to process PowerPoint
• Libreoffice not found
• LibreOffice is required to convert a .{source_suffix} file t
• MsExcelDocumentBackend could not load document with hash {se
• Cannot convert doc with {self.document_hash} because the bac

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