pyproject-fmt 2.21.0

Recent Changes

• ✨ feat(pyproject-fmt): add pixi support by @gaborbernat in #283 <a id=”2.20.0”></a>

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

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

The tool.pyproject-fmt table is used when present in the pyproject.toml file:

[tool.pyproject-fmt]

# After how many columns split arrays/dicts into multiple lines and wrap long strings;
# use a trailing comma in arrays to force multiline format instead of lowering this value
column_width = 120

# Number of spaces for indentation
indent = 2

# Keep full version numbers (e.g., 1.0.0 instead of 1.0) in dependency specifiers
keep_full_version = false

# Automatically generate Python version classifiers based on requires-python
# Set to false to disable automatic classifier generation
generate_python_version_classifiers = true

# Maximum Python version for generating version classifiers
max_supported_python = "3.14"

# Table format: "short" collapses sub-tables to dotted keys, "long" expands to [table.subtable] headers
table_format = "short"

# List of tables to force expand regardless of table_format setting
expand_tables = []

# List of tables to force collapse regardless of table_format or expand_tables settings
collapse_tables = []

# List of key patterns to skip string wrapping (supports wildcards like *.parse or tool.bumpversion.*)
skip_wrap_for_keys = []

If not set they will default to values from the CLI.

pyproject-fmt --config /path/to/pyproject-fmt.toml pyproject.toml

column_width = 120
indent = 2
table_format = "short"
max_supported_python = "3.14"

[project]
name = "myproject"
urls.homepage = "https://example.com"
urls.repository = "https://github.com/example/myproject"
scripts.mycli = "mypackage:main"

[project]
name = "myproject"

[project.urls]
homepage = "https://example.com"
repository = "https://github.com/example/myproject"

[project.scripts]
mycli = "mypackage:main"

Configuration priority

The formatting behavior is determined by a priority system that allows you to set a global default while overriding specific tables:

1. collapse_tables - Highest priority, forces specific tables to be collapsed regardless of other settings

2. expand_tables - Medium priority, forces specific tables to be expanded

3. table_format - Lowest priority, sets the default behavior for all tables not explicitly configured

This three-tier approach lets you fine-tune formatting for specific tables while maintaining a consistent default. For example:

[tool.pyproject-fmt]
table_format = "short"  # Collapse most tables
expand_tables = ["project.entry-points"]  # But expand entry-points

Specificity rules

Table selectors follow CSS-like specificity rules: more specific selectors win over less specific ones. When determining whether to collapse or expand a table, the formatter checks from most specific to least specific until it finds a match.

For example, with this configuration:

[tool.pyproject-fmt]
table_format = "long"  # Expand all tables by default
collapse_tables = ["project"]  # Collapse project sub-tables
expand_tables = ["project.optional-dependencies"]  # But expand this specific one

The behavior will be:

• project.urls → collapsed (matches project in collapse_tables)

• project.scripts → collapsed (matches project in collapse_tables)

• project.optional-dependencies → expanded (matches exactly in expand_tables, more specific than project)

• tool.ruff.lint → expanded (no match in collapse/expand, uses table_format default)

This allows you to set broad rules for parent tables while making exceptions for specific sub-tables. The specificity check walks up the table hierarchy: for project.optional-dependencies, it first checks if project.optional-dependencies is in collapse_tables or expand_tables, then checks project, then falls back to the table_format default.

Supported tables

The following sub-tables can be formatted with this configuration:

Project tables:

• project.urls - Project URLs (homepage, repository, documentation, changelog)

• project.scripts - Console script entry points

• project.gui-scripts - GUI script entry points

• project.entry-points - Custom entry point groups

• project.optional-dependencies - Optional dependency groups

Tool tables:

• tool.ruff.format - Ruff formatter settings

• tool.ruff.lint - Ruff linter settings

• Any other tool sub-tables

Array of tables:

• project.authors - Can be inline tables or [[project.authors]]

• project.maintainers - Can be inline tables or [[project.maintainers]]

• Any [[table]] entries throughout the file

Array of tables ([[table]]) are automatically collapsed to inline arrays when each inline table fits within the configured column_width. For example:

# Before
[[tool.commitizen.customize.questions]]
type = "list"

[[tool.commitizen.customize.questions]]
type = "input"

# After (with table_format = "short")
[tool.commitizen]
customize.questions = [{ type = "list" }, { type = "input" }]

If any inline table exceeds column_width, the array of tables remains in [[...]] format to maintain readability and TOML 1.0.0 compatibility (inline tables cannot span multiple lines).

[tool.pyproject-fmt]
skip_wrap_for_keys = ["*.parse", "*.regex", "tool.bumpversion.*"]

Pattern matching

The skip_wrap_for_keys option supports glob-like patterns:

• Exact match: tool.bumpversion.parse matches only that specific key

• Wildcard suffix: *.parse matches any key ending with .parse (e.g., tool.bumpversion.parse, project.parse)

• Wildcard prefix: tool.bumpversion.* matches any key under tool.bumpversion (e.g., tool.bumpversion.parse, tool.bumpversion.serialize)

• Global wildcard: * skips wrapping for all strings

Examples: ["*.parse", "*.regex"] to preserve regex fields, ["tool.bumpversion.*"] for a specific tool section, or ["*"] to skip all string wrapping.

pyproject-fmt is an opinionated formatter, much like black is for Python code. The tool intentionally provides minimal configuration options because the goal is to establish a single standard format that all pyproject.toml files follow.

Benefits of this approach:

• Less time configuring tools

• Smaller diffs when committing changes

• Easier code reviews since formatting is never a question

While a few key options exist (column_width, indent, table_format), the tool does not expose dozens of toggles. You get what the maintainers have chosen to be the right balance of readability, consistency, and usability. The column_width setting controls when arrays are split into multiple lines and when string values are wrapped using line continuations.

Table Ordering

Tables are reordered into a consistent structure:

1. [build-system]

2. [project]

3. [dependency-groups]

4. [tool.*] sections in the order:

   1. Build backends: poetry, poetry-dynamic-versioning, pdm, setuptools, distutils, setuptools_scm, hatch, flit, scikit-build, meson-python, maturin, pixi, whey, py-build-cmake, sphinx-theme-builder, uv

   2. Builders: cibuildwheel, nuitka

   3. Linters/formatters: autopep8, black, ruff, isort, flake8, pycln, nbqa, pylint, repo-review, codespell, docformatter, pydoclint, tomlsort, check-manifest, check-sdist, check-wheel-contents, deptry, pyproject-fmt, typos, bandit

   4. Type checkers: mypy, pyrefly, pyright, ty, django-stubs

   5. Testing: pytest, pytest_env, pytest-enabler, coverage

   6. Task runners: doit, spin, tox

   7. Release tools: bumpversion, jupyter-releaser, tbump, towncrier, vendoring

   8. Any other tool.* in alphabetical order

5. Any other tables (alphabetically)

String Quotes

All strings use double quotes by default. Single quotes are only used when the value contains double quotes:

# Before
name = 'my-package'
description = "He said \"hello\""

# After
name = "my-package"
description = 'He said "hello"'

Key Quotes

TOML keys are normalized to the simplest valid form. Keys that are valid bare keys (containing only A-Za-z0-9_-) have redundant quotes stripped. Single-quoted (literal) keys that require quoting are converted to double-quoted (basic) strings with proper escaping. This applies to all keys: table headers, key-value pairs, and inline table keys:

# Before
[tool."ruff"]
"line-length" = 120
lint.per-file-ignores.'tests/*' = ["S101"]

# After
[tool.ruff]
line-length = 120
lint.per-file-ignores."tests/*" = ["S101"]

Backslashes and double quotes within literal keys are escaped during conversion:

# Before
lint.per-file-ignores.'path\to\file' = ["E501"]

# After
lint.per-file-ignores."path\\to\\file" = ["E501"]

Array Formatting

Arrays are formatted based on line length, trailing comma presence, and comments:

# Short arrays stay on one line
keywords = ["python", "toml"]

# Long arrays that exceed column_width are expanded and get a trailing comma
dependencies = [
    "requests>=2.28",
    "click>=8.0",
]

# Trailing commas signal intent to keep multiline format
classifiers = [
    "Development Status :: 4 - Beta",
]

# Arrays with comments are always multiline
lint.ignore = [
    "E501",  # Line too long
    "E701",
]

Multiline formatting rules:

An array becomes multiline when any of these conditions are met:

1. Trailing comma present - A trailing comma signals intent to keep multiline format

2. Exceeds column width - Arrays longer than column_width are expanded (and get a trailing comma added)

3. Contains comments - Arrays with inline or leading comments are always multiline

String Wrapping

Strings that exceed column_width (including the key name and " = " prefix) are wrapped into multi-line triple-quoted strings using line continuations:

# Before (exceeds column_width)
description = "A very long description that goes beyond the configured column width limit"

# After
description = """\
  A very long description that goes beyond the \
  configured column width limit\
  """

Wrapping prefers breaking at spaces and at " :: " separators (common in Python classifiers). Strings inside inline tables are never wrapped. Strings that contain actual newlines are preserved as multi-line strings without adding line continuations. Use skip_wrap_for_keys to prevent wrapping for specific keys.

Table Formatting

Sub-tables can be formatted in two styles controlled by table_format:

Short format (collapsed to dotted keys):

[project]
urls.homepage = "https://example.com"
urls.repository = "https://github.com/example/project"

Long format (expanded to table headers):

[project.urls]
homepage = "https://example.com"
repository = "https://github.com/example/project"

Comment Preservation

All comments are preserved during formatting:

• Inline comments - Comments after a value on the same line stay with that value

• Leading comments - Comments on the line before an entry stay with the entry below

• Block comments - Multi-line comment blocks are preserved

Inline comment alignment:

Inline comments within arrays are aligned independently per array, based on that array’s longest value:

# Before - comments at inconsistent positions
lint.ignore = [
  "COM812", # Conflict with formatter
  "CPY", # No copyright statements
  "ISC001",   # Another rule
]

# After - comments align to longest value in this array
lint.ignore = [
  "COM812",  # Conflict with formatter
  "CPY",     # No copyright statements
  "ISC001",  # Another rule
]

[build-system]

Key ordering: build-backend → requires → backend-path

Value normalization:

• requires: Dependencies normalized per PEP 508 and sorted alphabetically by package name

• backend-path: Entries sorted alphabetically

# Before
[build-system]
requires = ["setuptools >= 45", "wheel"]
build-backend = "setuptools.build_meta"

# After
[build-system]
build-backend = "setuptools.build_meta"
requires = ["setuptools>=45", "wheel"]

[project]

Key ordering:

Keys are reordered in this sequence: name → version → import-names → import-namespaces → description → readme → keywords → license → license-files → maintainers → authors → requires-python → classifiers → dynamic → dependencies → optional-dependencies → urls → scripts → gui-scripts → entry-points

Field normalizations:

name

Converted to canonical format (lowercase with hyphens): My_Package → my-package

description

Whitespace normalized: multiple spaces collapsed, consistent spacing after periods.

license

License expression operators (and, or, with) uppercased: MIT or Apache-2.0 → MIT OR Apache-2.0

requires-python

Whitespace removed: >= 3.9 → >=3.9

keywords

Deduplicated (case-insensitive) and sorted alphabetically.

dynamic

Sorted alphabetically.

import-names / import-namespaces

Semicolon spacing normalized (foo;bar → foo; bar), entries sorted alphabetically.

classifiers

Deduplicated and sorted alphabetically.

authors / maintainers

Sorted by name, then email. Keys within each entry ordered: name → email.

Dependency normalization:

All dependency arrays (dependencies, optional-dependencies.*) are:

• Normalized per PEP 508: spaces removed, redundant .0 suffixes stripped (unless keep_full_version = true)

• Sorted alphabetically by canonical package name

# Before
dependencies = ["requests >= 2.0.0", "click~=8.0"]

# After
dependencies = ["click>=8", "requests>=2"]

Optional dependencies extra names:

Extra names are normalized to lowercase with hyphens:

# Before
[project.optional-dependencies]
Dev_Tools = ["pytest"]

# After
[project.optional-dependencies]
dev-tools = ["pytest"]

Python version classifiers:

Classifiers for Python versions are automatically generated based on requires-python and max_supported_python. Disable with generate_python_version_classifiers = false.

# With requires-python = ">=3.10" and max_supported_python = "3.14"
classifiers = [
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
]

Entry points:

Inline tables within entry-points are expanded to dotted keys:

# Before
entry-points.console_scripts = { mycli = "mypackage:main" }

# After
entry-points.console_scripts.mycli = "mypackage:main"

Authors/maintainers formatting:

Contact information can be formatted as inline tables or expanded array of tables:

# Short format (inline)
authors = [{ name = "Alice", email = "alice@example.com" }]

# Long format (array of tables)
[[project.authors]]
name = "Alice"
email = "alice@example.com"

Controlled by table_format, expand_tables, and collapse_tables.

[dependency-groups]

Key ordering: dev → test → type → docs → others alphabetically

Value normalization:

• All dependencies normalized per PEP 508

• Sorted: regular dependencies first, then include-group entries

# Before
[dependency-groups]
dev = [{ include-group = "test" }, "ruff>=0.4", "mypy>=1"]

# After
[dependency-groups]
dev = ["mypy>=1", "ruff>=0.4", { include-group = "test" }]

[tool.ruff]

Key ordering:

Keys are reordered in a logical sequence:

1. Global settings: required-version → extend → target-version → line-length → indent-width → tab-size

2. Path settings: builtins → namespace-packages → src → include → extend-include → exclude → extend-exclude → force-exclude → respect-gitignore

3. Behavior flags: preview → fix → unsafe-fixes → fix-only → show-fixes → show-source

4. Output settings: output-format → cache-dir

5. format.* keys

6. lint.* keys: select → extend-select → ignore → extend-ignore → per-file-ignores → fixable → unfixable → plugin configurations

Sorted arrays:

Arrays are sorted alphabetically using natural ordering (RUF1 < RUF9 < RUF10):

# These arrays are sorted:
lint.select = ["E", "F", "I", "RUF"]
lint.ignore = ["E501", "E701"]

# Per-file-ignores values are also sorted:
lint.per-file-ignores."tests/*.py" = ["D103", "S101"]

Sorted array keys:

Top-level:

exclude, extend-exclude, include, extend-include, builtins, namespace-packages, src

Format:

format.exclude

Lint:

select, extend-select, ignore, extend-ignore, fixable, extend-fixable, unfixable, extend-safe-fixes, extend-unsafe-fixes, external, task-tags, exclude, typing-modules, allowed-confusables, logger-objects

Per-file patterns:

lint.per-file-ignores.*, lint.extend-per-file-ignores.*

Plugin arrays:

lint.flake8-bandit.hardcoded-tmp-directory, lint.flake8-bandit.hardcoded-tmp-directory-extend, lint.flake8-boolean-trap.extend-allowed-calls, lint.flake8-bugbear.extend-immutable-calls, lint.flake8-builtins.builtins-ignorelist, lint.flake8-gettext.extend-function-names, lint.flake8-gettext.function-names, lint.flake8-import-conventions.banned-from, lint.flake8-pytest-style.raises-extend-require-match-for, lint.flake8-pytest-style.raises-require-match-for, lint.flake8-self.extend-ignore-names, lint.flake8-self.ignore-names, lint.flake8-tidy-imports.banned-module-level-imports, lint.flake8-type-checking.exempt-modules, lint.flake8-type-checking.runtime-evaluated-base-classes, lint.flake8-type-checking.runtime-evaluated-decorators, lint.isort.constants, lint.isort.default-section, lint.isort.extra-standard-library, lint.isort.forced-separate, lint.isort.no-lines-before, lint.isort.required-imports, lint.isort.single-line-exclusions, lint.isort.variables, lint.pep8-naming.classmethod-decorators, lint.pep8-naming.extend-ignore-names, lint.pep8-naming.ignore-names, lint.pep8-naming.staticmethod-decorators, lint.pydocstyle.ignore-decorators, lint.pydocstyle.property-decorators, lint.pyflakes.extend-generics, lint.pylint.allow-dunder-method-names, lint.pylint.allow-magic-value-types

[tool.pixi]

Key ordering:

Keys are grouped by functionality:

1. Workspace metadata: workspace.name → workspace.version → workspace.description → workspace.authors → workspace.license → workspace.license-file → workspace.readme → workspace.homepage → workspace.repository → workspace.documentation

2. Workspace configuration: workspace.channels → workspace.platforms → workspace.channel-priority → workspace.solve-strategy → workspace.conda-pypi-map → workspace.requires-pixi → workspace.exclude-newer → workspace.preview → workspace.build-variants → workspace.build-variants-files

3. Dependencies: dependencies → host-dependencies → build-dependencies → run-dependencies → constraints → pypi-dependencies → pypi-options

4. Development: dev

5. Environment setup: system-requirements → activation → tasks

6. Targeting: target → feature → environments

7. Package build: package

Sorted arrays:

workspace.channels, workspace.platforms, workspace.preview, workspace.build-variants-files

[tool.uv]

Key ordering:

Keys are grouped by functionality:

1. Version & Python: required-version → python-preference → python-downloads

2. Dependencies: dev-dependencies → default-groups → dependency-groups → constraint-dependencies → override-dependencies → exclude-dependencies → dependency-metadata

3. Sources & indexes: sources → index → index-url → extra-index-url → find-links → no-index → index-strategy → keyring-provider

4. Package handling: no-binary* → no-build* → no-sources* → reinstall* → upgrade*

5. Resolution: resolution → prerelease → fork-strategy → environments → required-environments → exclude-newer*

6. Build & Install: compile-bytecode → link-mode → config-settings* → extra-build-* → concurrent-builds → concurrent-downloads → concurrent-installs

7. Network & Security: allow-insecure-host → native-tls → offline → no-cache → cache-dir → http-proxy → https-proxy → no-proxy

8. Publishing: publish-url → check-url → trusted-publishing

9. Python management: python-install-mirror → pypy-install-mirror → python-downloads-json-url

10. Workspace & Project: managed → package → workspace → conflicts → cache-keys → build-backend

11. Other: pip → preview → torch-backend

Sorted arrays:

Package name arrays (sorted alphabetically):

constraint-dependencies, override-dependencies, dev-dependencies, exclude-dependencies, no-binary-package, no-build-package, no-build-isolation-package, no-sources-package, reinstall-package, upgrade-package

Other arrays:

environments, required-environments, allow-insecure-host, no-proxy, workspace.members, workspace.exclude

Sources table:

The sources table entries are sorted alphabetically by package name:

# Before
[tool.uv.sources]
zebra = { git = "..." }
alpha = { path = "..." }

# After
[tool.uv.sources]
alpha = { path = "..." }
zebra = { git = "..." }

pip subsection:

The [tool.uv.pip] subsection follows similar formatting rules, with arrays like extra, no-binary-package, no-build-package, reinstall-package, and upgrade-package sorted alphabetically.

[tool.coverage]

Key ordering:

Keys are reordered to follow coverage.py’s workflow phases:

1. Run phase (run.*): Data collection settings

   • Source selection: source → source_pkgs → source_dirs

   • File filtering: include → omit

   • Measurement: branch → cover_pylib → timid

   • Execution context: command_line → concurrency → context → dynamic_context

   • Data management: data_file → parallel → relative_files

   • Extensions: plugins

   • Debugging: debug → debug_file → disable_warnings

   • Other: core → patch → sigterm

2. Paths (paths.*): Path mapping between source locations

3. Report phase (report.*): General reporting

   • Thresholds: fail_under → precision

   • File filtering: include → omit → include_namespace_packages

   • Line exclusion: exclude_lines → exclude_also

   • Partial branches: partial_branches → partial_also

   • Output control: skip_covered → skip_empty → show_missing

   • Formatting: format → sort

   • Error handling: ignore_errors

4. Output formats (after report):

   • html.*: directory → title → extra_css → show_contexts → skip_covered → skip_empty

   • json.*: output → pretty_print → show_contexts

   • lcov.*: output → line_checksums

   • xml.*: output → package_depth

Grouping principle:

Related options are grouped together:

• File selection: include/omit are adjacent

• Exclusion patterns: exclude_lines/exclude_also are adjacent

• Partial branches: partial_branches/partial_also are adjacent

• Skip options: skip_covered/skip_empty are adjacent

Sorted arrays:

Run phase:

source, source_pkgs, source_dirs, include, omit, concurrency, plugins, debug, disable_warnings

Report phase:

include, omit, exclude_lines, exclude_also, partial_branches, partial_also

# Before (alphabetical)
[tool.coverage]
report.exclude_also = ["if TYPE_CHECKING:"]
report.omit = ["tests/*"]
run.branch = true
run.omit = ["tests/*"]

# After (workflow order with groupings)
[tool.coverage]
run.branch = true
run.omit = ["tests/*"]
report.omit = ["tests/*"]
report.exclude_also = ["if TYPE_CHECKING:"]

Other Tables

Any unrecognized tables are preserved and reordered according to standard table ordering rules. Keys within unknown tables are not reordered or normalized.