tomlkit

library0.15.1pypypi✓ verified 27d ago

TOML Kit is a style-preserving TOML library for Python, currently at version 0.14.0. It offers a parser that maintains comments, indentations, whitespace, and internal element ordering, providing an intuitive API for accessing and editing TOML files. The library is actively maintained with regular updates, as seen in its recent releases.

serialization

pip install tomlkit

github ↗package ↗

INSTALL

IMPORT

SIG · TOMLKIT

tomlkit

serializationpythonv0.15.1

Install

1.7s avg

Import

59ms

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 v0.15.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.060s · 18.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.058s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

parse

✓ from tomlkit import parse

Correct import path for the 'parse' function.

dumps

✓ from tomlkit import dumps

Correct import path for the 'dumps' function.

table

✓ from tomlkit import table

Correct import path for the 'table' function.

A quickstart guide demonstrating parsing, modifying, and writing TOML documents using TOML Kit.

from tomlkit import parse, dumps, table content = """[table] foo = "bar" # String """ doc = parse(content) doc['table']['baz'] = 13 tab = table() tab.add('array', [1, 2, 3]) doc['table2'] = tab dumps(doc)

Debug

Known issues

breakingIn version 0.13.0, test failures with Python 3.13.0a4 were fixed, which may affect compatibility with earlier versions of Python 3.13.

fix

Upgrade to TOML Kit version 0.13.0 or later.

affects: 0.13.0

deprecatedThe 'loads' function is deprecated in favor of 'parse' for parsing TOML strings.

fix

Use 'parse' instead of 'loads' for parsing TOML strings.

affects: 0.13.0

gotchaWhen modifying TOML documents, ensure that changes are made through the provided API to preserve formatting and comments.

fix

Use TOML Kit's API methods for modifications to maintain style preservation.

affects: All

gotchaThe test output indicates warnings from pip regarding running as the 'root' user and an available pip update.

fix

It is recommended to use a virtual environment for pip operations and consider upgrading pip as suggested in the notice.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'tomlkit'

The 'tomlkit' package is not installed in your Python environment or the environment where you are running your script is not active.

fix

Install the tomlkit library using pip: `pip install tomlkit`

AttributeError: module 'tomlkit' has no attribute 'dump'

Unlike some other configuration libraries (e.g., json, yaml, built-in toml), tomlkit does not provide a direct `dump()` function to write a TOMLDocument to a file-like object. You need to convert the document to a string first.

fix

Convert the TOMLDocument to a string using `tomlkit.dumps()` or `str()` before writing it to a file:
```python
import tomlkit

doc = tomlkit.document()
doc["example"] = "value"

# To write to a file
with open("config.toml", "w") as f:
    f.write(tomlkit.dumps(doc))
# Or using str()
# with open("config.toml", "w") as f:
#     f.write(str(doc))
```

KeyError: 'section_name'

You are attempting to access or assign a value within a nested TOML table (section) that has not yet been explicitly created in the TOMLDocument.

fix

Ensure that intermediate TOML tables (sections) are created as `tomlkit.table()` objects before trying to set keys within them:
```python
import tomlkit

doc = tomlkit.document()

# Correct way to create nested sections
doc["server"] = tomlkit.table()
doc["server"]["port"] = 8080

# If you want to add keys to an existing table or create a new one within it
doc["database"] = tomlkit.table()
doc["database"]["connection"] = tomlkit.table()
doc["database"]["connection"]["url"] = "localhost:5432"
```

Upgrade

Version history

0.15.1latest on PyPI · released Jul 17, 2026

Audit

Dependencies

requestsoptionalUsed for HTTP requests in documentation and examples

jinja2optionalEmployed in documentation for templating

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/python-poetry/tomlkit ↗

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