tomli

Tomli is a minimal Python library for parsing TOML documents into plain Python dictionaries. It began as the reference implementation that was eventually merged into the Python 3.11 standard library as tomllib, and it continues to ship on PyPI as a backport for the many projects still targeting older Python versions, plus anyone on 3.11+ who wants its faster mypyc-compiled wheels.

The library has no runtime dependencies, targets full compliance with the TOML specification (verified against the toml-lang/toml-test conformance suite), and deliberately does no more than parsing — there is no comment-preserving round-trip editor and no dumps/write function (that lives in the companion project Tomli-W). This narrow scope keeps the codebase small, auditable, and easy to reason about, which is exactly what a library sitting underneath pip, Poetry, and countless build backends needs to be.

What You Get

• loads() and load() functions that parse a TOML string or an open binary file object into a plain dict
• A dedicated TOMLDecodeError exception with informational messages for invalid documents
• Mypyc-compiled binary wheels on major platforms for near-native parsing speed, with a pure-Python fallback everywhere else
• A parse_float hook to swap in decimal.Decimal or another callable wherever the spec would otherwise produce a Python float
• Zero runtime dependencies and full type annotations (py.typed) for a clean drop into any project’s dependency tree

Common Use Cases

• Reading pyproject.toml inside build backends, linters, and other Python tooling
• Providing a tomllib polyfill so a single codebase supports Python 3.6+ while still using the standard library module on 3.11+
• Loading TOML-based application or CLI configuration files at startup
• Parsing TOML data files in scripts and pipelines where JSON/YAML aren’t the source format
• Validating TOML documents against the spec during CI or pre-commit checks

Under The Hood

Architecture

Tomli is a small, flat package (src/tomli/) built around a single hand-written recursive-descent parser in _parser.py (roughly 800 lines) that walks the input string character by character rather than relying on a parser-generator or tokenizer/AST split. _re.py holds the small set of regular expressions used for datetime, local-time, and number literals, lazily imported (__lazy_modules__) so that importing tomli stays cheap when those code paths aren’t hit. _types.py defines the handful of internal type aliases (Key, ParseFloat, Pos) used for static typing, and __init__.py re-exports just three names — loads, load, TOMLDecodeError — as the entire public surface. Inline tables and arrays are parsed via recursion, with an explicit nesting cap tied to sys.getrecursionlimit() to avoid crashing the mypyc-compiled binary wheels on pathologically nested documents, a deliberate defensive measure called out directly in the source comments.

Tech Stack

The library targets Python 3.8+ with from __future__ import annotations for forward-compatible type hints, and has zero runtime dependencies. It’s built with flit_core as the PEP 517 build backend and versioned via bump2version. The standout tooling choice is mypyc, which compiles the same Python source into binary wheels for CPython on the major platforms, giving Tomli C-extension-like parsing speed while keeping a single pure-Python source tree; PyPy and platforms without prebuilt wheels transparently fall back to the interpreted path. Tooling around the core includes tox for running the test matrix across Python 3.8 through 3.14 (plus PyPy), pre-commit for linting, and a fuzzer/ directory wired up for coverage-guided fuzz testing.

Code Quality

Tests live under tests/ and run via the standard-library unittest module, with tests/burntsushi.py wiring in the external toml-lang/toml-test conformance suite against tests/data/valid and tests/data/invalid fixtures — this is how the project verifies full TOML spec compliance rather than relying only on hand-written cases. mypy --strict (with strict_bytes and warn_unreachable enabled) is configured across the source tree, and .flake8 plus a .pre-commit-config.yaml enforce style. CI runs the test matrix across Python 3.8–3.14, PyPy, and Linux/macOS/Windows, and a separate linters job blocks the release workflow from firing if pre-commit fails. The project reports 100% branch coverage via coverage.py configuration in pyproject.toml.

What Makes It Unique

Tomli’s defining trait is being small on purpose: it was written specifically to become the model for Python’s own tomllib, so its scope stops exactly at parsing — no serialization, no comment-preserving edits, no configuration framework wrapped around it. Its combination of a pure-Python implementation with mypyc-compiled binary wheels is a comparatively rare pattern that gives it near-native performance without forcing a C toolchain on downstream users, and its benchmark suite in benchmark/ documents that speed advantage directly against toml, tomlkit, and other pure-Python competitors.