Read, Modify, and Write TOML with Python tomlkit
Learn how to read, modify, and write TOML files in Python with the tomlkit library while preserving comments, key order, and formatting.

Reading, modifying, and writing TOML files in Python with tomlkit is a common task for configuration tooling, and the library is designed specifically to preserve the original formatting of the file. The standard library's tomllib module can parse TOML, but it returns plain dictionaries and cannot serialize them back to TOML. tomlkit parses TOML into a document object that behaves like a dictionary while retaining comments, key order, and whitespace, so editing a pyproject.toml or a config.toml does not destroy the formatting that other tools or humans rely on.
Why tomlkit Exists
Python 3.11 added tomllib to the standard library, but it only covers the read side. Parsing a file with tomllib produces a plain dict, and there is no built-in way to write that dict back as TOML. If you want to modify a value and save the file, you have to serialize with a third-party library, and the result is a valid but completely reformatted file: comments are gone, key order follows insertion order, and any deliberate formatting choices are lost.
tomlkit solves this by keeping the original document structure in memory. It stores each key, value, comment, and piece of whitespace as part of the parsed tree. When you change one value, the rest of the document keeps its original layout. This is why tooling like Poetry uses tomlkit to edit pyproject.toml files: a small version bump should not reformat the entire file.
Reading a TOML Document
tomlkit provides two entry points for reading:
tomlkit.parse(text)parses a string.tomlkit.load(file_obj)reads from an open file object.
import tomlkit
with open("pyproject.toml", "r", encoding="utf-8") as f:
doc = tomlkit.load(f)
print(doc["tool"]["poetry"]["name"])The returned object is a TOMLDocument, which behaves like a mapping. You access values with the same subscript syntax you would use on a dictionary, including nested tables. Unlike a plain dictionary, the document remembers where each key appeared, what whitespace surrounded it, and which comments belong to it.
If you already have the file contents as a string, parse is the direct equivalent:
doc = tomlkit.parse(text)Both return the same TOMLDocument type, so everything that follows applies to either approach.
Modifying Existing Values
Modifying a value is a plain assignment:
doc["tool"]["poetry"]["version"] = "2.1.0"When you assign a Python value, tomlkit converts it to the appropriate internal TOML type and replaces the existing item in place. The comment attached to that key stays where it was. If the original file contained:
# Current release version
version = "2.0.0"then after the assignment the comment remains above the version key, and only the value changes.
The same applies to booleans, integers, floats, arrays, and dates:
doc["tool"]["poetry"]["dependencies"]["requests"] = "^2.32.0"
doc["tool"]["poetry"]["authors"] = ["Alice <alice@example.com>"]If the key already exists, its trivia is preserved. If it does not exist, the new key is appended at the end of the current table.
Adding New Keys, Tables, and Arrays
Adding a new scalar key uses the same assignment syntax:
doc["tool"]["poetry"]["description"] = "A command-line tool for syncing files"For a new empty table, use tomlkit.table():
from tomlkit import table
doc["tool"]["newtool"] = table()
doc["tool"]["newtool"]["enabled"] = TrueFor an array that you build incrementally, use tomlkit.array():
from tomlkit import array
items = array()
items.append("one")
items.append("two")
doc["tool"]["newtool"]["items"] = itemsFor an inline table, use tomlkit.inline_table():
from tomlkit import inline_table
cfg = inline_table()
cfg["retries"] = 3
cfg["timeout"] = 30
doc["tool"]["newtool"]["config"] = cfgOne important limitation: assignment to a nested path requires every intermediate table to already exist. The following raises a KeyError if tool or newtool is missing:
doc["tool"]["newtool"]["enabled"] = TrueCreate the intermediate tables first, or check for their presence before assigning.
Writing the Modified Document Back
Two functions write a document:
tomlkit.dump(doc, file_obj)writes to an open file object.tomlkit.dumps(doc)returns the TOML as a string.
with open("pyproject.toml", "w", encoding="utf-8") as f:
tomlkit.dump(doc, f)If you need the string for another purpose, such as sending it over HTTP or embedding it in a larger file, use dumps:
updated = tomlkit.dumps(doc)The serialized output preserves the original comments, key order, and whitespace, with only the modified or added sections reflecting the changes.
How Formatting and Comments Are Preserved
The reason tomlkit can round-trip a file without reformatting it is that every item in the document carries its own trivia. Trivia includes the leading whitespace and blank lines before a key, the trailing whitespace after a value, and any comments attached to the key, whether they appear on the same line or on lines above it.
When you replace a value, the new value inherits the trivia of the old one. When you add a new key, you can attach a comment explicitly:
doc["tool"]["newtool"]["enabled"] = True
doc["tool"]["newtool"]["enabled"].comment("Enable the new tool")The .comment() method attaches a comment that will be written on the line above the key during serialization.
This behavior is what makes tomlkit suitable for editing files that are shared with other tools. A pyproject.toml often contains comments explaining why a dependency is pinned or why a setting exists. Those comments survive a tomlkit edit, which is not the case when you parse with tomllib and serialize with a generic TOML writer.
Choosing Between tomlkit and tomllib
| Capability | tomlkit | tomllib |
|---|---|---|
| Read TOML | Yes | Yes |
| Write TOML | Yes | No |
| Preserve comments | Yes | No |
| Preserve key order | Yes | No |
| Availability | pip install tomlkit | Python 3.11+ |
Use tomllib when you only need to read configuration and never write it back, and when comments and ordering do not matter. It is part of the standard library and returns plain dictionaries, which keeps the code simple when you only need the values.
Use tomlkit when you need to modify and write TOML, or when preserving the original formatting matters. For typical configuration files, keeping the richer in-memory representation is a reasonable trade-off because it lets you edit files without losing comments and layout.
tomlkit is a pure-Python package installed with pip. It implements the TOML 1.0 specification, so it handles the same syntax that tomllib accepts. Because it keeps a richer in-memory representation, it is the practical choice whenever a script must edit a TOML file in place rather than regenerate it from scratch.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.