Skip to main content

toml-tidy

Abstract TOML sorting transformation

CI PyPI version Supported Python versions MIT license pre-commit integration Trunk integration

Sort TOML keys while preserving table hierarchy and source formatting where tomlkit supports it.

Install

Install from PyPI:

pip install toml-tidy

Or as a standalone tool with uv:

uv tool install toml-tidy

Or run it once without installing:

uvx toml-tidy pyproject.toml

For development from a local checkout, use uv tool install ..

Usage

toml-tidy pyproject.toml
toml-tidy pyproject.toml --check
toml-tidy pyproject.toml --diff
toml-tidy pyproject.toml --in-place --order natural
toml-tidy config/*.toml --in-place --scope tables

The command accepts one or more file paths and processes each one, so it works directly as a pre-commit or trunk formatter target.

Without --in-place, sorted TOML is written to standard output; this mode takes exactly one path so separate documents never get concatenated.

--check writes nothing and exits with status 1 when any file requires sorting.

--diff also writes nothing: it prints a unified diff for each file that requires sorting, against exactly what --in-place would write, and exits with status 1 when any file requires sorting. The diff keeps each file's own line endings, so patch applies it to the file it came from. Each header carries the path as it was given on the command line, so pass relative paths and run patch -p0 from the same directory: GNU patch ignores an absolute or .. header path as unsafe. A file that requires sorting but whose path patch would not read back as exactly that name (leading or trailing whitespace, a control character such as a TAB or line break, or a leading double quote) gets an error with status 2 instead of a diff. --diff cannot be combined with --in-place or --check.

--in-place rewrites each file only when sorting changes it.

With multiple paths the worst exit code wins: 2 for any error, else 1 for any --check or --diff difference, else 0; an error in one file does not stop the remaining files.

--scope limits what gets sorted: all (default) sorts everything, tables sorts only sibling table declarations, and keys sorts only direct key-value entries.

--blank-lines additionally normalizes blank lines to exactly one before every table header and none anywhere else; --no-blank-lines (the default) leaves every blank line where it was.

--line-width expands single-line arrays whose line would be wider than the given column count; with no value set, every array keeps its own layout.

Configuration

Defaults can be set in a .toml-tidy.toml or toml-tidy.toml file, with the keys at the top level, or under [tool.toml-tidy] in a pyproject.toml. CLI flags always override the configuration.

# toml-tidy.toml
order = "natural"   # "alpha" | "version"
scope = "all"       # "tables" | "keys"
first = ["project", "build-system"]
blank-lines = false # true normalizes blank lines
line-width = 88     # omit to leave array layout alone

first pins top-level entries by name, in the listed order, ahead of their sorted siblings; it never applies inside nested tables, and it has no CLI flag.

Unknown keys are rejected so configuration typos cannot silently fall back to defaults.

Discovery follows Ruff's rules:

  • Each target file uses the closest configuration file found walking up from its directory to the filesystem root.
  • In one directory, .toml-tidy.toml wins over toml-tidy.toml, which wins over pyproject.toml. A dedicated file applies even when it is empty.
  • A pyproject.toml counts only when it contains a [tool.toml-tidy] table; one without the table is skipped and the walk continues upward, so a sub-package's pyproject.toml does not hide the root configuration.
  • Settings are never merged: the closest file is used, and every file above it, or a [tool.toml-tidy] table beside a winning dedicated file, is ignored.
  • --config <path> uses the given dedicated file or pyproject.toml for every target and skips discovery. A pyproject.toml without the table means the defaults. A missing or invalid --config file exits with status 2 before any target is processed.
  • When the hierarchy holds no configuration file, the first existing file among .toml-tidy.toml, toml-tidy.toml and pyproject.toml in the user-level toml-tidy directory applies; if there is none, or that directory cannot be located or searched, the defaults apply. On Linux and macOS that directory is $XDG_CONFIG_HOME/toml-tidy when XDG_CONFIG_HOME is an absolute path, else ~/.config/toml-tidy. On Windows it is %APPDATA%\toml-tidy, else ~\AppData\Roaming\toml-tidy.

pre-commit

repos:
  - repo: https://github.com/AndrewDongminYoo/toml-tidy
    rev: v0.7.0 # pin the latest release; the hook ships from v0.2.0 onward
    hooks:
      - id: toml-tidy

The hook runs toml-tidy --in-place, and args are appended to it, so flags are set per repository without losing in-place rewriting:

hooks:
  - id: toml-tidy
    args: [--blank-lines, --order, alpha]

From v0.7.0, the hook only runs on files ending in .toml and on Pipfile, so generated lockfiles such as uv.lock, poetry.lock and Cargo.lock are left alone without an exclude.

Trunk

toml-tidy is available as an opt-in formatter through Trunk.

See the official Trunk plugin definition for setup and runtime requirements.

Ordering

natural is the default and compares digit runs numerically, so item2 precedes item10.

alpha uses case-insensitive lexical order.

version follows the Rust style guide's version sorting as rustfmt implements it, the order used for Cargo manifests. Unlike natural, it is case-sensitive, so B precedes a; each _ sorts right after a space and before any other character, as the guide states rather than first as rustfmt does, so item_a precedes item1; only ASCII digits form numbers; and among equal numbers the one with more leading zeros comes first, so v00 precedes v0.

All modes compare TOML's parsed logical key, not source quoting.

Dotted keys such as b.a = 2 sort with their sibling direct keys by their parsed dotted path, segment by segment, so a precedes b.a, which precedes b.z.

For example, [plugins.omo] precedes [plugins."omo-kit"], while the quoted spelling remains unchanged in output.

Preservation

Direct keys and sibling explicit table declarations are sorted recursively within their parent table.

Array-of-tables declarations such as [[items]] sort by name among their sibling tables, while the element order inside each array of tables remains unchanged.

Parent-child hierarchy remains unchanged.

Standalone comments move with the following key or table declaration.

Whitespace between entries remains after the preceding entry, and trailing whitespace remains at its table boundary, unless --blank-lines is enabled.

Inline comments and key quoting remain attached to their parsed tomlkit items.

Every non-empty single-line array uses one space after [ and before ], and one space after each separating comma with none before it. A trailing comma keeps its place at the end of the array. Empty and multi-line arrays keep their source layout.

Keys inside inline tables are not reordered.

Line width

--line-width (config: line-width = 88) is unset by default and runs after sorting. It only ever expands an array onto several lines; it never joins a multi-line array back into one.

  • An array is measured as the whole line it renders on, including indentation and the key, and is expanded when that line exceeds the given width.
  • A comment trailing the array is not counted, because expanding the array moves the comment but cannot shorten it.
  • Only an array that is the direct value of a key is measured, since only that array occupies a line of its own. Arrays nested inside another array or an inline table share their parent's line and are left alone.
  • An array that already spans several lines is never measured or rejoined, so a second run changes nothing.
  • An empty array is never expanded, because doing so cannot make its line shorter.
  • An expanded array reuses the line ending of the line it sits on, so a CRLF or mixed-ending document keeps its endings.

Blank lines

--blank-lines (config: blank-lines = true) is off by default and runs after sorting. It rewrites blank lines only, never comments or values:

  • Exactly one blank line precedes every table and array-of-tables header, above the comment run attached to that header rather than between the comment and the header.
  • No blank lines remain between key-value entries, inside a comment run, or at the end of the file.
  • The document's first rendered line never gains a blank line above it.
  • Blank lines inside multi-line string values belong to the value, not to the layout, and are untouched.

Given this input:

a = 1

b = 2
[x]
p = 1


[y]
q = 1

toml-tidy --blank-lines produces:

a = 1
b = 2

[x]
p = 1

[y]
q = 1

The result is stable, so --check reports a file once and reports it clean after --in-place fixes it.

Development

Run the same quality gates enforced by CI before committing:

uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run basedpyright

CI runs the test suite on every supported Python version and against the lower and upper tested tomlkit patch releases because the sorter intentionally isolates a dependency on tomlkit's private container representation.

Releasing

A release is prepared on a release/vX.Y.Z branch: bump project.version, run uv lock, date the CHANGELOG section and add its compare link, and update the pre-commit rev above.

Merge that pull request first, then tag the merge commit and push the tag. Pushing the tag runs the tests, publishes to PyPI, and creates the GitHub Release from the tagged CHANGELOG section. A tag on any commit main has never pointed at is refused before anything is published — tagging a branch tip puts the artifact on PyPI before that branch's own review has landed on it, and the commit that was merged does not carry what the review added.

Metadata

Release files for toml-tidy 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for toml-tidy 0.7.0
File Size Uploaded Provenance Actions
toml_tidy-0.7.0.tar.gz 25.4 kB Without provenance Details for toml_tidy-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for toml-tidy 0.7.0
File Interpreter ABI Platform Actions
toml_tidy-0.7.0-py3-none-any.whl Python 3 none any Details for toml_tidy-0.7.0-py3-none-any.whl

Total release size: 51.4 kB

Release files / toml_tidy-0.7.0.tar.gz

Download URL toml_tidy-0.7.0.tar.gz
Size 25.4 kB
Tags Source
SHA-256 checksum
How to use checksums
8905bcb487d0ff6b4ccbb8b664703f409e6e21814737f0ffcc52bfd56e393313
BLAKE2b-256 checksum
How to use checksums
29ee9a582e4fe3142a8d944e41e5ecf5747707d01ad3de1f02b8e00ee089671c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / toml_tidy-0.7.0-py3-none-any.whl

Download URL toml_tidy-0.7.0-py3-none-any.whl
Size 25.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
57de8429fd788f532495b743d526552379aa3a616280ded6d9d0a47489232905
BLAKE2b-256 checksum
How to use checksums
c373853230301d0485ef95d11e9a9e6889090929174d31be80454ccf77eb46aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for toml-tidy 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page