Getting started

Installation

The core library supports Python 3.6+; optional LaTeX requires 3.6.2+. Choose one of the following methods to install the published PyPI package. HTML and MathML work with the core package; extras add LaTeX and Markdown input. Git and a repository checkout are not required.

pip

Install in your project's Python environment. If needed, create one with python -m venv .venv and activate it using the command for your operating system.

python -m pip install mathml2docx

For optional inputs, choose the extras you need:

python -m pip install "mathml2docx[latex]"
python -m pip install "mathml2docx[markdown]"
# Both optional frontends:
python -m pip install "mathml2docx[latex,markdown]"

Check the installed version with:

python -m pip show mathml2docx

Update with python -m pip install --upgrade mathml2docx, or python -m pip install --upgrade "mathml2docx[latex,markdown]" if using both extras. Run your saved Python script with python report.py.

uv

Install uv separately. For a new project, run uv init --bare report-project, then cd report-project. In an existing uv project, use its directory directly.

uv add mathml2docx
# Or include both optional inputs:
uv add "mathml2docx[latex,markdown]"
uv run python -c "import mathml2docx; print(mathml2docx.__version__)"

For a single extra, use uv add "mathml2docx[latex]" or uv add "mathml2docx[markdown]". uv manages the environment and records dependencies in pyproject.toml and uv.lock. Run your saved script with uv run python report.py.

Update within your declared version constraints:

uv lock --upgrade-package mathml2docx
uv sync

Poetry

Install Poetry separately; the current Poetry tool requires Python 3.10+. In a new project directory, run poetry init and set the Python range to match the interpreters you support. In an existing Poetry project, use its directory directly.

poetry add mathml2docx
# Or include both optional inputs:
poetry add "mathml2docx[latex,markdown]"
poetry run python -c "import mathml2docx; print(mathml2docx.__version__)"

For a single extra, use poetry add "mathml2docx[latex]" or poetry add "mathml2docx[markdown]". Poetry records dependencies in pyproject.toml and poetry.lock. Run your saved script with poetry run python report.py. Update within your declared version constraints with poetry update mathml2docx.

Version compatibility

Package managers have their own Python requirements; the library's Python 3.6 support does not require installing a modern tool on Python 3.6. Keep your project's requirements or lockfile for repeatable installs. See migration when upgrading from 0.x. Source and contributor setup is in development and releases.

Python 3.6

Use a pip version that supports Python 3.6 and its compatible dependency wheels:

python -m pip install --upgrade "pip>=21.3,<22"
python -m pip install mathml2docx

pip selects dependency versions compatible with the interpreter. The optional LaTeX frontend still requires Python 3.6.2+.

Convert HTML and equations

from mathml2docx import convert

html = '''<h1>Equation example</h1>
<p>The following is a fraction.</p>
<math xmlns="http://www.w3.org/1998/Math/MathML">
  <mfrac><mn>1</mn><mn>2</mn></mfrac>
</math>'''
convert(html, 'example.docx')

convert() returns a python-docx Document. Omit the output path to return the document without saving it. Neither XSL nor Microsoft Office is required.

To convert an existing HTML file named input.html:

from mathml2docx import MathmlToDocx

parser = MathmlToDocx()
parser.parse_html_file('input.html', 'output.docx')

After installing the latex extra:

from mathml2docx import MathmlToDocx

MathmlToDocx().parse_latex(r'\frac{1}{2}').save('latex.docx')

Add to an existing document

from docx import Document
from mathml2docx import MathmlToDocx

document = Document()
document.add_paragraph('Existing content')
MathmlToDocx().add_html_to_document('<p>Additional content</p>', document)
document.save('combined.docx')

Use add_html_to_cell(html, cell) for a table cell. If upgrading from 0.x, read the migration guide.