flake8

Lint a file or directory recursively

$ flake8 [path/to/file_or_directory]

$ flake8 --show-source [path/to/file_or_directory]

$ flake8 --ignore [rule1,rule2,...] [path/to/file_or_directory]

$ flake8 --exclude [substring1,glob2] [path/to/file_or_directory]

flake8 [options] [path ...]

-h, --help
    Show the help message and exit.

--version
    Show program's version number and exit.

--select=ERROR_CODES
    Enable specific error codes (e.g., E101,W202).

--ignore=ERROR_CODES
    Ignore specific error codes (e.g., E501,W292).

--exclude=GLOB_PATTERNS
    Exclude files or directories matching given patterns (e.g., *.pyc,docs/).

--max-line-length=N
    Set maximum allowed line length (default 79 for PEP 8).

--max-complexity=N
    Set maximum McCabe complexity for functions (default -1, no limit).

--show-source
    Display the source code line for each error.

--statistics
    Count occurrences of each error type.

--count
    Print total number of errors and warnings.

--format=FORMAT_STRING
    Specify the output format for reported errors.

--isolated
    Disable all plugins and configuration files for a clean run.

--config=PATH
    Specify an alternative path to a configuration file.

flake8 is a versatile command-line utility designed to enforce style guide (PEP 8), programming error, and code complexity checks in Python codebases. It acts as a wrapper around three core tools:

PyFlakes: A static analysis tool that detects common programming errors such as unused imports or undefined names, without executing the code.
pycodestyle (formerly pep8): Checks code against the official Python style guide, PEP 8, covering aspects like indentation, naming conventions, and line length.
McCabe: Analyzes code complexity, specifically focusing on the McCabe complexity metric for functions, which helps identify overly complex functions that might be hard to read and maintain.

flake8 aggregates the output from these tools into a single, unified report, making it an indispensable tool for maintaining high code quality and consistency across Python projects. It is highly configurable through command-line options and project-specific configuration files (e.g., setup.cfg, pyproject.toml, .flake8), and is commonly integrated into Continuous Integration (CI) pipelines and pre-commit hooks.

flake8 performs static analysis and does not execute code, so it cannot catch runtime errors. It may occasionally report false positives or flag code that is intentionally structured in a certain way; careful configuration via its ignore/exclude options or configuration files is essential. While highly effective, strict adherence to default PEP 8 rules can sometimes be overly rigid for specific project conventions, requiring customization. Performance on very large codebases can be improved by properly excluding irrelevant files and directories.

flake8 can be configured project-wide using files such as setup.cfg, pyproject.toml, or a dedicated .flake8 file. These files allow developers to define default settings, ignored errors, excluded paths, and other options, ensuring consistent code quality checks across a team without requiring repetitive command-line arguments.

One of flake8's powerful features is its extensibility through plugins. The Python community has developed numerous plugins (e.g., flake8-docstrings, flake8-bugbear, flake8-isort) that add specialized checks beyond the default capabilities of pyflakes, pycodestyle, and mccabe. This allows users to tailor flake8 to specific project needs or enforce additional coding standards.

flake8 was developed to address the need for a unified interface to several popular Python code quality tools: pyflakes, pep8 (now pycodestyle), and mccabe. Before flake8, developers often had to run these tools separately and parse their distinct outputs. By consolidating them, flake8 streamlined the process of identifying and fixing style and error issues, making code quality checks more accessible and efficient. Since its inception, it has become a de facto standard for code linting in the Python community, continuously evolving with ongoing development to support newer Python versions and integrate with the broader development ecosystem.

autopep8(1), black(1), isort(1), pylint(1), mypy(1)