Overview¶

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

Philosophy¶

This tool aims to be an opinionated formatter, with similar objectives to black. This means it deliberately does not support a wide variety of configuration settings. In return, you get consistency, predictability, and smaller diffs.

Use¶

Via `CLI`¶

pyproject-fmt is a CLI tool that needs a Python interpreter (version 3.10 or higher) to run. We recommend either pipx or uv to install pyproject-fmt into an isolated environment. This has the added benefit that later you will be able to upgrade pyproject-fmt without affecting other parts of the system. We provide a method for pip too here, but we discourage that path if you can:

# 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 within the global Python interpreter itself (perhaps as a user package via the --user flag). Be cautious if you are using a Python installation that is managed by your operating system or another package manager. pip might not coordinate with those tools, and may leave your system in an inconsistent state. Note, if you go down this path you need to ensure 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¶

You can use pyproject-fmt as a Python module to format TOML content programmatically.

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.