pyproject-fmt

2.21.1 · active · verified Mon Apr 13

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.

Warnings

gotcha pyproject-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.
gotcha While 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.
gotcha The 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.
gotcha pyproject-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.
gotcha When 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.
gotcha Unlike 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.

Install

pip install pyproject-fmt Standard pip installation (isolated environments like uv or pipx are recommended)
uv tool install pyproject-fmt Recommended installation with uv
pipx install pyproject-fmt Recommended installation with pipx

Imports

run
```
from pyproject_fmt import run
```

Quickstart

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')

view raw JSON →