Flake8-pyproject

1.2.4 · active · verified Fri Apr 10

Flake8-pyproject is a Flake8 plugin that enables Flake8 to load its configuration from `pyproject.toml` files, a feature not natively supported by Flake8. It registers itself as a plugin, allowing the standard `flake8` command to seamlessly use `pyproject.toml` when present in the current directory. The library also provides an alternative `flake8p` command. It is currently at version 1.2.4 and receives updates primarily for Flake8 compatibility and new configuration options.

Warnings

breaking Flake8-pyproject versions have specific compatibility with Flake8 major versions. Version 1.0.0 dropped support for Flake8 4.x (requiring Flake8 5.0+), while earlier versions (e.g., 0.9.1) explicitly pinned to Flake8 4.x or earlier. Ensure your `flake8-pyproject` version matches your `flake8` installation.
Fix: Check the release notes for `Flake8-pyproject` to determine the compatible `flake8` version. Downgrade/upgrade `flake8-pyproject` or `flake8` accordingly (e.g., `pip install 'Flake8-pyproject<1.0.0'` for Flake8 4.x, or `pip install 'Flake8-pyproject>=1.0.0'` for Flake8 5.x+).
gotcha The `pyproject.toml` file containing the `[tool.flake8]` configuration must typically be located in the current working directory where `flake8` is executed. If it's in a different location or named differently, you must explicitly specify its path using the `--toml-config` command-line option.
Fix: Place `pyproject.toml` in the project root, or use `flake8 --toml-config /path/to/my_config.toml`.
gotcha The `[tool.flake8]` section within `pyproject.toml` must adhere to TOML's syntax for arrays and dictionaries (e.g., `ignore = ["E203", "W503"]`, `per-file-ignores = ["__init__.py:F401"]`). This differs from the INI format used in `.flake8` or `setup.cfg`.
Fix: Convert INI-style lists and comma-separated values to TOML arrays and lists, respectively. Example: `ignore = E231, E241` becomes `ignore = ['E231', 'E241']`.
gotcha For Python versions older than 3.11, the `tomli` package is a required dependency for parsing TOML files. Python 3.11 and later include `tomllib` in the standard library, making `tomli` unnecessary.
Fix: Ensure `tomli` is installed for Python < 3.11. No action needed for Python 3.11+.
gotcha As of version 1.2.3, the plugin specifically parses command-line arguments as passed down from Flake8 and explicitly ignores arguments other than `--toml-config`. This change might affect custom integrations or scripts that rely on specific command-line argument handling by `flake8-pyproject`.
Fix: Review any custom scripts or tools that call `flake8` with `flake8-pyproject` installed and ensure they only pass `--toml-config` for custom `pyproject.toml` paths, or other arguments directly handled by Flake8 itself.
gotcha Flake8-pyproject works by 'monkey-patching' Flake8 and Python's `configparser` library. This approach, while effective, means the plugin's stability can be sensitive to significant restructuring in future versions of Python or Flake8.
Fix: Be aware that major updates to Flake8 or Python might require corresponding updates to `flake8-pyproject` for continued compatibility.

Install

pip install Flake8-pyproject Install stable version
pip install flake8 'Flake8-pyproject<1.0.0' # For Flake8 4.x pip install flake8 'Flake8-pyproject>=1.0.0' # For Flake8 5.x and later Install with specific Flake8 compatibility

Quickstart

This quickstart demonstrates how to install `flake8-pyproject`, configure Flake8 via `pyproject.toml`, and then run the `flake8` command to apply those configurations. The `flake8` command will automatically pick up the `[tool.flake8]` section from your `pyproject.toml`.

mkdir my_project
cd my_project
pip install flake8 Flake8-pyproject

# Create pyproject.toml
cat <<EOF > pyproject.toml
[tool.flake8]
ignore = ["E203", "W503"]
max-line-length = 88
per-file-ignores = [
    "__init__.py:F401",
]
EOF

# Create a Python file with a linter error
cat <<EOF > my_module.py
import os

def my_func (  arg1, arg2 ):
    return arg1 + arg2

EOF

# Run flake8 (will use pyproject.toml config)
flake8 my_module.py

# Alternatively, use the provided flake8p command
# flake8p my_module.py

view raw JSON →