toml-sort

toml-sort is a focused CLI utility and Python library for normalizing the structure of TOML files. It sorts tables and arrays of tables alphabetically, standardizes whitespace and indentation, and gives fine-grained control over which comments and keys are preserved during the rewrite — all built on top of tomlkit’s format-preserving parser.

The tool is commonly wired into pre-commit hooks and CI pipelines to keep pyproject.toml, Cargo.toml-adjacent config, and other TOML sources consistently ordered across a team, with a --check mode for linting without mutating files. Because it can also be driven from pyproject.toml itself via a [tool.tomlsort] section, projects can standardize its behavior alongside their other tooling configuration rather than passing flags on every invocation.

What You Get

• A toml-sort CLI with stdin/stdout, -o/--output, and -i/--in-place modes for one-off or scripted use
• A --check flag that exits non-zero when a file would be reformatted, for use as a CI lint gate
• Granular sort controls (--all, --sort-table-keys, --sort-inline-tables, --sort-inline-arrays, --sort-first) instead of an all-or-nothing sort
• Comment-preservation flags (--no-header-comments, --no-footer-comments, --no-inline-comments, --no-block-comments) for controlling exactly what survives the rewrite
• Project-level configuration via a [tool.tomlsort] table in pyproject.toml, merged with CLI flags
• A TomlSort Python class for embedding the same sorting/formatting logic directly in other tools

Common Use Cases

• Running as a pre-commit hook (it ships a .pre-commit-hooks.yaml) to keep every contributor’s TOML files identically ordered
• Gating CI on toml-sort --check so unsorted or inconsistently formatted TOML fails the build before merge
• Normalizing generated or hand-edited config files (pyproject.toml, Cargo.toml-style manifests) before committing
• Embedding TomlSort in another Python tool that needs to programmatically reformat TOML output deterministically

Under The Hood

Architecture toml-sort is a thin, purpose-built layer over tomlkit’s format-preserving TOML parser. toml_sort/tomlsort.py walks the parsed TOMLDocument, wrapping each item in a TomlSortItem (paired with a TomlSortKeys path) so it can track which comments are attached to which node while it reorders tables, arrays of tables, and (optionally) inline structures. toml_sort/cli.py is a separate, thin argument-parsing layer that builds SortConfiguration/CommentConfiguration/FormattingConfiguration/SortOverrideConfiguration dataclasses from CLI flags or a [tool.tomlsort] pyproject.toml table and hands them to the TomlSort class — the same configuration objects are the public library API, so CLI and library usage share one code path. Changing the core sort algorithm in tomlsort.py would ripple through both surfaces uniformly, since neither layer duplicates sorting logic.

Tech Stack The project targets Python 3.9+ and depends on a single runtime library, tomlkit (>=0.13.2), for round-trip-safe TOML parsing. Packaging and dependency management use Poetry (poetry-core build backend, poetry.lock committed), with nox orchestrating lint and typecheck sessions and ruff handling both linting (pydocstyle/pycodestyle/pyflakes/isort rule sets) and formatting. Mypy runs in strict mode against Python 3.9 semantics. CI (GitHub Actions) runs lint and typecheck first, then executes the test matrix across Python 3.9 through 3.14, and a separate release workflow publishes to PyPI.

Code Quality The test suite (tests/test_cli.py and tests/test_toml_sort.py, plus fixture files under tests/examples/) is substantial relative to the ~1,200-line implementation, covering CLI flag combinations and the library’s sorting behavior directly. Mypy strict mode plus a py.typed marker signal a fully type-annotated public API, and ruff enforces consistent docstrings and import ordering. Error handling is minimal by necessity — this is a text-transformation utility, not a service — with the CLI surfacing tomlkit parse errors and returning non-zero exit codes rather than swallowing failures.

What Makes It Unique Most TOML tooling either re-serializes a file from a parsed data structure (losing comments and formatting) or leaves ordering untouched entirely. toml-sort’s differentiator is granular, comment-aware sorting on top of a format-preserving parser: it can sort just top-level tables while leaving inline tables and arrays untouched, pin specific keys first, and selectively keep or drop header/footer/inline/block comments — control that plain --check-style formatters in this space generally do not expose.