PaddlePaddle/PaddleOCR · error · RuntimeError

XLSX conversion requires openpyxl: pip install paddleocr[doc

Error message

XLSX conversion requires openpyxl: pip install paddleocr[doc2md]

What it means

RuntimeError raised by XlsxConverter.convert_file when the lazy import of openpyxl (including its spreadsheet_drawing anchors) fails. XLSX-to-Markdown conversion requires openpyxl, provided by the doc2md extra.

Source

Thrown at paddleocr/_doc2md/converters/xlsx.py:170

    return (int(min_r), int(max_r), int(min_c), int(max_c))


@default_registry.register
class XlsxConverter(BaseConverter):
    supported_extensions = ["xlsx"]
    supported_mimetypes = [
        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    ]

    def convert_file(self, file_path: Path, **kwargs) -> ConvertResult:
        try:
            import openpyxl
            from openpyxl.drawing.spreadsheet_drawing import (
                OneCellAnchor,
                TwoCellAnchor,
            )
        except ImportError:
            raise RuntimeError(
                "XLSX conversion requires openpyxl: pip install paddleocr[doc2md]"
            )

        sheet_name: Optional[str] = kwargs.get("sheet_name", None)
        max_rows: Optional[int] = kwargs.get("max_rows", None)
        extract_drawings: bool = kwargs.get("extract_drawings", True)

        import zipfile

        # read_only=False is required to access merged_cells
        wb = openpyxl.load_workbook(str(file_path), read_only=False, data_only=True)
        sheets_md = []
        images: dict = {}
        image_counter = 0

        target_sheets = [sheet_name] if sheet_name else wb.sheetnames

        with zipfile.ZipFile(str(file_path), "r") as _zf:

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. pip install 'paddleocr[doc2md]'
2. Or: pip install openpyxl
3. If openpyxl is installed but too old to expose drawing anchors, upgrade it

Example fix

# before (shell)
pip install paddleocr
# after
pip install 'paddleocr[doc2md]'

import importlib.util

if importlib.util.find_spec('openpyxl') is None:
    raise RuntimeError('openpyxl missing: pip install paddleocr[doc2md]')

try:
    result = doc2md_convert(path)
except RuntimeError as e:
    if 'openpyxl' in str(e):
        fail_with_install_hint(e)
    raise

When it happens

Trigger: doc2md_convert('data.xlsx', sheet_name='Sheet1') without openpyxl installed; headless servers where openpyxl was never added.

Common situations: Spreadsheet ingestion pipelines deployed from minimal images; local dev worked because openpyxl came from another package (e.g. pandas exports) but CI lacks it.

Related errors

• DOCX conversion requires python-docx: pip install paddleocr[
• PPTX conversion requires python-pptx: pip install paddleocr[
• pylatexenc is required for math formula conversion. Install
• File not found: {file_path}
• Failed to convert {file_path.name}: {e}

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/5ade62ec14d5dcf5. Report an issue: GitHub.