pyproject-fmt

library2.28.2pypypi✓ verified 24d ago

pyproject-fmt is an opinionated formatter for pyproject.toml files, designed to enforce a consistent format similar to how Black formats Python code. It intentionally provides minimal configuration options to establish a single standard format, which helps in reducing configuration time, producing smaller diffs, and simplifying code reviews. The current version is 2.21.1, and it maintains an active release cadence.

devops testing

pip install pyproject-fmt

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYPROJECT-FMT

pyproject-fmt

devopspythonv2.28.2

Install

2.0s avg

Import

151ms

Disk

29MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.28.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.164s · 33.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.0s · import 0.138s · 34MB

29MB installed

● package 29MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

run

✓ from pyproject_fmt import run

This quickstart demonstrates how to programmatically use `pyproject-fmt` to format a `pyproject.toml` file. The `run` function processes the file(s) and returns an exit code, where 0 indicates success. It also creates a temporary `pyproject.toml` if one doesn't exist for a runnable example.

import os from pyproject_fmt import run # Assuming a pyproject.toml file exists in the current directory for testing # Create a dummy pyproject.toml for demonstration if it doesn't exist if not os.path.exists('pyproject.toml'): with open('pyproject.toml', 'w') as f: f.write('[project]\nname = "my-package"\nversion = "0.1.0"\nrequires-python = ">=3.10"\ndependencies = ["requests"]\n') # Format a pyproject.toml file and return the exit code # The 'run' function accepts command-line arguments as a list. # Pass an empty list or specific file paths. exit_code = run(["pyproject.toml"]) if exit_code == 0: print("pyproject.toml formatted successfully.") else: print(f"Formatting failed with exit code: {exit_code}") # Clean up the dummy file if os.path.exists('pyproject.toml'): os.remove('pyproject.toml')

pyproject-fmt --version

Debug

Known issues

gotchapyproject-fmt is highly opinionated and offers minimal configuration options. Users expecting extensive customization (e.g., similar to some linters) may find this restrictive, as the goal is to enforce a single, consistent format.

fix

Embrace the opinionated formatting or use pre-commit hooks to automate formatting without manual intervention. Understand that configuration choices are deliberately limited.

affects: All versions

gotchaWhile direct `pip install pyproject-fmt` works, the official documentation recommends installing it into an isolated environment using tools like `uv` or `pipx`. Installing globally with `pip` might lead to inconsistencies with system-managed Python installations.

fix

Prefer `uv tool install pyproject-fmt` or `pipx install pyproject-fmt` for managing the tool.

affects: All versions

gotchaThe formatter will reorder tables and keys within your `pyproject.toml` file to a consistent, predefined structure (e.g., `[build-system]` first, followed by `[project]`, then `[tool]` sections in a specific order). This reordering is intentional for consistency but might surprise users on first use.

fix

Review the project's documentation on 'Table Organization' to understand the enforced structure. Allow the formatter to apply its intended order.

affects: All versions

gotchapyproject-fmt has specific, mostly non-configurable rules for string wrapping. Strings inside inline tables are never wrapped, and strings containing actual newlines are preserved as multi-line strings. You can use `skip_wrap_for_keys` for specific exceptions, but the overall wrapping behavior is fixed.

fix

Familiarize yourself with the string wrapping rules in the documentation. Use `skip_wrap_for_keys` in configuration if specific string keys should not be wrapped.

affects: All versions

gotchaWhen both a standalone `pyproject-fmt.toml` shared configuration file and a `[tool.pyproject-fmt]` section within the project's `pyproject.toml` exist, settings from the `[tool.pyproject-fmt]` table take precedence.

fix

Be aware of the configuration precedence. If you're using a shared config, ensure local project settings aren't unintentionally overriding it, or deliberately use local settings for project-specific overrides.

affects: All versions

gotchaUnlike some other popular Python formatters (e.g., Black), `pyproject-fmt` does not implement a 'magic comma' heuristic for lists (like dependencies). This means lists that exceed the configured column width will always be expanded to multiple lines, regardless of a trailing comma.

fix

Accept that lists will be formatted according to the tool's strict line-length rules, expanding to multiple lines if necessary, without the 'magic comma' influencing this behavior.

affects: All versions

Errors

Common errors & fixes

pyproject-fmt: command not found

The `pyproject-fmt` executable is not installed or not in your system's PATH.

fix

Install `pyproject-fmt` using pip, preferably within a virtual environment: `pip install pyproject-fmt`

error: path 'non_existent_file_or_dir' does not exist

The formatter was invoked with a path that does not correspond to an existing file or directory on the file system.

fix

Provide a valid path to an existing `pyproject.toml` file or a directory containing one. For the current directory, use: `pyproject-fmt .`

ERROR: Failed to parse pyproject.toml: Expected '=' after a key

The `pyproject.toml` file contains a syntax error, preventing the formatter from parsing its content according to the TOML specification.

fix

Review and correct the TOML syntax in your `pyproject.toml` file to resolve the parsing issue.

Upgrade

Version history

2.28.2latest on PyPI · released Aug 28, 2026

Audit

Dependencies

PythonrequiredRequired runtime environment.

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/tox-dev/toml-fmt ↗

packagehttps://pypi.org/project/pyproject-fmt/ ↗

docshttps://pyproject-fmt.readthedocs.io/en/latest/ ↗

changeloghttps://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/CHANGELOG.md ↗