{"record":{"id":"81fd0a566aea9e66","repo":"PaddlePaddle/PaddleOCR","slug":"pylatexenc-is-required-for-math-formula-conversion","errorCode":null,"errorMessage":"pylatexenc is required for math formula conversion. Install it with: pip install pylatexenc","messagePattern":"pylatexenc is required for math formula conversion\\. Install it with: pip install pylatexenc","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"paddleocr/_doc2md/math/omml.py","lineNumber":198,"sourceCode":"\nclass oMath2Latex(Tag2Method):\n    \"\"\"\n    Convert oMath element of omml to latex\n    \"\"\"\n\n    _t_dict = T\n\n    __direct_tags = (\"box\", \"sSub\", \"sSup\", \"sSubSup\", \"num\", \"den\", \"deg\", \"e\")\n\n    _encoder = None  # cached UnicodeToLatexEncoder instance (class-level)\n\n    def __init__(self, element):\n        if oMath2Latex._encoder is None:\n            # Delayed import: pylatexenc is an optional dependency\n            try:\n                from pylatexenc.latexencode import UnicodeToLatexEncoder\n            except ImportError:\n                raise RuntimeError(\n                    \"pylatexenc is required for math formula conversion. \"\n                    \"Install it with: pip install pylatexenc\"\n                )\n            oMath2Latex._encoder = UnicodeToLatexEncoder(\n                replacement_latex_protection=\"braces-all\",\n                unknown_char_policy=\"keep\",\n                unknown_char_warning=False,\n            )\n        self.u = oMath2Latex._encoder\n        self._latex = self.process_children(element)\n\n    def __str__(self):\n        return self.latex.replace(\"  \", \" \")\n\n    def process_unknow(self, elm, stag):\n        if stag in self.__direct_tags:\n            return self.process_children(elm)\n        elif stag[-2:] == \"Pr\":","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/paddleocr/_doc2md/math/omml.py#L180-L216","documentation":"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.","triggerScenarios":"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.","commonSituations":"Academic/technical documents full of equations converted in a minimal deployment; the doc2md extra covering Office libs but not pylatexenc.","solutions":["pip install pylatexenc","If you do not need math fidelity, preprocess the document to strip equations before conversion","Add pylatexenc to the deployment image alongside paddleocr[doc2md]"],"exampleFix":"# before (shell)\npip install 'paddleocr[doc2md]'\n# after\npip install 'paddleocr[doc2md]' pylatexenc","handlingStrategy":"validation","validationCode":"import importlib.util\n\nif importlib.util.find_spec('pylatexenc') is None:\n    raise RuntimeError('pylatexenc required for OMML math: pip install pylatexenc')","typeGuard":null,"tryCatchPattern":"try:\n    result = doc2md_convert(docx_path)\nexcept RuntimeError as e:\n    if 'pylatexenc' in str(e):\n        result = doc2md_convert(strip_equations(docx_path))  # degrade gracefully\n    else:\n        raise","preventionTips":["Install pylatexenc whenever source documents may contain equations","Probe for it at startup if you accept technical .docx files"],"tags":["optional-dependency","doc2md","math","installation"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}