{"id":5415,"library":"pyproject-fmt","title":"pyproject-fmt","description":"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.","status":"active","version":"2.21.1","language":"en","source_language":"en","source_url":"https://github.com/tox-dev/toml-fmt/tree/main/pyproject-fmt","tags":["formatter","pyproject.toml","toml","linting","tool"],"install":[{"cmd":"pip install pyproject-fmt","lang":"bash","label":"Standard pip installation (isolated environments like uv or pipx are recommended)"},{"cmd":"uv tool install pyproject-fmt","lang":"bash","label":"Recommended installation with uv"},{"cmd":"pipx install pyproject-fmt","lang":"bash","label":"Recommended installation with pipx"}],"dependencies":[{"reason":"Required runtime environment.","package":"Python","version":">=3.10"}],"imports":[{"symbol":"run","correct":"from pyproject_fmt import run"}],"quickstart":{"code":"import os\nfrom pyproject_fmt import run\n\n# Assuming a pyproject.toml file exists in the current directory for testing\n# Create a dummy pyproject.toml for demonstration if it doesn't exist\nif not os.path.exists('pyproject.toml'):\n    with open('pyproject.toml', 'w') as f:\n        f.write('[project]\\nname = \"my-package\"\\nversion = \"0.1.0\"\\nrequires-python = \">=3.10\"\\ndependencies = [\"requests\"]\\n')\n\n# Format a pyproject.toml file and return the exit code\n# The 'run' function accepts command-line arguments as a list.\n# Pass an empty list or specific file paths.\nexit_code = run([\"pyproject.toml\"])\n\nif exit_code == 0:\n    print(\"pyproject.toml formatted successfully.\")\nelse:\n    print(f\"Formatting failed with exit code: {exit_code}\")\n\n# Clean up the dummy file\nif os.path.exists('pyproject.toml'):\n    os.remove('pyproject.toml')\n","lang":"python","description":"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."},"warnings":[{"fix":"Embrace the opinionated formatting or use pre-commit hooks to automate formatting without manual intervention. Understand that configuration choices are deliberately limited.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Prefer `uv tool install pyproject-fmt` or `pipx install pyproject-fmt` for managing the tool.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review the project's documentation on 'Table Organization' to understand the enforced structure. Allow the formatter to apply its intended order.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}