Formatting Rules¶

This reference separates file-wide rules from the key order and array policy for recognized tables. See the configuration reference for available settings.

General Formatting¶

These rules cover the complete pyproject.toml file.

Table Ordering¶

The formatter writes tables in this order:

[build-system]
[project]
[dependency-groups]
[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, yapf, djlint, ruff, isort, flake8, pycln, nbqa, pylint, repo-review, codespell, docformatter, pydoclint, interrogate, tomlsort, check-manifest, check-sdist, check-wheel-contents, deptry, vulture, 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, commitizen, jupyter-releaser, semantic_release, tbump, towncrier, vendoring
8. Any other tool.* in alphabetical order
Other tables, alphabetically

String Quotes¶

Strings use double quotes unless the value contains one:

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

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

Key Quotes¶

The formatter removes quotes from bare keys containing A-Za-z0-9_-. Keys that need quotes use escaped double quotes. The rule covers headers, assignments, and inline tables:

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

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

Conversion escapes backslashes and double quotes in literal keys:

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

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

Array Formatting¶

Short arrays stay on one line:

# Before
keywords = ["python", "toml"]

# After
keywords = [ "python", "toml" ]

An array that exceeds column_width expands and gains a trailing comma:

# Before
[project]
keywords = ["web", "toml", "pyproject", "formatting"]

# After
[project]
keywords = [
  "formatting",
  "pyproject",
  "toml",
  "web",
]

A trailing comma retains multiline form at any width:

# Before
classifiers = ["Development Status :: 4 - Beta",]

# After
classifiers = [
  "Development Status :: 4 - Beta",
]

A member comment also retains multiline form:

lint.ignore = [
  "E501", # too long
  "E701",
]

An array uses multiline form when it has a trailing comma, exceeds column_width, or contains a member comment.

String Wrapping¶

The formatter wraps a string that pushes its line past column_width. Continuations account for the key or nested indent. A key wider than the limit keeps its value on one line because wrapping cannot shorten that prefix.

# Before
description = "Format your pyproject.toml file in place"

# After
description = """\
  Format your pyproject.toml file in \
  place\
  """

Wrapping prefers spaces and " :: " separators. It skips inline-table strings and strings containing newlines. skip_wrap_for_keys excludes selected paths.

Table Formatting¶

table_format selects a child-table shape.

Short form uses dotted keys:

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

Long form uses headers:

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

Child headers follow the same rank as their dotted keys. Unlisted children follow alphabetically, so [tool.coverage.run] precedes [tool.coverage.report] in long form just as run.* precedes report.* in short form:

# Before
[tool.coverage.report]
skip_covered = true

[tool.coverage.run]
branch = true

# After
[tool.coverage.run]
branch = true
[tool.coverage.report]
skip_covered = true

Root groups have one blank line between them. Child tables stay adjacent unless sub_table_spacing adds a gap:

# Before
[tool.ruff]
line-length = 120

[tool.ruff.lint]
select = ["E", "W"]

# After
[tool.ruff]
line-length = 120

[tool.ruff.lint]
select = [ "E", "W" ]

See the configuration reference for table overrides and spacing.

Array of Tables¶

Short form folds an array of tables when each entry fits within column_width:

# 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 one entry exceeds the limit, [[...]] headers remain because TOML 1.0 inline tables cannot span lines.

Comment Preservation¶

Comments move with the value or entry they describe. Within an array, trailing comments align against that array’s longest value:

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

# After
lint.ignore = [
  "COM812", # Conflict with formatter
  "CPY",    # No copyright statements
  "ISC001", # Another rule
]

Disabled Keys¶

A comment containing one valid assignment, such as # default = true, represents a disabled field. The formatter temporarily enables the assignment, formats it with its table, and restores the comment marker. This keeps the field beside its active peers:

# Before
[[tool.uv.index]]
name = "pypi"
authenticate = "never"
# default = true
# ignore-error-codes = [400,401,403]

# After
[[tool.uv.index]]
name = "pypi"
authenticate = "never"
# default = true
# ignore-error-codes = [ 400, 401, 403 ]

Prose, multiline blocks, and commented headers remain ordinary comments. The check is structural: prose that parses as one assignment receives disabled-field formatting. Rephrase such prose to avoid that interpretation. An assignment wider than column_width also remains an ordinary comment.

Group Markers¶

An isolated # Group: comment divides an array, table, or section list into independent sort ranges. Group order and the marker position stay fixed. Matching ignores case; trailing comments do not create boundaries.

The formatter sorts the entries inside each group:

# Before
[project]
dependencies = [
  # Group: web
  "flask",
  "django",
  # Group: db
  "sqlalchemy",
  "psycopg2",
]

# After
[project]
dependencies = [
  # Group: web
  "django",
  "flask",
  # Group: db
  "psycopg2",
  "sqlalchemy",
]

The same marker can precede a table key or [tool.*] header.

Line Endings¶

Output retains the input’s line ending. Mixed files use the more frequent ending, with ties resolved to \n. Stdout uses \n.

Table-Specific Handling¶

Recognized tables add the rules below.

`[build-system]`¶

The PEP 517 / PEP 518 table declares the project’s build process. See the packaging specification.

Keys follow build-backend → requires → backend-path. requires receives normalized spelling and package-name order.

`[project]`¶

The PEP 621 core metadata table. See the packaging specification.

Keys follow the canonical metadata order. The formatter normalizes the name, dependency arrays, classifiers, and keywords, and validates the version.

Formatting details

Key ordering: 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
version: Kept verbatim, because it is the exact version published in the package metadata, and normalizing would rewrite for example, CalVer 2026.08.10 to 2026.8.10. The formatter rejects values outside PEP 440, reports the error, and leaves the file untouched.
description: Whitespace normalized: multiple spaces collapsed, consistent spacing after periods.
license: Uppercases license expression operators (and, or, with): MIT or Apache-2.0 → MIT OR Apache-2.0. The formatter rewrites a value after it parses as an SPDX expression over registered license and exception identifiers, so free-form text that happens to read like one (MIT or later) retains its input spelling.
requires-python: Whitespace removed: >= 3.9 → >=3.9
keywords: Deduplicated (case-insensitive) and sorted alphabetically.
dynamic: Sorted alphabetically.
import-names / import-namespaces: Uses PEP 794 spelling: a dotted name of Python identifiers followed by its optional modifier (pkg.sub ;private → pkg.sub; private). Valid entries sort alphabetically; other values retain their input spelling.
classifiers: Deduplicated and sorted alphabetically.
authors / maintainers: Retain published order. Each entry uses name → email key order.

Dependency normalization: dependency arrays use PEP 508 spelling and canonical package-name order. The formatter removes spaces and redundant .0 suffixes unless keep_full_version = true:

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

# After
[project]
dependencies = [ "click~=8.0", "requests>=2" ]

A direct-reference dependency keeps a space before its marker separator, because PEP 508 only ends the URL at whitespace; without it, installers read the ; and the marker as part of the URL and reject the entry:

# Before
[project]
dependencies = ["pkg @ git+https://github.com/user/repo.git@main ; python_version>='3.10'"]

# After
[project]
dependencies = [ "pkg @ git+https://github.com/user/repo.git@main ; python_version>='3.10'" ]

Optional-dependency extra names use lowercase with hyphens:

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

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

Python version classifiers derive from requires-python and max_supported_python (here 3.15). Disable generation with generate_python_version_classifiers = false:

# Before
[project]
requires-python = ">=3.10"

# After
[project]
requires-python = ">=3.10"
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",
  "Programming Language :: Python :: 3.15",
]

Entry points: inline tables within entry-points expand to dotted keys:

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

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

Authors / maintainers can be inline tables (short format):

# Before
[project]
authors = [{ name = "Alice", email = "alice@example.com" }]

# After
[project]
authors = [ { name = "Alice", email = "alice@example.com" } ]

or an expanded array of tables (long format, controlled by table_format, expand_tables, and collapse_tables):

[[project.authors]]
name = "Alice"
email = "alice@example.com"

`[dependency-groups]`¶

The PEP 735 table for named groups of development dependencies. See the packaging specification.

Groups follow dev → test → type → docs → other names alphabetically. Each group receives normalized dependency spelling and package-name order.

`[tool.poetry]`¶

Poetry is a Python dependency management and packaging tool. See its pyproject.toml reference.

Covers Poetry 1.x metadata under [tool.poetry] and Poetry 2.x tool-specific keys. Sections and inline tables follow Poetry’s documented order. Set-like arrays sort; sequence-dependent arrays retain input order.

Formatting details

Top-level key ordering:

Identity: name → version → description → package-mode
License & authorship: license → authors → maintainers
Documentation: readme → homepage → repository → documentation
Discovery: keywords → classifiers
Packaging contents: packages → include → exclude → build
Dependencies (sub-tables): dependencies → dev-dependencies → group → extras
Entry points / distribution: scripts → plugins → urls → source
Poetry runtime constraints: requires-poetry → requires-plugins → build-constraints

Sub-table key ordering:

[tool.poetry.dependencies] / [tool.poetry.dev-dependencies] / per-group dependencies: python first (interpreter constraint), all other package names alphabetized.
[tool.poetry.group.<name>]: optional → include-groups → dependencies.
[tool.poetry.extras], [tool.poetry.scripts], [tool.poetry.urls], [tool.poetry.plugins.*], [tool.poetry.requires-plugins], [tool.poetry.build-constraints]: Keys alphabetized.
[tool.poetry.build]: script → generate-setup-file.
[[tool.poetry.source]]: Each entry’s keys ordered name → url → priority → links → indexed, with the deprecated default and secondary last. Entries retain priority order.

Sorted arrays:

keywords, classifiers: deduplicated (case-insensitive) and sorted alphabetically.
exclude: sorted alphabetically.
[tool.poetry.extras] values (each extras.<name>): sorted alphabetically.
[tool.poetry.group.<name>.include-groups]: sorted alphabetically.
Per-dependency extras arrays (in dependencies, dev-dependencies, per-group dependencies, requires-plugins, build-constraints): sorted alphabetically.

Preserved order: authors, maintainers, packages, include, readme (when an array), multi-constraint dependency arrays, and [[tool.poetry.source]] entries.

Inline-table key ordering: Poetry discriminator keys select one of these orders:

Sources ({ priority = ... }, { secondary = ... }, { links = ... }, { indexed = ... }): name → url → priority → links → indexed → default → secondary.
Git dependencies ({ git = ... }): git → branch → tag → rev → subdirectory → python → platform → markers → allow-prereleases → allows-prereleases → optional → extras → develop.
Path dependencies ({ path = ... }): path → develop → subdirectory → python → platform → markers → optional → extras.
File dependencies ({ file = ... }): file → subdirectory → python → platform → markers → optional → extras.

Inline tables outside these schemas, such as { name = "...", email = "..." }, retain their input order.

# Before
[[tool.poetry.source]]
priority = "primary"
url = "https://example.com"
name = "private"

[tool.poetry.dependencies]
zebra = "^1.0"
python = "^3.11"
foo = { branch = "main", git = "https://example.com/foo" }

# After
[tool.poetry]
dependencies.python = "^3.11"
dependencies.foo = { git = "https://example.com/foo", branch = "main" }
dependencies.zebra = "^1.0"
source = [ { name = "private", url = "https://example.com", priority = "primary" } ]

`[tool.pdm.*]`¶

PDM is a modern Python package and dependency manager. See its build configuration reference.

Top-level keys follow distribution → resolution → version → build → scripts → source → dev-dependencies → publish → options. Name and glob arrays sort; source entries retain priority order.

`[tool.setuptools]` and `[tool.setuptools_scm]`¶

setuptools is a build backend and packaging library; setuptools_scm derives the package version from SCM tags. See the setuptools pyproject.toml reference and the setuptools_scm configuration reference.

Both tables group keys by discovery → data → metadata → deprecated. Name and glob arrays sort; literal lists such as packages retain input order.

Formatting details

[tool.setuptools] top-level key ordering (grouped):

Packaging discovery: py-modules → packages.find.* / packages.find-namespace.* → packages → package-dir
Package data: include-package-data → package-data → exclude-package-data
Dynamic metadata: dynamic
Extensions / build customization: ext-modules → cmdclass
Distribution metadata: platforms → provides → obsoletes → license-files
Data files: data-files
Deprecated / obsolete (pushed last): script-files → namespace-packages → zip-safe → eager-resources → dependency-links

[tool.setuptools.packages.find] / [tool.setuptools.packages.find-namespace] inner ordering: where → include → exclude → namespaces.

[tool.setuptools.package-data] / [tool.setuptools.exclude-package-data] / [tool.setuptools.data-files] ordering: the catch-all "*" pattern always goes first, then the other package patterns alphabetically; each value sorts alphabetically.

[tool.setuptools.dynamic] ordering: field names alphabetized. Inline-table directives (e.g. version = { attr = "pkg.__version__" } or readme = { file = "README.md", content-type = "text/markdown" }) get their keys ordered attr → file → content-type.

Sorted arrays:

py-modules, platforms, provides, obsoletes, namespace-packages, eager-resources: alphabetized.
packages.find.include / packages.find.exclude / packages.find-namespace.*: alphabetized.
Values inside package-data / exclude-package-data tables: alphabetized.

Preserved order: packages (literal list, first match wins), license-files (PEP 639 concatenation order), script-files and the data-files lists (installed in order, which decides which of two files sharing a name reaches the installation), and everything under [[tool.setuptools.ext-modules]] (compiler and linker argv arrays).

[tool.setuptools_scm] key ordering (grouped):

Version output: version_file → version_file_template
Version computation: version_scheme → local_scheme → version_cls → normalize
Root discovery: root → relative_to → fallback_root → parent → search_parent_directories → dist_name
Tag / parse: tag_regex → parse → parentdir_prefix_version → fallback_version
Nested SCM-specific tables: scm.git.pre_parse → scm.git.describe_command
Deprecated (pushed last): git_describe_command (use scm.git.describe_command) → write_to (use version_file) → write_to_template (use version_file_template) → version_class (use version_cls) → template

# Before
[tool.setuptools]
zip-safe = false
py-modules = ["foo", "bar"]

[tool.setuptools.packages.find]
namespaces = true
where = ["src"]
include = ["my_pkg*"]

[tool.setuptools.dynamic]
readme = { content-type = "text/markdown", file = "README.md" }

# After
[tool.setuptools]
py-modules = [ "bar", "foo" ]
packages.find.where = [ "src" ]
packages.find.include = [ "my_pkg*" ]
packages.find.namespaces = true
dynamic.readme = { file = "README.md", content-type = "text/markdown" }
zip-safe = false

`[tool.hatch.*]`¶

Hatch is a Python project manager based on the Hatchling build backend. See its build configuration reference.

Hatch tables group keys by version → metadata → build → publish → workspace → environments. Name and path arrays sort; build hooks and matrix entries retain input order.

`[tool.scikit-build]`¶

scikit-build-core is a CMake-based build backend for Python C/C++ extensions. See its configuration reference.

Keys follow meta → build → cmake → ninja → sdist → wheel → install → editable → logging → metadata → search → generate → overrides. Name and path lists sort; cmake and ninja arguments retain input order.

`[tool.maturin]`¶

Maturin builds and publishes Rust-based Python extension modules. See its configuration reference.

Keys follow module identity → source layout → cargo settings → compatibility/strip → behavior. Set-like arrays sort; cargo and rustc arguments retain input order.

`[tool.pixi]`¶

Pixi is a cross-platform conda/PyPI package and environment manager. See its pyproject.toml reference.

Keys follow workspace metadata → configuration → dependencies → environments → build. A platform array containing plain names sorts.

`[tool.uv]`¶

uv is Astral’s Python package and project manager. See its settings reference.

Keys follow Python → dependencies → sources → resolution → build → network → publishing → workspace. Package-name arrays and the sources table sort alphabetically.

`[tool.cibuildwheel]`¶

cibuildwheel builds Python wheels across platforms in CI. See its options reference.

Keys follow selection → build config → build phases → test phases → platform images → per-platform sub-tables → overrides. Set-like arrays sort; argument lists retain input order.

`[tool.autopep8]`¶

autopep8 formats Python code to conform to PEP 8. See its configuration reference.

Keys follow length/indent → mode → rules → behavior. Rule lists sort.

`[tool.black]`¶

Black is a Python code formatter. See its configuration reference.

Keys follow Black’s option groups. target-version and enable-unstable-feature sort alphabetically.

`[tool.yapf]`¶

YAPF is a configurable Python code formatter from Google. See its configuration reference.

A single flat table: based_on_style comes first (it sets the defaults), then the rest in a fixed order.

`[tool.djlint]`¶

djLint is a linter and formatter for HTML templates (Django, Jinja, and more). See its configuration reference.

Keys follow profile/scope → formatting → linting → ignores → output. Exclude and block lists sort.

`[tool.ruff]`¶

Ruff is a Python linter and formatter written in Rust. See its settings reference.

Keys follow Ruff’s option grouping (global → paths → behavior → output → format → lint); rule-code, path, and name arrays use natural order (RUF1 < RUF9 < RUF10).

Formatting details

Key ordering:

Global settings: required-version → extend → target-version → line-length → indent-width → tab-size
Path settings: builtins → namespace-packages → src → include → extend-include → exclude → extend-exclude → force-exclude → respect-gitignore
Behavior flags: preview → fix → unsafe-fixes → fix-only → show-fixes → show-source
Output settings: output-format → cache-dir
format.* keys
lint.* keys: select → extend-select → ignore → extend-ignore → per-file-ignores → fixable → unfixable → plugin configurations

Sorted arrays: alphabetical with natural ordering (RUF1 < RUF9 < RUF10); per-file-ignores values follow the same order:

# Before
[tool.ruff]
lint.select = ["F", "E", "RUF", "I"]
lint.ignore = ["E701", "E501"]
lint.per-file-ignores."tests/*.py" = ["S101", "D103"]

# After
[tool.ruff]
lint.select = [ "E", "F", "I", "RUF" ]
lint.ignore = [ "E501", "E701" ]
lint.per-file-ignores."tests/*.py" = [ "D103", "S101" ]

The full set of 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.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

Preserved order: lint.isort.forced-separate, whose list order controls auxiliary import blocks.

`[tool.isort]`¶

isort sorts and organizes Python imports. See its configuration options.

profile comes first (it sets the defaults everything else overrides), then output style, known sources, separation, skip patterns, and import edits. Name lists sort; sequence-dependent lists retain input order.

`[tool.pylint.*]`¶

Pylint is a static analyzer and linter for Python. See its configuration reference.

Sub-tables follow Pylint’s checker-group order. Rule, name, and path lists sort by leaf key, independent of sub-table.

`[tool.codespell]`¶

codespell checks code and text for common misspellings. See its configuration reference.

Keys follow dictionaries → scope → fix behavior → output. Word and path lists sort.

`[tool.docformatter]`¶

docformatter formats Python docstrings to follow PEP 257. See its configuration reference.

Keys follow behavior → format width → wrap/summary tweaks → other.

`[tool.interrogate]`¶

interrogate measures docstring coverage of a Python codebase. See its configuration reference.

Keys follow threshold → ignore flags → exclude → output. Exclude and regex lists sort.

`[tool.check-manifest]`¶

check-manifest checks that MANIFEST.in is complete for an sdist. See its configuration reference.

Keys follow ignore → ignore-bad-ideas → ignore-default-rules. Both glob lists sort.

`[tool.deptry]`¶

deptry finds unused, missing, and transitive dependencies in Python projects. See its usage reference.

Keys follow scope/exclude → ignore rules → per-rule ignores → behavior → mapping. Ignore and path lists sort.

`[tool.vulture]`¶

Vulture finds unused (dead) Python code. See its configuration reference.

Keys follow paths → ignore → behavior → output. Path and name lists sort.

`[tool.bandit]`¶

Bandit finds common security issues in Python code. See its configuration reference.

Keys follow exclude_dirs → targets → tests → skips → per-plugin sub-tables. Array values sort alphabetically.

`[tool.mypy]`¶

mypy is a static type checker for Python. See its configuration reference.

Covers mypy’s documented options and [[tool.mypy.overrides]]. Keys follow the mypy reference, set-like arrays sort, and plugins plus mypy_path retain input order.

Formatting details

Top-level key ordering (sectioned):

Import discovery: mypy_path → files → modules → packages → exclude → exclude_gitignore → namespace_packages → explicit_package_bases → ignore_missing_imports → follow_untyped_imports → follow_imports → follow_imports_for_stubs → python_executable → no_site_packages → no_silence_site_packages
Platform configuration: python_version → platform → always_true → always_false
Disallow dynamic typing: disallow_any_unimported → disallow_any_expr → disallow_any_decorated → disallow_any_explicit → disallow_any_generics → disallow_subclassing_any
Untyped definitions and calls: disallow_untyped_calls → untyped_calls_exclude → disallow_untyped_defs → disallow_incomplete_defs → check_untyped_defs → disallow_untyped_decorators
None and Optional: implicit_optional → strict_optional
Configuring warnings: warn_redundant_casts → warn_unused_ignores → warn_no_return → warn_return_any → warn_unreachable → deprecated_calls_exclude
Suppressing errors: ignore_errors
Miscellaneous strictness: allow_untyped_globals → allow_redefinition → local_partial_types → disable_error_code → enable_error_code → extra_checks → implicit_reexport → strict_equality → strict_bytes → strict
Configuring error messages: show_error_context → show_column_numbers → show_error_end → hide_error_codes → show_error_code_links → pretty → color_output → error_summary → show_absolute_path
Incremental mode: incremental → cache_dir → sqlite_cache → cache_fine_grained → skip_version_check → skip_cache_mtime_checks
Advanced options: plugins → pdb → show_traceback → raise_exceptions → custom_typing_module → custom_typeshed_dir → warn_incomplete_stub → native_parser
Report generation: any_exprs_report → cobertura_xml_report → html_report → linecount_report → linecoverage_report → lineprecision_report → txt_report → xml_report → xslt_html_report → xslt_txt_report
Miscellaneous: junit_xml → junit_format → scripts_are_modules → warn_unused_configs → verbosity
overrides last.

Overrides entry key ordering: in each [[tool.mypy.overrides]] entry, module comes first (required), then per-module overridable keys in the same logical grouping as the parent table (import behavior, platform markers, disallow dynamic typing, untyped defs/calls, optional handling, warnings, suppression, miscellaneous strictness).

Sorted arrays:

Top-level: files, modules, packages, exclude, always_true, always_false, untyped_calls_exclude, deprecated_calls_exclude, disable_error_code, enable_error_code.
Inside overrides entries: module (when an array of patterns), always_true, always_false, disable_error_code, enable_error_code.

Preserved order: plugins (run in declared order; reordering changes behavior) and mypy_path (a search path with priority semantics).

Inline-table handling: when [[tool.mypy.overrides]] collapses to overrides = [{...}, {...}] under the default table_format = "short", mypy-specific discriminators select each entry’s key order: disable_error_code / enable_error_code / ignore_missing_imports / follow_untyped_imports / ignore_errors / warn_unused_ignores / disallow_untyped_defs / check_untyped_defs. Arrays inside each entry sort in either table shape.

# Before
[[tool.mypy.overrides]]
disable_error_code = ["import-untyped", "attr-defined"]
module = "pkg.*"

# After
[tool.mypy]
overrides = [ { module = "pkg.*", disable_error_code = [ "attr-defined", "import-untyped" ] } ]

`[tool.pyrefly]`¶

Pyrefly is Meta’s Python type checker and language server, written in Rust. See its configuration reference.

Keys follow platform → paths → behavior → errors. Selection arrays sort; search paths retain input order.

`[tool.pyright]` and `[tool.basedpyright]`¶

Pyright is Microsoft’s Python type checker; basedpyright is a community fork sharing the same schema. See the pyright configuration reference and the basedpyright config-files reference.

Keys follow platform → mode flags → paths → strict-flavor toggles → defineConstant → alphabetical report* rules → executionEnvironments. Path arrays sort.

`[tool.ty]`¶

ty is Astral’s Python type checker, written in Rust. See its configuration reference.

Keys follow src → environment → rules → terminal → overrides. src.include sorts; src.exclude retains input order.

`[tool.pytest.ini_options]`¶

pytest is a testing framework for Python. See its configuration reference.

Keys in ini_options follow the pytest reference. Set-like arrays sort; addopts and pythonpath retain input order.

`[tool.coverage]`¶

coverage.py measures code coverage of Python programs. See its configuration reference.

Keys follow coverage.py’s workflow phases (run → paths → report → output formats) with related options kept adjacent; set-like arrays sort.

`[tool.tox]`¶

tox automates and standardizes testing across multiple Python environments. See its configuration reference.

A [tool.tox] block reuses the tox-toml-fmt rules applied to a standalone tox.toml.

`[tool.bumpversion]`¶

bump-my-version (the successor to bumpversion) updates version strings across files and tags releases. See its configuration reference.

Keys follow identity → format → tag → commit → behavior → files / parts.

`[tool.commitizen]`¶

Commitizen enforces conventional commits and automates version bumps and changelogs. See its configuration reference.

Keys follow rule selection → version source → bump behavior → tag/sign → changelog → hooks → customize.

`[tool.semantic_release]`¶

python-semantic-release automates versioning and releases from commit history. See its configuration reference.

Keys follow tag/version → assets → version source → repo → commit parser → branches → publish → changelog → remote. exclude_commit_patterns sorts; declaration lists retain input order.

`[tool.towncrier]`¶

towncrier builds release notes from news-fragment files. See its configuration reference.

Keys follow package identity → news location → rendering → behavior → type / section. The ignore list sorts; changelog entries retain display order.

`[tool.pyproject-fmt]`¶

The formatter’s own configuration table.

See the configuration reference for what each key controls.

Keys follow the documented configuration sequence. The expand_tables, collapse_tables, and skip_wrap_for_keys lists sort and drop duplicate strings.

Other Tables¶

Unrecognized tables take their standard table position. Their keys and values retain input order and spelling.

Formatting Rules¶

General Formatting¶

Table Ordering¶

String Quotes¶

Key Quotes¶

Array Formatting¶

String Wrapping¶

Table Formatting¶

Array of Tables¶

Comment Preservation¶

Disabled Keys¶

Group Markers¶

Line Endings¶

Table-Specific Handling¶

[build-system]¶

[project]¶

[dependency-groups]¶

[tool.poetry]¶

[tool.pdm.*]¶

[tool.setuptools] and [tool.setuptools_scm]¶

[tool.hatch.*]¶

[tool.scikit-build]¶

[tool.maturin]¶

[tool.pixi]¶

[tool.uv]¶

[tool.cibuildwheel]¶

[tool.autopep8]¶

[tool.black]¶

[tool.yapf]¶

[tool.djlint]¶

[tool.ruff]¶

[tool.isort]¶

[tool.pylint.*]¶

[tool.codespell]¶

[tool.docformatter]¶

[tool.interrogate]¶

[tool.check-manifest]¶

[tool.deptry]¶

[tool.vulture]¶

[tool.bandit]¶

[tool.mypy]¶

[tool.pyrefly]¶

[tool.pyright] and [tool.basedpyright]¶

[tool.ty]¶

[tool.pytest.ini_options]¶

[tool.coverage]¶

[tool.tox]¶

[tool.bumpversion]¶

[tool.commitizen]¶

[tool.semantic_release]¶

[tool.towncrier]¶

[tool.pyproject-fmt]¶

Other Tables¶

`[build-system]`¶

`[project]`¶

`[dependency-groups]`¶

`[tool.poetry]`¶

`[tool.pdm.*]`¶

`[tool.setuptools]` and `[tool.setuptools_scm]`¶

`[tool.hatch.*]`¶

`[tool.scikit-build]`¶

`[tool.maturin]`¶

`[tool.pixi]`¶

`[tool.uv]`¶

`[tool.cibuildwheel]`¶

`[tool.autopep8]`¶

`[tool.black]`¶

`[tool.yapf]`¶

`[tool.djlint]`¶

`[tool.ruff]`¶

`[tool.isort]`¶

`[tool.pylint.*]`¶

`[tool.codespell]`¶

`[tool.docformatter]`¶

`[tool.interrogate]`¶

`[tool.check-manifest]`¶

`[tool.deptry]`¶

`[tool.vulture]`¶

`[tool.bandit]`¶

`[tool.mypy]`¶

`[tool.pyrefly]`¶

`[tool.pyright]` and `[tool.basedpyright]`¶

`[tool.ty]`¶

`[tool.pytest.ini_options]`¶

`[tool.coverage]`¶

`[tool.tox]`¶

`[tool.bumpversion]`¶

`[tool.commitizen]`¶

`[tool.semantic_release]`¶

`[tool.towncrier]`¶

`[tool.pyproject-fmt]`¶