PaddlePaddle/PaddleOCR · error · RuntimeError

DOCX conversion requires python-docx: pip install paddleocr[

Error message

DOCX conversion requires python-docx: pip install paddleocr[doc2md]

What it means

RuntimeError raised inside _convert_body when the lazy 'from docx.table/text.paragraph import ...' fails. python-docx is an optional dependency of the doc2md extra; DOCX-to-Markdown conversion cannot proceed without it, and the message tells you the exact extra to install.

Source

Thrown at paddleocr/_doc2md/converters/docx.py:1294

    ilvl = int(ilvl_elem.get(f"{_W}val", "0")) if ilvl_elem is not None else 0
    if num_id not in numbering_map:
        return None
    fmt = numbering_map[num_id].get(ilvl, "bullet")
    list_type = (
        "ordered"
        if fmt in ("decimal", "lowerLetter", "upperLetter", "lowerRoman", "upperRoman")
        else "bullet"
    )
    return (list_type, ilvl, num_id)


def _convert_body(doc, *, extract_drawings=True) -> tuple:
    """Traverse body elements in order and produce Markdown. Returns (markdown_str, images_dict)."""
    try:
        from docx.table import Table
        from docx.text.paragraph import Paragraph
    except ImportError:
        raise RuntimeError(
            "DOCX conversion requires python-docx: pip install paddleocr[doc2md]"
        )

    body_font_size = _get_body_font_size(doc)
    content_width = _get_content_width(doc)
    numbering_map = _build_numbering_map(doc)
    lines: list[str] = []
    images: dict = {}
    image_counter = [0]  # wrapped in list so inner functions can mutate it
    code_buf: list[str] = []  # buffer for consecutive code paragraphs
    toc_buf: list[tuple] = []  # buffer for consecutive TOC paragraphs
    ol_counters: dict[str, int] = {}  # key = "{numId}-{ilvl}", value = current index
    prev_was_list = False

    def flush_code_buf():
        """Flush the code buffer as a fenced code block."""
        if code_buf:
            lines.append("```")

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. pip install 'paddleocr[doc2md]'
2. Or install the dependency directly: pip install python-docx
3. Verify with: python -c "import docx; print(docx.__version__)"

Example fix

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

try:
    import docx  # noqa: F401
    HAS_DOCX = True
except ImportError:
    HAS_DOCX = False

if not HAS_DOCX:
    raise RuntimeError("install paddleocr[doc2md] before converting .docx")

try:
    doc2md_convert('file.docx')
except RuntimeError as e:
    if 'python-docx' in str(e):
        subprocess.run([sys.executable, '-m', 'pip', 'install', 'paddleocr[doc2md]'])
    else:
        raise

When it happens

Trigger: Calling doc2md conversion on a .docx file (which routes to _convert_body via the DocxConverter) without python-docx installed.

Common situations: Installing plain 'paddleocr' without extras and later using doc2md; sparse production images that trimmed optional deps.

Related errors

• PPTX conversion requires python-pptx: pip install paddleocr[
• XLSX conversion requires openpyxl: pip install paddleocr[doc
• 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/d51be4679f19425f. Report an issue: GitHub.