Overview¶

Apply a consistent format to your pyproject.toml file with comment support. See changelog here.

Philosophy¶

This is an opinionated formatter, with the same objectives as black: it offers few configuration settings on purpose. In return you get consistency, predictability, and smaller diffs.

Use¶

Via `CLI`¶

pyproject-fmt is a CLI tool that needs Python 3.10 or higher to run. Install it into an isolated environment with pipx or uv; that way you can upgrade pyproject-fmt later without disturbing the rest of your system. A pip path follows for completeness, though we discourage it:

# install uv per https://docs.astral.sh/uv/#getting-started
uv tool install pyproject-fmt
pyproject-fmt --help

pipx

python -m pip install pipx-in-pipx --user
pipx install pyproject-fmt
pyproject-fmt --help

pip

python -m pip install --user pyproject-fmt
pyproject-fmt --help

You can install it into the global Python interpreter (as a user package via the --user flag). Take care if your Python is managed by the operating system or another package manager: pip may not coordinate with those tools and can leave your system inconsistent. On this path, make sure pip is new enough per the subsections below.

Via `pre-commit` hook¶

See pre-commit/pre-commit for instructions, sample .pre-commit-config.yaml:

- repo: https://github.com/tox-dev/pyproject-fmt
  # Use the sha / tag you want to point at
  # or use `pre-commit autoupdate` to get the latest version
  rev: ""
  hooks:
    - id: pyproject-fmt

Via Python¶

Call pyproject-fmt as a Python module to format TOML from your own code.

from pyproject_fmt import run

# Format a pyproject.toml file and return the exit code
exit_code = run(["path/to/pyproject.toml"])

The run function accepts command-line arguments as a list and returns an exit code (0 for success, non-zero for failure).

Format pyproject.toml files.

pyproject_fmt.run(args=None)¶

Run the formatter.

Parameters:: args (Sequence[str] | None) – CLI arguments
Return type:: int
Returns:: exit code

See Configuration for configuration options and command line interface.