NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #53 most downloaded on PyPI
Style preserving TOML library
Latest stable
0.15.2
Last release 1 months ago
16 Oct 2026
Release timing varies
gaps range from 2 weeks to 10 months
Nearly every release is documented
notes for 54 of 57 stable releases
Nothing withdrawn
no release was ever pulled
8 years old
57 releases · first in 2018
Drag across the ruler to compare, or tap a release to open it.
Fix inline table separator after append by @cyliu0 in #477
fold argument to Time and DateTime by @tuyentran4992 in #620Note truncated.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
\u001b instead of \e, which is only valid in TOML 1.1, so the output stays readable by TOML 1.0 parsers such as tomllib. (#641)key_value() now raises UnexpectedCharError on anything other than whitespace or a comment after the pair, instead of silently discarding it (e.g. key_value("a = 1 b = 2")), matching parse(). (#594)integer() given a string now validates it against the TOML integer grammar and keeps the original text, so grouping underscores (e.g. integer("1_000")) survive dumps(); strings that are not valid TOML integers (e.g. "010") now raise ValueError. (#336)fold argument to DateTime and Time, mirroring the stdlib, and carry fold through item(), arithmetic (including datetime subtraction) and unwrap(), so a folded local time no longer converts an hour off. (#619, #623, #626)[project] table; building from source now requires poetry-core>=2.2.0. (#607, #609)b = {}. (#664)[a.b.c] then [a] with b.z = 1 extends the implicit a.b super-table rather than redefining it (stdlib tomllib accepts it), so it now parses and round-trips instead of raising Redefinition of an existing table. The concrete-table case ([a.b] then [a] b.z = 1) stays rejected. (#565)E exponent after a leading-zero mantissa (e.g. 0E2) being rejected as an invalid number while 0e2 parsed fine. (#586)Inf, NaN, -INF) being accepted; TOML only allows lowercase inf and nan, so they now raise ParseError. (#628)item() reordering the keys of an inline table (dict-valued keys were forced last) under the default sort_keys=False. (#546)unwrap() moving a key to the end after its value was replaced (e.g. doc["b"] = 9), while dumps() and keys() kept the original order. (#591)", " separators emitting a bare "," for the new entry, leaving the table inconsistently spaced (e.g. {x = 1, y = 2,z = 3}). (#595)key = [], placed and keyed relative to the nearest table header so it parses back into the same table. (#567)add_line(value, comment=...)) rendering its closing ] on the comment line, producing unparseable output. (#580)del array[start:stop:step] with a negative or omitted bound removing the wrong elements from the rendered output. (#599)ValueError("slice assignment is not supported"). (#600)String.__add__ splicing the appended text into a basic string without escaping it, so appending a quote or backslash produced invalid TOML. (#612)\r in a multiline basic string and rejected with InvalidStringError in a multiline literal string; CRLF line endings are left intact. (#539)datetime.time rendering with a UTC offset (e.g. 07:32:00+02:00), which TOML local times do not allow; it now renders as a local time. (#613)+-0.0 (e.g. -1.5 times 0), which does not parse. (#629)Bool items never comparing equal to each other; they now compare by value. (#660)Fix inline table separator after append by @cyliu0 in #477
Full Changelog: 0.15.0...0.15.1
key in ...) on Container, Table and InlineTable with native __contains__ implementations, avoiding the inherited MutableMapping round-trip through __getitem__ (which resolves the value and builds an exception on every absent key). (#483)Source index-based: it now tracks an integer position over the input string instead of materializing a list of (index, char) tuples up front, so construction is O(1) and state save/restore no longer copies an iterator. (#489)Source.advance_while/advance_until consume a whole run of whitespace, bare-key or number characters in a single pass over the input string instead of one inc() call per character. (#490)TOMLChar wrapper: the parser now reads plain str characters from Source and detects end-of-input positionally, avoiding a per-character object construction and method dispatch. (#492)StringType members by identity (is) instead of building a set on every is_basic/is_literal/is_singleline/is_multiline call, avoiding millions of enum hashes while parsing. (#502)[a.b.c] / [a.b.d] headers) from O(n²) into O(n). (#503)key in ...) on out-of-order tables with a native OutOfOrderTableProxy.__contains__, completing #483 for the last mapping type that still inherited the slow MutableMapping mixin (which resolves the value and builds an exception on every absent key). (#515)files = [...] blocks that dominate lock files): the parser no longer attempts to read a value while sitting on the closing ], which previously built an UnexpectedCharError just to discard it — and constructing that exception eagerly computes a line/column by scanning the whole document, making it O(document size) per such array. (#517)"""/''' bodies the single-line fast path added in #491; a \r still stops the scan so \r\n stays validated and byte-for-byte preserved. (#518)unwrap() (converting a parsed document to a plain dict) by resolving each key directly from the container's key map instead of iterating the inherited MutableMapping view, which rebuilt a SingleKey from the bare string for every key just to re-look-up the value. Out-of-order tables still resolve through their proxy, so their validation is unchanged. (#521)as_string() / dumps()) of inline tables with many keys by precomputing the last-key and last-deleted-element indices in a single pass, instead of rescanning the remaining body on every separator comma — turning an O(n²) render into O(n). (#525)string() dropping a leading newline of a multiline string on round-trip: a value beginning with a newline is now rendered with an extra leading newline (the one the parser trims after the opening delimiter) so it survives re-parsing.ParseError when a sub-table extends the last element of an array of tables after an unrelated table. (#261)doc["a"] = {...} where a came from a.b = ...): the dotted prefix was duplicated onto the new [a] header, and the header then swallowed any sibling that follows it on round-trip. The replacement now renders as a plain table and, when needed, moves before the inline entries (values and dotted keys) it would otherwise capture. (#513, #524)dumps() rendering mapping-like wrappers around a parsed document (e.g. dotty_dict's Dotty) through their delegated as_string, preserving the original table order and layout instead of re-encoding through a plain dict — a 0.15.0 regression. (#482)RecursionError. Values nested more than 100 levels deep and keys with more than 100 dotted fragments now raise ParseError. (#459)comment() producing invalid TOML for a multiline string by prefixing every line with #, not just the first. (#449)KeyAlreadyPresent error when parsing or accessing an out-of-order table whose array-of-tables elements are split across the table's parts. (#505)tomllib behaviour. (#523)doc["a"] = aot(...) where a came from a.b = ...): the new [[a]] header kept the dotted key's inline position and swallowed the following dotted sibling on round-trip. The array of tables now renders past the inline entries it would otherwise capture, mirroring the table fix for #513. (#542)a.b = 1) whose table had gained a [a.c]-style child placed the scalar inside that table's scope, silently re-nesting it on round-trip. Scalars now move before such an entry, like they do before regular tables. (#543)[table] header when adding a key to an out-of-order table whose concrete header is declared after its sub-tables; the new key now lands in the existing concrete part instead of giving the header-less super part a second header. (#545)doc[k] = doc[k] rewriting [keys .'a'.'c'] to [keys.a.'c']. (#291)str() and repr() of out-of-order table proxies to show their merged values. (#536)feat(spec): update to toml spec v1.1 by @frostming in #456
Full Changelog: 0.14.0...0.15.0
chore(deps-dev): bump requests from 2.32.2 to 2.32.4 by @dependabot [bot] in #426
Full Changelog: 0.13.3...0.14.0
fix: register encoder's doc incorrectly mentions TypeError by @mathieu-lemay in #384
tmpdir fixture with tmp_path by @DimmaDont in #403Arrays by @DimmaDont in #409Full Changelog: 0.13.2...0.13.3
.item() method to array and tables to retrieve an item by key. (#390)fix: delete keys from out of order table by @frostming in #379
Full Changelog: 0.13.1...0.13.2
chore(deps-dev): bump setuptools from 68.0.0 to 70.0.0 by @dependabot in #367
Full Changelog: 0.13.0...0.13.1
fix: Test failures with Python 3.13.0a4: test_dates_behave_like_dates and test_times_behave_like_times by @frostming in #349
tomlkit 0.12.5 : Encoder contract interferes with external TypeErrors raised in encoders by @frostming in #358Full Changelog: 0.12.5...0.13.0
TypeError from a custom encoder. (#355)[pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in #337
Full Changelog: 0.12.4...0.12.5
indent exist check before accessing its property by @pinal005 in #328
|= does not work as expected on TOMLDocument by @frostming in #334Full Changelog: 0.12.3...0.12.4
chore(deps-dev): bump urllib3 from 1.26.17 to 1.26.18 by @dependabot in #320
Full Changelog: 0.12.2...0.12.3
Fix division for integers by @anibali in https://github.com/sdispater/tomlkit/pull/312
Full Changelog: https://github.com/sdispater/tomlkit/compare/0.12.1...0.12.2
Full Changelog: https://github.com/sdispater/tomlkit/compare/0.12.0...0.12.1
Full Changelog: https://github.com/sdispater/tomlkit/compare/0.12.0...0.12.1
fix: replace deprecated usage of datetime.utcnow by @frostming in https://github.com/sdispater/tomlkit/pull/308
Full Changelog: https://github.com/sdispater/tomlkit/compare/0.11.8...0.12.0
Remove the extra indentations added when parsing nested sub-tables.
Configure Read The Docs by @webknjaz in https://github.com/sdispater/tomlkit/pull/251
IO by @Avasam in https://github.com/sdispater/tomlkit/pull/272Full Changelog: https://github.com/sdispater/tomlkit/compare/0.11.6...0.11.7
unwrap() method for Container children values which sometimes returns an internal object if the table is an out-of-order table. (#264)Allow broader type for toml file path value
Fix the type annotation of unwrap() and datetime parsing.
Fix memleak by dropping lru cache by @Secrus in https://github.com/sdispater/tomlkit/pull/227
Full Changelog: https://github.com/sdispater/tomlkit/compare/0.11.3...0.11.4
lru_cache on methods. (#227)bugfix: items.Array __init__ didn't ignore Null that _group_values added. by @laixintao in https://github.com/sdispater/tomlkit/pull/221
Full Changelog: https://github.com/sdispater/tomlkit/compare/0.11.2...0.11.3
Absolute URL for documentation in README by @mondeja in https://github.com/sdispater/tomlkit/pull/210
Full Changelog: https://github.com/sdispater/tomlkit/compare/0.11.1...0.11.2
Keep consistent line endings when changing files.
KeyAlreadyPresent and InvalidStringError subclasses of ParseError. (#202)OutOfOrderTableProxy when deleting items. (#204)OutOfOrderTableProxy. (#205)unwrap() for String values to remove the quotes. (#199)Add unwrap method to recursive convert to plain old python objects by @syntapy in https://github.com/sdispater/tomlkit/pull/187
Full Changelog: https://github.com/sdispater/tomlkit/compare/0.10.2...0.11.0
unwrap methods that return tomlkit objects recursively converted to plain python objects. (#43)Use the plain python string representation of Key in KeyAlreadyPresent error message.
Preserve the newlines before super tables when rendering.
Fix the only child detection when creating tables.
When a table's only child is a table or array of table, it is created as a super table.
Fix a bug of separators not being kept when replacing the value.
Add an argument to allow table to be super table by @frostming in https://github.com/sdispater/tomlkit/pull/159
Full Changelog: https://github.com/sdispater/tomlkit/compare/0.8.0...0.9.0
table API to allow it to be a super table. (#159)Table and Container with dotted key. (#160)value() API that parses string incompletely. (#168)Support copy protocols for table items.
=. (#141)KeyAlreadyPresent when the table is separated into multiple parts. (#148)TOMLFile. (#149)Fixed an error where container's data were lost when copying.
Fixed an error with indent for nested table elements when updating.
py.typed file. (#109)Added support for sorting keys when dumping raw dictionaries by passing sort_keys=True to dumps() (#103).
sort_keys=True to dumps() (#103).Added support for heterogeneous arrays (#92).
Fix containers and our of order tables dictionary behavior (#82).
Fixed out of order tables not behaving properly
Fixed the behavior for out of order tables (#68).
Added support for producing multiline arrays
Fixed handling of inline tables.
Fixed appending inline tables to tables.
Fixed display of inline tables after element deletion.
Fixed the handling of inline tables.
setdefault() on containers (Thanks to @AndyKluger).### Fixed - Fixed copy of TOML documents. - Fixed behavior on PyPy3.
Fixed table header missing when replacing a super table's sub table with a single item.
Fixed deletion and replacement of sub tables declared after other tables.
Improved distinction between date(time)s and numbers.
KeyAlreadyPresent error when declaring a sub table after other tables.### Fixed - Fixed string parsing behavior.
Fixed trailing commas not raising an error for key/value.
Fixed performances issues while parsing on Python 2.7.
Fixed handling of characters that need escaping when inserting/modifying a string element.
Fixed insertion of an element after deletion.
Fixed adding an element after another element without a new line.
dumps() now also accepts a raw dictionary.
dumps() now also accepts a raw dictionary.add()/append()/remove() now return the current Container/Table to provide a fluent interface.Make new dicts automatically sorted when dumped.
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.