toml-sort

library0.24.4pypypi✓ verified 23d ago

toml-sort is a Python library and command-line utility for sorting and formatting TOML files. It provides features like sorting tables and arrays of tables, preserving comments, and standardizing whitespace and indentation. The library is actively maintained, with frequent releases, and is currently at version 0.24.4.

devops serialization

pip install toml-sort

github ↗package ↗

INSTALL

IMPORT

SIG · TOML-SORT

toml-sort

devopspythonv0.24.4

Install

1.6s avg

Import

68ms

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.24.4 · 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.074s · 18.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.062s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

TomlSort

✓ from toml_sort import TomlSort

✗ from toml_sort.tomlsort_tool import sort_toml_string

tomlsort

✓ from toml_sort import tomlsort

✗ from toml_sort.tomlsort_tool import sort_toml_string

Demonstrates how to sort a TOML string programmatically using the `sort_toml_string` function.

from toml_sort.tomlsort_tool import sort_toml_string unsorted_toml = ''' [database] ports = [8000, 8001, 8002] enabled = true [owner] name = "Tom" dob = 1979-05-27T07:32:00-08:00 ''' sorted_toml = sort_toml_string(unsorted_toml) print(sorted_toml)

toml-sort --version

Debug

Known issues

breakingVersion 0.24.0 dropped official support for Python 3.7 and 3.8. Users should upgrade to Python 3.9 or newer.

fix

Upgrade your Python environment to 3.9 or later.

affects: >=0.24.0

breakingVersion 0.24.0 removed support for `tomlkit` versions older than 0.13.2. Ensure `tomlkit` is updated.

fix

Update `tomlkit` to version 0.13.2 or newer (`pip install --upgrade tomlkit`).

affects: >=0.24.0

gotchaSorting inline tables with keys containing trailing spaces could cause a `ValueError` in versions 0.24.0 and 0.24.1. This was a regression.

fix

Upgrade to version 0.24.2 or later, which includes a fix for this regression.

affects: 0.24.0, 0.24.1

gotchaBy default, `toml-sort` only sorts non-inline tables and arrays of tables. To sort all keys, including scalars and non-table entries, use the `--all` CLI option or configure `sort_all = true` in `pyproject.toml`.

fix

Use `toml-sort --all <file>` or add `sort_all = true` under `[tool.toml_sort]` in your `pyproject.toml`.

affects: All

gotchaComment handling can be complex. While `toml-sort` strives to preserve comments, specific types of comments (header, footer, inline, block) can be selectively disabled via CLI switches, which will lead to their removal.

fix

Review the documentation for comment handling options if comments are unexpectedly altered or removed. Use `--no-comments`, `--no-header`, etc., as needed.

affects: All

gotcha`toml-sort` can be configured via `pyproject.toml` under the `[tool.toml_sort]` section. Command-line arguments will always take precedence over `pyproject.toml` settings in case of conflicts.

fix

Be aware of the precedence order. Use CLI arguments for temporary overrides or specific runs, and `pyproject.toml` for project-wide default configurations.

affects: All

Upgrade

Version history

0.24.4latest on PyPI · released Mar 24, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.9 or newer. Support for Python 3.7 and 3.8 was dropped in version 0.24.0.

tomlkitrequiredCore dependency for TOML parsing and manipulation. Version >=0.13.2 is required; older versions (<0.13.2) are no longer supported since v0.24.0.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/pappasam/toml-sort ↗

packagehttps://pypi.org/project/toml-sort/ ↗