Migrating from 0.x
Version 1.0.0 converts MathML directly into Word's OMML without an XSL file.
Upgrade the published package from PyPI:
python -m pip install --upgrade "mathml2docx[latex,markdown]"
Choose only the extras your application uses; HTML/MathML needs just mathml2docx.
from mathml2docx import convert, MathmlToDocx, TableStyle, ParagraphStyle
convert('<h1>Report</h1><p>Content</p>', 'report.docx',
table_style=TableStyle.GRID, paragraph_style=ParagraphStyle.NORMAL)
parser = MathmlToDocx()
parser.parse_mathml('<math><mfrac><mn>1</mn><mn>2</mn></mfrac></math>').save('fraction.docx')
# python -m pip install "mathml2docx[latex]"
parser.parse_latex(r'\frac{1}{2} + x^2').save('equation.docx')
Behavior changes
- The core library supports Python 3.6+. Development/documentation tools use uv and Python 3.10+.
parse_html_file(input, output)no longer duplicates.docx. Omitted output names replace the input extension. The method returns the saved path.- HTML always uses a BeautifulSoup tree.
fix_htmlremains for call compatibility; setting it toFalsedoes not disable tree parsing. get_origin()returns the same converter instance. Options have one source of truth and support bothparser.options.imagesandparser.options['images'].copy_settings_from()independently copies all options and style mappings.- Style helpers require explicit targets:
add_styles_to_run(css, run=run)andadd_styles_to_paragraph(css, paragraph=paragraph). - URL images are not downloaded automatically. Data URLs work by default; local
files must stay below
img_src_base_path. Supplyimage_loader(source)returning bytes or a file object for URLs or application-specific assets. - The Office XSL has been removed from the current package. Historical Git revisions and releases still require a separate licensing assessment.
- Unsupported MathML raises
UnsupportedMathMLError. This is not complete support for every MathML construct or every LaTeX package.
Supported mathematics
Tokens (mi, mn, mo, mtext, ms), grouping, fractions, scripts, square and
indexed roots, delimiters, limits, accents, rectangular matrices, and phantom are
supported. semantics converts its first expression and omits annotations.
Selected menclose notations and one pair each of pre/post scripts in mmultiscripts are supported. Content MathML needs preprocessing or fallback. Not every font,
spacing, accent, or other presentation attribute is reproduced.
LaTeX passes through latex2mathml and the same native converter. Independent answer checks exposed command, text, accent, and spacing errors in latex2mathml 2.16. The optional frontend therefore requires Python 3.6.2+ and latex2mathml 3.64+. HTML/MathML still supports Python 3.6.0/3.6.1; LaTeX requests on those versions report the required version. HTML dollar delimiters are not interpreted automatically.
Additional checks cover mathvariant, string quotes, barless binomial coefficients,
bevelled fractions, explicit fences, over/underlines, accents, and limit function
arguments. Dimensioned mpadded, forced equation line breaks, arbitrary negative
spacing, and custom fraction bar thickness raise errors. Some matrix alignment,
CSS, and operator properties are not applied. Supported mspace widths use Unicode
space approximations. See validation and limitations.
Styles and templates
Inline CSS supports colors, backgrounds, fonts, sizes, emphasis, underline, strike,
alignment, margins, indentation, and page breaks. RGBA is composited over the
inherited background; zero alpha is transparent. Static <style> selectors and
explicitly loaded external CSS are supported.
Install the markdown extra to use parse_markdown() with tables, fenced code,
and ~~text~~ strikethrough, or provide HTML from another Markdown parser.
Font size alone is not interpreted as heading semantics.
from docx import Document
from mathml2docx import MathmlToDocx
parser = MathmlToDocx(style_map={'p': {'quotation': 'Quote'}})
document = Document()
document.add_paragraph('{{content}}')
parser.add_html_to_document('<p class="quotation">A quotation</p>', document)
# Replace a unique marker, including one split across multiple runs.
parser.replace_html(document, '{{content}}', '<p>Inserted content</p>')
# Inline markers and existing bookmarks are also supported.
# parser.replace_bookmark(document, 'result', '<b>Result</b>')
document.save('output.docx')
The document's styles and numbering definitions are retained. New lists receive
new numbering definitions so they restart independently; nested lists use their
corresponding levels. DocxTemplate integration uses its underlying get_docx() document.
CLI
mathml2docx input.html output.docx
python -m mathml2docx input.tex equation.docx --format latex
Existing output is refused unless --force is supplied.
Math layout and recovery
MathML without display is now inline, matching the standard. To preserve old
block placement, use MathmlToDocx(default_math_display='block'). Explicit
display="block" and supported CSS display values are honored. Unsupported
formulas still raise by default; unsupported_math='text', mathml_fallback
and mathml_preprocessor provide explicit recovery. See equation handling.
Mathematical correctness and input recovery
MathML defaults now apply consistently from math and mstyle. Compact-style
movable limits use side scripts, including inside fractions and scripts; formulas
that depended on the former stacked layout may look different. Use explicit
display="block" or appropriate displaystyle where intended.
Structured accents, merged/ragged mathematical tables and RTL layouts use explicit
recovery when no faithful native representation is available. A forced break on
mo is handled the same way as on mspace. Malformed argument counts are detected
before recovery, including when an unsupported sibling appears first.
Encoded Unicode mathematical alphabets now carry matching native OMML variants, including double-struck and bold characters emitted by LaTeX backends. Word can otherwise decode those characters while losing their intended style.
Token whitespace and string escaping follow MathML rules. XML encoding declarations do not alter decoded Unicode input. CSS equation styling and XML-aware template boundaries preserve the selected text, math and surrounding content.
1.0.1 corrections
Encoded mathematical alphabets retain their variants under explicit or inherited
mathvariant; styled literal strings also retain text spacing. Unresolved LaTeX
command tokens now raise UnsupportedMathMLError instead of being saved as
identifiers. Expand custom macros before conversion. This backend validation
precedes MathML fallback; explicit \text{...} content remains literal text.