Python tomllib vs tomlkit: Which TOML Parser?

When working with TOML configuration files in Python, developers often face a choice between python tomllib vs tomlkit. tomllib is the standard library module introduced in Python 3.11, while tomlkit is a third-party library that offers additional features like round-trip editing. The right choice depends on whether you need read-only parsing or the ability to modify and preserve TOML structure.

What tomllib and tomlkit Are

tomllib is a read-only parser that follows the TOML specification. It returns plain dictionaries, lists, and primitive types, making it suitable for loading configuration files. tomlkit, on the other hand, builds a document model that preserves comments, spacing, and ordering. This allows you to edit a TOML file and write it back without losing formatting.

API Differences: Reading TOML

Both libraries provide a loads function to parse a TOML string. The return types differ:

import tomllib
import tomlkit

toml_str = """
[server]
host = "localhost"
port = 8080
"""

# tomllib returns a plain dict
data = tomllib.loads(toml_str)
print(type(data))  # <class 'dict'>

# tomlkit returns a TOMLDocument (a dict subclass)
doc = tomlkit.parse(toml_str)
print(type(doc))   # <class 'tomlkit.toml_document.TOMLDocument'>

Both raise exceptions on invalid TOML. tomllib raises tomllib.TOMLDecodeError, while tomlkit raises tomlkit.exceptions.ParseError. The error messages are similar, but the exception types differ.

Round-Trip Editing with tomlkit

The main advantage of tomlkit is its ability to edit TOML while preserving the original formatting. For example, you can change a value and dump the document back to a string:

doc = tomlkit.parse(toml_str)
doc["server"]["port"] = 9090
new_toml = tomlkit.dumps(doc)
print(new_toml)

This outputs the TOML with the same comments and spacing as the original, only the port value changes. tomllib does not support this; it only parses to a dict, and you would have to manually serialize the dict back to TOML, which would lose comments and ordering.

Performance Considerations

Since tomllib is a simple parser that returns plain data structures, it generally has lower overhead than tomlkit, which constructs a more complex document tree. For applications that only read configuration once at startup, the difference is negligible. However, if you parse TOML repeatedly or process large files, tomllib's simpler model may be more memory-efficient. No official benchmarks are provided here, but the design suggests that tomllib is lighter for read-only use.

Compatibility and Dependencies

tomllib is part of the Python standard library from version 3.11 onward. For earlier Python versions, you can use the tomli backport, which provides the same API. tomlkit is a third-party package that supports Python 3.7 and later. If you need to support older Python versions, tomlkit is a viable option, but it adds a dependency to your project.

Choosing Between tomllib and tomlkit

The decision comes down to your requirements:

Use tomllib when you only need to read configuration and you are on Python 3.11+. Use tomlkit when you need to modify TOML files programmatically or when you must preserve comments and formatting.

Example: Modifying a TOML File with tomlkit

Consider a typical scenario where you need to update a version number in a pyproject.toml file. With tomlkit, you can do this cleanly:

from pathlib import Path
import tomlkit

path = Path("pyproject.toml")
doc = tomlkit.parse(path.read_text())
doc["project"]["version"] = "2.0.0"
path.write_text(tomlkit.dumps(doc))

The file keeps its original structure, comments, and ordering. With tomllib, you would have to parse the file, modify the dict, and then manually write a new TOML string, which is error-prone and loses formatting. This is where tomlkit's document model shines.