pylatexenc

pylatexenc is a pure-Python library for working with LaTeX markup outside of a full TeX engine. It provides a real parser (latexwalker) that turns LaTeX source into a structured tree of nodes — macros, environments, groups, math, and characters — rather than treating LaTeX as plain text to be regex-matched. On top of that parser, latex2text converts parsed LaTeX into readable Unicode plain text, while latexencode goes the other direction, turning Unicode strings (accented letters, math symbols) into escaped LaTeX source.

The library ships as three independently usable modules plus a lower-level latexnodes/macrospec layer that defines how macros and environments are recognized and their arguments parsed. Each of the three user-facing modules also installs a console script (latexwalker, latex2text, latexencode) for quick command-line conversions, though the primary use case is programmatic: extracting or generating LaTeX in documentation tooling, citation managers, academic-text pipelines, and any system that needs to move between LaTeX source and human-readable text without shelling out to a TeX distribution.

It has no runtime dependencies, supports Python 3.6+, and is under active development toward a 3.0 release that reworks the parsing internals while keeping the same three-module surface.

What You Get

• A LaTeX parser (latexwalker) that builds a tree of macro, environment, group, math, and character nodes from raw LaTeX source
• A LaTeX-to-Unicode converter (latex2text) that renders parsed LaTeX as readable plain text, handling accents, math symbols, and common macros
• A Unicode-to-LaTeX encoder (latexencode) that escapes accented characters and math symbols into valid LaTeX source
• A customizable macro/environment specification system (macrospec) for teaching the parser about new commands and how their arguments should be read
• Three console-script entry points (latexwalker, latex2text, latexencode) for one-off command-line conversions
• Zero runtime dependencies and support back to Python 3.6

Common Use Cases

• Stripping LaTeX markup out of academic abstracts, citations, or BibTeX fields to get clean display text
• Building documentation or static-site tooling that needs to render LaTeX-authored content as plain text or HTML without invoking a TeX engine
• Converting user-typed Unicode (accented names, math symbols) into escaped LaTeX for inclusion in a .tex document
• Writing custom LaTeX-aware tooling (linters, converters, extractors) on top of the latexwalker/macrospec node tree instead of hand-rolling regexes

Under The Hood

Architecture pylatexenc is organized as three user-facing modules layered over a shared low-level core. latexnodes defines the node types (chars, macros, groups, math, comments) and the token-reader/parsing-state machinery; macrospec builds on it to define how specific macros and environments declare and consume their arguments via a LatexContextDb. latexwalker (pylatexenc/latexwalker/_walker.py) is the actual recursive-descent parser: its LatexWalker class walks an input string using a configurable ParsingState and default macro/environment database (_defaultspecs.py), producing a tree of node objects rather than a flat token stream. latex2text and latexencode then consume or produce that representation, each as an independent module with its own default specs and CLI (__main__.py) — so the three conversions can be used or extended separately without pulling in the others.

Tech Stack The library is pure Python with zero runtime dependencies, targeting Python 3.6+ for the published package. Packaging uses hatchling with the version single-sourced from pylatexenc/version.py (pyproject.toml’s [tool.hatch.version]). Development tooling is managed with uv and PEP 735 dependency groups: a dev group (pytest) for the test suite, a builddoc group (Sphinx, sphinx-issues) for the Read the Docs build, and a buildjslib group (Transcrypt, PyYAML) that transpiles select modules to JavaScript for a companion project. CI runs on GitHub Actions with a dedicated CodeQL security-analysis workflow alongside the test workflow, and releases are published to PyPI via a manual deploy-pypi workflow.

Code Quality The test/ directory contains around 30 test modules covering each layer independently — latexwalker, latex2text, latexencode, and the lower-level latexnodes/macrospec parsers (arguments, delimited/verbatim/math parsing, token readers) each have dedicated test files, run via pytest per pyproject.toml’s [tool.pytest.ini_options]. Core modules carry extensive Sphinx-style docstrings documenting arguments, return types, and version-added notes, and internal modules are explicitly marked as unstable/internal-only where their API may change. No static type checker or type stubs are configured, but the CodeQL workflow adds automated security/quality scanning on every push and pull request.

API Design The public surface is deliberately narrow and function-oriented: latex2text.LatexNodes2Text().latex_to_text(s) and latexencode.unicode_to_latex(s) cover the two most common conversions in one call each, while power users can drop down to LatexWalker and a custom LatexContextDb to handle non-default macros. Backwards compatibility is treated as a first-class concern — the README and docstrings repeatedly flag versionadded/versionchanged points across the 2.x to 3.0 transition, and the three console scripts mirror the three main modules one-to-one, keeping the CLI and library APIs conceptually aligned.