tox-toml-fmt¶

tox-toml-fmt formats tox.toml files without discarding comments. It uses a small configuration surface to keep results stable across projects. See the release history for version changes.

Install¶

The command requires Python 3.10 or later. An isolated tool environment avoids dependency conflicts with the target project.

uv tool install tox-toml-fmt
tox-toml-fmt --help

pipx

python -m pip install pipx-in-pipx --user
pipx install tox-toml-fmt
tox-toml-fmt --help

pip

python -m pip install --user tox-toml-fmt
tox-toml-fmt --help

A user installation shares the interpreter’s package set. Prefer uv or pipx when an operating system or package manager owns that interpreter.

Pre-commit¶

Add the hook to .pre-commit-config.yaml and set rev to the required release:

- repo: https://github.com/tox-dev/tox-toml-fmt
  rev: ""
  hooks:
    - id: tox-toml-fmt

See pre-commit/pre-commit for installation and update commands.

Python API¶

run accepts command-line arguments and returns the process exit code:

from tox_toml_fmt import run

exit_code = run(["path/to/tox.toml"])

Keep Python callers on the same parser as the tox-toml-fmt CLI.

tox_toml_fmt.build_parser()¶

Build the parser without reading arguments, for documentation tooling.

Return type:: ArgumentParser

tox_toml_fmt.run(args=None)¶

Use a supplied argument list for embedding; the console entry reads sys.argv.

Return 1 after a change or rejection, and 0 when inputs match.

Return type:: int

See the configuration reference for settings and the formatting reference for the rules applied to each table.