latexcodec

library3.0.1pypypi✓ verified 23d ago

latexcodec is a Python library providing a lexer and codec for converting text between LaTeX markup and Unicode. It is particularly suited for handling short segments of LaTeX code, such as paragraphs or entries in a BibTeX file, rather than compiling full LaTeX documents. The current stable version is 3.0.1, and it maintains an active but measured release cadence.

serialization

pip install latexcodec

github ↗package ↗

INSTALL

IMPORT

SIG · LATEXCODEC

latexcodec

serializationpythonv3.0.1

Install

1.5s avg

Import

98ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.106s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.090s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

latexcodec

✓ import latexcodec import codecs # Use codecs.decode() and codecs.encode()

✗ from latexcodec import decode_latex_str

Importing `latexcodec` automatically registers the 'latex' and 'ulatex' codecs with Python's standard `codecs` module. Direct functions are not typically exposed for end-user encoding/decoding.

This quickstart demonstrates how to decode LaTeX strings to Unicode and encode Unicode strings to LaTeX using the `latex` and `ulatex` codecs registered by importing `latexcodec`. It also shows how to specify additional encodings and handle unrepresentable characters during encoding.

import codecs import latexcodec # This registers the 'latex' and 'ulatex' codecs # Decode LaTeX to Unicode latex_text = r"I like b\"all{\oe}ns and M\"uller." unicode_output = codecs.decode(latex_text, "ulatex") print(f"Decoded LaTeX: {unicode_output}") # Encode Unicode to LaTeX unicode_input = "élève" latex_output = codecs.encode(unicode_input, "ulatex") print(f"Encoded Unicode: {latex_output}") # Example with specific encoding (e.g., Latin-1) latin1_latex_bytes = b"\xfe" # Represents 'þ' in Latin-1 decoded_latin1 = latin1_latex_bytes.decode("latex+latin1") print(f"Decoded Latin1 LaTeX: {decoded_latin1}") # Example with error handling during encoding for unrepresentable characters unicode_with_unrepresentable = "A keyboard: ⌨" # Using 'keep' error handler with 'ulatex' codec encoded_kept = codecs.encode(unicode_with_unrepresentable, "ulatex", "keep") print(f"Encoded with 'keep' error (ulatex): {encoded_kept}") # Using 'ulatex+utf8' for robust encoding of all Unicode characters encoded_utf8 = codecs.encode(unicode_with_unrepresentable, "ulatex+utf8") print(f"Encoded with ulatex+utf8: {encoded_utf8}")

Debug

Known issues

breakingVersions prior to 3.0.1 are incompatible with Python 3.13+ due to the removal of `pkg_resources.open_text`. Users on Python 3.13 and newer must upgrade to `latexcodec` 3.0.1 or later.

fix

Upgrade to `latexcodec>=3.0.1`.

affects: <3.0.1

deprecatedThe maintainer strongly encourages users to consider `pylatexenc` as a superior alternative to `latexcodec` for LaTeX code processing.

fix

Evaluate migrating to `pylatexenc` for new projects or existing ones that require more robust LaTeX handling. (https://github.com/phfaist/pylatexenc)

affects: All versions

gotchaThis library is primarily designed for processing short fragments of LaTeX text (e.g., paragraphs, BibTeX entries) and is not intended to function as a full LaTeX compiler or for comprehensive document processing.

fix

Ensure use cases align with the library's scope. For full document parsing or compilation, consider dedicated LaTeX parsers or compilers.

affects: All versions

gotchaWhen decoding LaTeX, commands that do not directly represent characters (e.g., macros, formatting commands like `\textbf`) or are unrecognized by the codec are passed through unchanged. This can result in a 'hybrid' Unicode string containing unexpanded LaTeX commands.

fix

Be aware of this behavior and implement post-processing if fully flattened Unicode is required. Unrecognized commands may require custom translation tables.

affects: All versions

gotchaEncoding Unicode characters to LaTeX can fail if the characters cannot be represented by the default (ASCII) LaTeX encoding. For more robust encoding, use the `ulatex+utf8` codec or specify the `'keep'` error handler with `ulatex` to retain unencodable characters.

fix

Use `codecs.encode(unicode_str, 'ulatex+utf8')` or `codecs.encode(unicode_str, 'ulatex', 'keep')`.

affects: All versions

gotchaThe decoding process canonicalizes certain LaTeX elements: comments are dropped, paragraphs are converted to double newlines, and spacing after LaTeX commands is standardized. This can lead to subtle differences in the decoded text's structure compared to the original LaTeX source.

fix

Account for these canonicalizations when comparing decoded output to original source or when expecting specific formatting.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'latexcodec'

The `latexcodec` package is not installed in the Python environment, or the environment where the script is run does not have access to the installed package.

fix

Install the package using pip: `pip install latexcodec`

UnicodeEncodeError: 'latex' codec can't encode character '\u2009' in position 0: don't know how to translate '\u2009' into latex

This error occurs when attempting to encode a Unicode character for which the default `latex` codec does not have a registered LaTeX equivalent. The specific character `\u2009` (thin space) is an example of a Unicode character that `latexcodec` may not know how to translate by default.

fix

Use the `ulatex+utf8` codec for more robust encoding, or specify the `'keep'` error handler to retain unencodable characters. Example: `codecs.encode(unicode_str, 'ulatex+utf8')` or `codecs.encode(unicode_str, 'ulatex', 'keep')`.

AttributeError: module 'pkg_resources' has no attribute 'open_text'

This error typically occurs when using `latexcodec` versions prior to 3.0.1 with Python 3.13 or newer, because the `pkg_resources.open_text` method was removed in Python 3.13.

fix

Upgrade `latexcodec` to version 3.0.1 or later: `pip install --upgrade latexcodec`

LaTeX command \textbf{} appearing in decoded output

The `latexcodec` library is designed for short fragments of LaTeX text and by design, when decoding, commands that do not directly represent characters (like macros or formatting commands such as `\textbf`) or are unrecognized are passed through unchanged. This results in a 'hybrid' Unicode string containing unexpanded LaTeX commands.

fix

Be aware of this intended behavior. If fully flattened Unicode is required, implement post-processing to handle or remove these unexpanded LaTeX commands, or consider using a full LaTeX parser like `pylatexenc` for more comprehensive LaTeX handling.

Upgrade

Version history

3.0.1latest on PyPI · released Jun 17, 2025

Audit

Dependencies

pythonrequiredRequired Python version

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/mcmtroffaes/latexcodec ↗

packagehttps://pypi.org/project/latexcodec/ ↗