pyproject-fmt

pyproject-fmt formats pyproject.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.11 or later. An isolated tool environment avoids dependency conflicts with the target project.

uv tool install pyproject-fmt
pyproject-fmt --help
python -m pip install pipx-in-pipx --user
pipx install pyproject-fmt
pyproject-fmt --help
python -m pip install --user pyproject-fmt
pyproject-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/pyproject-fmt
  rev: ""
  hooks:
    - id: pyproject-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 pyproject_fmt import run

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

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

pyproject_fmt.build_parser()

Return the CLI argument parser, built without reading arguments, for documentation tooling.

Return type:

ArgumentParser

Returns:

the argument parser of the command line interface.

pyproject_fmt.run(args=None)

Format the named files, or sys.argv when args is None; return 1 after a change or rejection.

Parameters:

args (Sequence[str] | None) – the command line arguments, or None to read sys.argv.

Return type:

int

Returns:

1 when a file changed or was rejected, otherwise 0.

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