flake8-pyproject

library1.2.4pypypiunverified

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.

testing

pip install Flake8-pyproject

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · FLAKE8-PYPROJECT

flake8-pyproject

testingpythonv1.2.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

flake8p --version

Debug

Known issues

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

affects: <1.0.0, >=1.0.0

gotchaThe `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`.

affects: All versions

gotchaThe `[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']`.

affects: All versions

gotchaFor 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+.

affects: <1.0.1

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

affects: >=1.2.3

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

affects: All versions

Errors

Common errors & fixes

flake8 not loading pyproject.toml configuration

The `pyproject.toml` file's Flake8 configuration might be incorrectly placed, formatted, or `flake8-pyproject` may not be properly recognized by Flake8, leading to the configuration being ignored.

fix

Ensure your Flake8 configuration is under the `[tool.flake8]` section in `pyproject.toml` and formatted correctly. Verify `flake8-pyproject` is installed in the same environment as `flake8` and run `flake8` directly (or `flake8p`). If the `pyproject.toml` is not in the current directory, use `flake8 --toml-config /path/to/pyproject.toml`.

pflake8: command not found

The `pflake8` executable, provided by `flake8-pyproject`, is not located in any directory listed in your system's PATH environment variable, or the package installation was incomplete.

fix

Ensure that the directory containing Python scripts for your environment (e.g., `.venv/bin` on Linux/macOS or `Scripts` in a virtual environment on Windows) is added to your system's PATH. You may need to reinstall `flake8-pyproject` or activate your virtual environment.

flake8 per-file-ignores in pyproject.toml not working

Configuration options that expect a list (like `per-file-ignores` or `ignore`) are defined using a comma-separated string, but `flake8-pyproject` requires them to be specified as a TOML array in `pyproject.toml`.

fix

Change the format of list-based configuration options in `pyproject.toml` from a comma-separated string to a TOML array. For example, `per-file-ignores = ['__init__.py:F401', 'setup.py:E402']` instead of `per-file-ignores = '__init__.py:F401,setup.py:E402'`.

Upgrade

Version history

1.2.4latest on PyPI · released Nov 28, 2025

Audit

Dependencies

flake8requiredThis is a plugin for Flake8 and requires Flake8 to function. Specific versions of Flake8-pyproject are compatible with specific major versions of Flake8.

tomlioptionalRequired for parsing TOML files on Python versions older than 3.11. Python 3.11+ uses the built-in `tomllib` module.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/john-hen/Flake8-pyproject ↗

packagehttps://pypi.org/project/flake8-pyproject/ ↗

changeloghttps://github.com/john-hen/Flake8-pyproject/releases ↗