math-core

A Python library for converting LaTeX math expressions to MathML Core.

Overview

math-core converts LaTeX mathematical expressions into MathML Core, a streamlined subset of MathML that is supported by all major web browsers. It lets you render mathematical content on the web without requiring JavaScript libraries or polyfills.

Features

Convert LaTeX math expressions to MathML Core
Support for both inline and display (block) math
Define custom LaTeX macros for extended functionality
Global and local counter for numbered equations
Pretty-printing option for readable MathML output
Comprehensive error handling with descriptive error messages

Installation

pip install math-core

Quick Start

from math_core import LatexToMathML

# Create a converter instance
converter = LatexToMathML()

# Convert inline math
mathml = converter.convert_with_local_state("x^2 + y^2 = z^2", displaystyle=False)
print(mathml)
# Output: <math><msup><mi>x</mi><mn>2</mn></msup><mo>+</mo><msup><mi>y</mi><mn>2</mn></msup><mo>=</mo><msup><mi>z</mi><mn>2</mn></msup></math>

# Convert display math
mathml = converter.convert_with_local_state(r"\frac{1}{2}", displaystyle=True)
print(mathml)
# Output: <math display="block"><mfrac><mn>1</mn><mn>2</mn></mfrac></math>

Usage

Basic Usage

from math_core import LatexToMathML, LatexError

# Initialize converter
converter = LatexToMathML(pretty_print="always")

# Convert LaTeX to MathML
try:
    mathml = converter.convert_with_local_state(r"\sqrt{x^2 + 1}", displaystyle=False)
    print(mathml)
except LatexError as e:
    print(f"Conversion error: {e}")

Custom LaTeX Macros

Define custom macros to extend or modify LaTeX command behavior:

# Define custom macros
macros = {
    "d": r"\mathrm{d}",      # Differential d
    "R": r"\mathbb{R}",      # Real numbers
    "vec": r"\mathbf{#1}"    # Vector notation
}

converter = LatexToMathML(macros=macros)
mathml = converter.convert_with_local_state(r"\d x", displaystyle=False)

Numbered Equations with Global State

For documents with multiple numbered equations:

converter = LatexToMathML()

# First equation gets (1)
eq1 = converter.convert_with_global_state(
    r"\begin{align}E = mc^2\end{align}",
    displaystyle=True
)

# Second equation gets (2)
eq2 = converter.convert_with_global_state(
    r"\begin{align}F = ma\end{align}",
    displaystyle=True
)

# Reset counter when starting a new chapter/section
converter.reset_global_state()

# This equation gets (1) again
eq3 = converter.convert_with_global_state(
    r"\begin{align}p = mv\end{align}",
    displaystyle=True
)

Local Counter for Independent Numbering

Use local counters when equation numbers should restart within each conversion:

converter = LatexToMathML()

# Each conversion has independent numbering
doc1 = converter.convert_with_local_state(
    r"\begin{align}a &= b\\c &= d\end{align}",
    displaystyle=True
)  # Contains (1) and (2)

doc2 = converter.convert_with_local_state(
    r"\begin{align}x &= y\\z &= w\end{align}",
    displaystyle=True
)  # Also contains (1) and (2)

Converting a Whole Document at Once

convert_all converts a collection of snippets in one go, which is the only way to get forward references right: a snippet may refer to an equation which is only defined in a later snippet.

converter = LatexToMathML()

reference, equation = converter.convert_all([
    (r"\eqref{eq:euler}", False),
    (r"\begin{align}e^{i\pi} + 1 = 0\label{eq:euler}\end{align}", True),
])
# `reference` refers to equation (1), even though it comes first.

Each entry is a (latex, displaystyle) pair. Equation numbering restarts with every call to convert_all; the state of convert_with_global_state is neither used nor modified.

If any snippet fails to convert, LatexError is raised, unless the converter was created with continue_on_error=True, in which case an HTML snippet describing the error takes the place of that snippet's MathML.

API Reference

LatexToMathML

The main converter class.

Constructor parameters:

pretty_print (str, optional): A string indicating whether to pretty print the MathML output. Options are “never”, “always”, or “auto”. “auto” means that all block equations will be pretty printed. Default: “never”.
macros (dict[str, str], optional): Dictionary of LaTeX macros for custom commands.
xml_namespace (bool, optional): A boolean indicating whether to include xmlns="http://www.w3.org/1998/Math/MathML" in the <math> tag. Default: False.
continue_on_error (bool, optional): A boolean indicating whether to raise an exception for conversion errors. If conversion fails and this is True, an HTML snippet describing the error will be returned, instead of raising LatexError. Default: False.
ignore_unknown_commands (bool, optional): A boolean indicating whether to ignore unknown LaTeX commands. If True, unknown commands be rendered as red text and the conversion will continue. Default: False.
annotation (bool, optional): A boolean indicating whether to include the original LaTeX as an annotation in the MathML output. Default: False.
global_group (bool, optional): A boolean indicating whether to run the conversion in the global group. If True, commands defined with \newcommand stay defined for subsequent calls to convert_with_global_state; if False, such definitions are local to the snippet which contains them. Default: False.
fancy_error (bool, optional): A boolean indicating whether to render errors as rich Ariadne diagnostic reports. If True (the default), the LatexError message contains a formatted diagnostic with source spans. Set to False to use compact plain-text messages instead.
unicode_substitution: A string indicating whether to substitute certain character combinations with a single Unicode symbol.
max_expansions (int, optional): The number of custom command expansions allowed in one snippet, after which the conversion gives up. The limit exists because a macro may expand to itself, directly or indirectly. Default: 1000.

Methods:

convert_with_global_state(latex: str, displaystyle: bool) -> str: Convert LaTeX to MathML using global state. May raise LatexError.
convert_with_local_state(latex: str, displaystyle: bool) -> str: Convert LaTeX to MathML using local state. May raise LatexError.
convert_all(snippets: list[tuple[str, bool]]) -> list[str]: Convert all snippets of a document at once, resolving forward references between them. Each snippet is a (latex, displaystyle) pair. Uses a fresh state for the batch, independent of the global state. May raise LatexError.
reset_global_state() -> None: Reset the global state (e.g., set the equation counter to zero).

LatexError

Exception raised when LaTeX parsing or conversion fails.

from math_core import LatexToMathML, LatexError

converter = LatexToMathML()
try:
    result = converter.convert_with_local_state(r"\invalid")
except LatexError as e
    print(f"Conversion failed: {e}")

Use Cases

Static Site Generators

Integrate math-core into your static site generator to convert LaTeX in Markdown files:

import re
from math_core import LatexToMathML

converter = LatexToMathML(pretty_print="auto")

def process_math(content):
    # Replace display math $$...$$; do this first to avoid conflicts with inline math delimiters
    content = re.sub(
        r"\$\$([^\$]+)\$\$",
        lambda m: converter.convert_with_local_state(m.group(1), displaystyle=True),
        content,
    )

    # Replace inline math $...$
    content = re.sub(
        r"\$([^\$]+)\$",
        lambda m: converter.convert_with_local_state(m.group(1), displaystyle=False),
        content,
    )

    return content

Web Applications

Generate MathML on the server side:

from flask import Flask, render_template_string
from math_core import LatexToMathML, LatexError

app = Flask(__name__)
converter = LatexToMathML()

@app.route("/equation/<latex>")
def render_equation(latex):
    try:
        mathml = converter.convert_with_local_state(latex, displaystyle=True)
        return render_template_string(
            "<html><body>{{ mathml|safe }}</body></html>", mathml=mathml
        )
    except LatexError:
        return "Invalid equation", 400

Why MathML Core?

MathML Core is a carefully selected subset of MathML 4 that focuses on essential mathematical notation while ensuring consistent rendering across browsers. Unlike full MathML or JavaScript-based solutions:

Native browser support: No JavaScript required
Accessibility: Better screen reader support
Performance: Faster rendering than JS solutions
SEO-friendly: Search engines can index mathematical content
Future-proof: Part of web standards with ongoing browser support

Browser Support

Firefox currently has the most complete support for MathML Core, with Chrome close behind. Safari has the least support and some rendering issues exist when using MathML Core, but it is improving with each release.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

math_core-0.8.0.tar.gz (204.0 kB view details)

Uploaded Aug 27, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

math_core-0.8.0-cp314-cp314t-win_arm64.whl (281.0 kB view details)

Uploaded Aug 27, 2026 CPython 3.14tWindows ARM64

math_core-0.8.0-cp314-cp314t-win_amd64.whl (293.9 kB view details)

Uploaded Aug 27, 2026 CPython 3.14tWindows x86-64

math_core-0.8.0-cp314-cp314t-musllinux_1_2_x86_64.whl (632.4 kB view details)

Uploaded Aug 27, 2026 CPython 3.14tmusllinux: musl 1.2+ x86-64

math_core-0.8.0-cp314-cp314t-musllinux_1_2_i686.whl (653.7 kB view details)

Uploaded Aug 27, 2026 CPython 3.14tmusllinux: musl 1.2+ i686

math_core-0.8.0-cp314-cp314t-musllinux_1_2_armv7l.whl (701.7 kB view details)

Uploaded Aug 27, 2026 CPython 3.14tmusllinux: musl 1.2+ ARMv7l

math_core-0.8.0-cp314-cp314t-musllinux_1_2_aarch64.whl (592.3 kB view details)

Uploaded Aug 27, 2026 CPython 3.14tmusllinux: musl 1.2+ ARM64

math_core-0.8.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (418.6 kB view details)

Uploaded Aug 27, 2026 CPython 3.14tmanylinux: glibc 2.17+ x86-64

math_core-0.8.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (413.4 kB view details)

Uploaded Aug 27, 2026 CPython 3.14tmanylinux: glibc 2.17+ ARM64

math_core-0.8.0-cp314-cp314t-macosx_11_0_arm64.whl (378.6 kB view details)

Uploaded Aug 27, 2026 CPython 3.14tmacOS 11.0+ ARM64

math_core-0.8.0-cp314-cp314t-macosx_10_12_x86_64.whl (397.4 kB view details)

Uploaded Aug 27, 2026 CPython 3.14tmacOS 10.12+ x86-64

math_core-0.8.0-cp310-abi3-win_arm64.whl (287.1 kB view details)

Uploaded Aug 27, 2026 CPython 3.10+Windows ARM64

math_core-0.8.0-cp310-abi3-win_amd64.whl (300.2 kB view details)

Uploaded Aug 27, 2026 CPython 3.10+Windows x86-64

math_core-0.8.0-cp310-abi3-musllinux_1_2_x86_64.whl (638.0 kB view details)

Uploaded Aug 27, 2026 CPython 3.10+musllinux: musl 1.2+ x86-64

math_core-0.8.0-cp310-abi3-musllinux_1_2_i686.whl (660.4 kB view details)

Uploaded Aug 27, 2026 CPython 3.10+musllinux: musl 1.2+ i686

math_core-0.8.0-cp310-abi3-musllinux_1_2_armv7l.whl (708.9 kB view details)

Uploaded Aug 27, 2026 CPython 3.10+musllinux: musl 1.2+ ARMv7l

math_core-0.8.0-cp310-abi3-musllinux_1_2_aarch64.whl (596.7 kB view details)

Uploaded Aug 27, 2026 CPython 3.10+musllinux: musl 1.2+ ARM64

math_core-0.8.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (424.0 kB view details)

Uploaded Aug 27, 2026 CPython 3.10+manylinux: glibc 2.17+ x86-64

math_core-0.8.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (419.2 kB view details)

Uploaded Aug 27, 2026 CPython 3.10+manylinux: glibc 2.17+ ARM64

math_core-0.8.0-cp310-abi3-macosx_11_0_arm64.whl (386.2 kB view details)

Uploaded Aug 27, 2026 CPython 3.10+macOS 11.0+ ARM64

math_core-0.8.0-cp310-abi3-macosx_10_12_x86_64.whl (401.1 kB view details)

Uploaded Aug 27, 2026 CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file math_core-0.8.0.tar.gz.

File metadata

Download URL: math_core-0.8.0.tar.gz
Upload date: Aug 27, 2026
Size: 204.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.12.6 {"installer":{"name":"uv","version":"0.12.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for math_core-0.8.0.tar.gz
Algorithm	Hash digest
SHA256	`3d144f4e2986bf27b5e171541b9d40fbdf7171ec8b09cb55115f3ff86bb27fe3`
MD5	`8f722143ce2c9ce5f217c444f8fe4126`
BLAKE2b-256	`bdd7a26aea824b587862771c839ff37afd9166ecb5326e377c4d2d381a4224e7`

Algorithm	Hash digest
SHA256	`fdbcb40bcf6de50c1a00adf4738686822de1149133d5094168ed8dae3e9ba180`
MD5	`7200138ba8e47601fc8dc1f2a0d88e68`
BLAKE2b-256	`38f0f8e780877ca2bffe50af0a2eda4fd5b9eb17c130a973361fb43fced6387b`

Algorithm	Hash digest
SHA256	`a73c10609580a71c53af3cd1168b13f80b0d278b1b6808648161c4335ca95b6b`
MD5	`d88eab114f0dee358269b0e8557b34d4`
BLAKE2b-256	`c4f63492b8ecf33901809b61dc9ab369cbc05d455555eb83ae38ad50743cd9c5`

Algorithm	Hash digest
SHA256	`749441b791ef3b5cf816b233a52b7b7708fcd5686162b2a68cc5400001030298`
MD5	`9ebe7370e79accc9a73ce54ff0d0a9de`
BLAKE2b-256	`0945437d589ba4bc7adf47ae6ec29fa6991d5ae1368e9f9b56c006fec2ca647a`

Algorithm	Hash digest
SHA256	`4dce7863bdcd2a5b99353f2bbed3cfa7823f4a85011790ba20edb85455840e03`
MD5	`d415a61785f220d265c7bd94692779ef`
BLAKE2b-256	`23adbfbd3b768895f22a35d0439119965be9de88134d0f5b13d2423c2dcbc005`

Algorithm	Hash digest
SHA256	`93adb7401c14049b7969068edd2e8a9f64b9f8a8a90010f2cd8d7a1267c61e18`
MD5	`dedf3ce4f652a662feba677a2ebac1f8`
BLAKE2b-256	`cf2c33c6c3236e5cdb0d62177e9310bbe7f65db90747d5f5d2ad76ff6680da3a`

Algorithm	Hash digest
SHA256	`c17db73f7ad4ab3f4525f1ed4401a36ecbe21273584043f8779f59e0e9714e6f`
MD5	`93ecd81d8fd1d80e548af3912647ed17`
BLAKE2b-256	`c200cb7c9ef6cbf9cd06c5d04d85d9285c2b505295eba124d19af5b6080e1aab`

Algorithm	Hash digest
SHA256	`e84ace2b902c3fd145c5472ff7d1fb3990fe4fae77457c5d30e63bcaf499d6f4`
MD5	`3c3d4001b5228f01751ddf87157a1241`
BLAKE2b-256	`e14bf08213d0a868d194a2fce5420b798072d0cb62c303420551175ef2819267`

Algorithm	Hash digest
SHA256	`cd3458aa2e3be49252b9df77863cd661c85ccf0a9baa2b44bf62c66334dc05b4`
MD5	`e2973b82beb145734630efcdfd4b860a`
BLAKE2b-256	`bbd5033ab2eb4b9e8ffceb135e938b3e923bcb8d7285f7a3f07cf186f167aeac`

Algorithm	Hash digest
SHA256	`6bc687244d2699d473fc043ed2bfece3f7db7d9e4fdae73cc2d254570fecad93`
MD5	`2625eb9cd4cd2c3eb7a757358a731476`
BLAKE2b-256	`d753e0a3d5541afe99a8d9a442f7186f7ab99215c5a6bf4f875fb695386c5ca3`

Algorithm	Hash digest
SHA256	`632ff8c854015cf11a9e778e575aed5a1b0a25754bc40d79162825318732359c`
MD5	`943841ec560fc82cd88a55b4f4fa1785`
BLAKE2b-256	`205aa9df2a78987b8a61260bd9a17b247e7a00cf0ce4b222f80f2a9b1d74787d`

Algorithm	Hash digest
SHA256	`4902d01eeec4fe57301a7f98e74e00fbab8346cb38859fb7962d1a61cf2e0bf4`
MD5	`d0aa289013038047f3f6e01cd42d3958`
BLAKE2b-256	`aacda6a1f5dd25752455090e4655bde67d2c7bd885c1eab4f60c815d7ffcd18a`

Algorithm	Hash digest
SHA256	`7c514a1fdbbacad54ed0464bd121ce1a87e51551f0f5e08471101653cf4b8dce`
MD5	`9c4d6ecd629dd725d4c281919903087d`
BLAKE2b-256	`6799a6ca1b78e3ccd4ef7e5376efc05c3ff45e450788682defa00e236ff62d82`

Algorithm	Hash digest
SHA256	`54f3b1ef3f4e9ccd7421ed4a9c829cc73b7387e33a2cb614e5876beedc2fe082`
MD5	`48fbd687e0a97085f35d7f95d1cc49b8`
BLAKE2b-256	`27936e74c448e8cf1dfc6d140c0b195d347ea0092b3c9bf0e2f963f88d1f2937`

Algorithm	Hash digest
SHA256	`a8f2d868fad3f83eeca0fab077e997de9f53d40edb8db3aa7d12e4ddd6a5b7b1`
MD5	`0e4d170d4e6d4a4b4656ba40c8efa9e5`
BLAKE2b-256	`5a4ec7a5c5801216436fbd2472cb9332552547533c3e65ea9a3952206b3c8cb4`

Algorithm	Hash digest
SHA256	`6e0113a3c79b2d3982c5e7c88d7da881b39c3e86333b614d7c77088db923add8`
MD5	`1514bd9fcfab945093ed632ffdb60517`
BLAKE2b-256	`60b3b7f5f0091127e15192738096e12d711ba5cbb71821f8a1f622114dcd103a`

Algorithm	Hash digest
SHA256	`fe905911c8743361e4875911618903decd976007b6dd0d3794dfb71ecf1e24e5`
MD5	`312577a216eecb3c96ba5e8ca4b9295a`
BLAKE2b-256	`61b36061892c8d099c8957a5ce336b7bc0c7929a171e6dcfca84fa20ad857ea7`

Algorithm	Hash digest
SHA256	`34001bc67f5a4585217d86c156163aa831d04b058f698d9510ee78ec54ec7742`
MD5	`7a3764ba8232227e01f89aae3de54981`
BLAKE2b-256	`46532a88810a85856cc03d33f1864188d5421f80a18ce92714a9290d7f1c1c87`

Algorithm	Hash digest
SHA256	`f243478ab51bddfb73f617cdde98132cee8f79ea5c2fc941dcf8e189706e7ad4`
MD5	`6f84fbdfd8385cec817d7ee880f40e34`
BLAKE2b-256	`e80b0a8f2e1eaff548cbd9696a0e92898653a282d0b5e1ab57320a7c6a54ab4d`

Algorithm	Hash digest
SHA256	`f34455ee4438dff47212eee919a790aa380f5ccbb0beeaedc07dba1b0d226aed`
MD5	`f93c8010c85d13a03239035fa457d682`
BLAKE2b-256	`c1a735a2e7de16e466c0f95b01b3853c052700177f7c1fb116408ae2ed2652c9`

Algorithm	Hash digest
SHA256	`4500fa614b266d305cf4776ec56d38a5b02f4558c3213c01d4563a390ad68d86`
MD5	`69289a64c0e26c9a6ddd51e110553de4`
BLAKE2b-256	`8322e3d5737247bc061d70d69ebe122a28bc2547a7d738a27d2a2e0b408eb6c9`

math-core 0.8.0

math-core

Overview

Features

Installation

Quick Start

Usage

Basic Usage

Custom LaTeX Macros

Numbered Equations with Global State

Local Counter for Independent Numbering

Converting a Whole Document at Once

API Reference

LatexToMathML

LatexError

Use Cases

Static Site Generators

Web Applications

Why MathML Core?

Browser Support

Contributing

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Provides Extra

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details