PaddlePaddle/PaddleOCR · error · RuntimeError

pylatexenc is required for math formula conversion. Install

Error message

pylatexenc is required for math formula conversion. Install it with: pip install pylatexenc

What it means

RuntimeError raised in oMath2Latex.__init__ when the delayed import of pylatexenc.latexencode.UnicodeToLatexEncoder fails. Converting OMML (Office Math Markup) formulas to LaTeX during document conversion needs the optional pylatexenc package, which is not installed by default.

Source

Thrown at paddleocr/_doc2md/math/omml.py:198

class oMath2Latex(Tag2Method):
    """
    Convert oMath element of omml to latex
    """

    _t_dict = T

    __direct_tags = ("box", "sSub", "sSup", "sSubSup", "num", "den", "deg", "e")

    _encoder = None  # cached UnicodeToLatexEncoder instance (class-level)

    def __init__(self, element):
        if oMath2Latex._encoder is None:
            # Delayed import: pylatexenc is an optional dependency
            try:
                from pylatexenc.latexencode import UnicodeToLatexEncoder
            except ImportError:
                raise RuntimeError(
                    "pylatexenc is required for math formula conversion. "
                    "Install it with: pip install pylatexenc"
                )
            oMath2Latex._encoder = UnicodeToLatexEncoder(
                replacement_latex_protection="braces-all",
                unknown_char_policy="keep",
                unknown_char_warning=False,
            )
        self.u = oMath2Latex._encoder
        self._latex = self.process_children(element)

    def __str__(self):
        return self.latex.replace("  ", " ")

    def process_unknow(self, elm, stag):
        if stag in self.__direct_tags:
            return self.process_children(elm)
        elif stag[-2:] == "Pr":

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. pip install pylatexenc
2. If you do not need math fidelity, preprocess the document to strip equations before conversion
3. Add pylatexenc to the deployment image alongside paddleocr[doc2md]

Example fix

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

import importlib.util

if importlib.util.find_spec('pylatexenc') is None:
    raise RuntimeError('pylatexenc required for OMML math: pip install pylatexenc')

try:
    result = doc2md_convert(docx_path)
except RuntimeError as e:
    if 'pylatexenc' in str(e):
        result = doc2md_convert(strip_equations(docx_path))  # degrade gracefully
    else:
        raise

When it happens

Trigger: doc2md conversion of a .docx containing Word equation objects (m:oMath elements) on an environment without pylatexenc; the class-level encoder cache is empty on first formula encountered.

Common situations: Academic/technical documents full of equations converted in a minimal deployment; the doc2md extra covering Office libs but not pylatexenc.

Related errors

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