---
id: tomlrt
version: "2.2.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# tomlrt — A format-preserving TOML reader and writer for Python.

License: permissive · Maintenance: active · Downloads: 93.1K/mo

## What it is and what it does

tomlrt is a TOML parser and writer that treats formatting as data rather than noise. When you load a TOML file, edit it, and dump it back, every byte you didn't touch stays exactly as it was—comments, blank lines, indentation, quote style, and number formatting all round-trip intact. This makes it ideal for tools that need to modify configuration files programmatically while preserving human-written structure and intent.

The package supports TOML 1.1 and exposes both a file-based API (load/dump) and a programmatic one (Document class for building documents from scratch). It depends only on typing-extensions, keeping the install lightweight. The implementation is pure Python, distributed as a wheel, and requires Python 3.10 or later.

Use it for:

- Updating version strings or dependencies in pyproject.toml while keeping existing comments and formatting intact.
- Building configuration management tools that edit TOML files without destroying developer-written structure.
- Programmatically modifying application config files where preserving layout matters for readability or version control diffs.
- Creating TOML editors or linters that need to round-trip documents without lossy parsing.
- Generating new TOML documents from scratch using the Document API when format preservation isn't required.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Reads and writes TOML files while preserving formatting, comments, whitespace, and string styles exactly as they appear in the original document.

Yes. tomlrt solves a real problem—standard TOML parsers discard formatting, making them unsuitable for editing user-facing config files. The package is actively maintained, has no known vulnerabilities, carries a permissive MIT license, and installs with minimal friction. Use it whenever you need to read, modify, and write TOML while respecting the original document's structure.

## Install

pip install tomlrt
uv add tomlrt
poetry add tomlrt

## Installing tomlrt

Before you install: Low friction: pure Python wheel, single lightweight dependency (typing-extensions), active maintenance with a release 1 day old.

License in practice: MIT license permits unrestricted use, modification, and distribution in both open-source and commercial projects.

Quickstart:

import tomlrt

with open("pyproject.toml", "rb") as f:
    doc = tomlrt.load(f)

doc["project"]["version"] = "0.2.0"
print(tomlrt.dumps(doc))

Requires Python 3.10 or later.

Verify before relying:

- Whether round-trip fidelity holds for all TOML 1.1 edge cases (inline tables, nested structures, escape sequences).
- Performance characteristics on large configuration files (parsing speed, memory usage).
- Behavior when modifying deeply nested structures or adding new keys not in the original document.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 93.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

toml parser preserves formatting, round-trip toml reader writer, format-preserving config parser, toml editor with comments intact, pyproject.toml round-trip, toml with whitespace preservation, lossless toml manipulation, config-management, round-trip-parsing, format-preserving

[View on SkillFed](https://skillfed.io/packages/tomlrt) · [View on PyPI](https://pypi.org/project/tomlrt/)