pyflakes

Check a single Python file

$ pyflakes check [path/to/file.py]

$ pyflakes checkPath [path/to/directory]

$ pyflakes checkRecursive [path/to/directory]

$ pyflakes iterSourceCode [path/to/directory_1] [path/to/directory_2]

pyflakes [options] file_or_directory [file_or_directory ...]

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

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

-j N, --jobs=N
    Run pyflakes in parallel using N jobs. Set to 0 to use the number of CPU cores.

--exclude=patterns
    Comma-separated list of file/directory patterns to exclude from checking. Supports standard Unix shell glob matching.

--builtins=names
    Comma-separated list of names that are globally assumed to be defined (e.g., by your framework).

--disable-msg=codes
    Comma-separated list of error codes to disable (e.g., F401 for unused imports). Each code starts with 'F'.

--enable-msg=codes
    Comma-separated list of error codes to enable (overrides --disable-msg for these codes). Useful for specific scenarios.

--diff
    Only check files that have uncommitted changes in the current Git repository.

--include-dir=directories
    Comma-separated list of directories to include for checking, in addition to explicitly provided paths. Useful when using --diff.

pyflakes is a simple and fast static analysis tool for Python programs. Unlike more comprehensive linters such as Pylint, pyflakes focuses exclusively on detecting programming errors like unused imports, undefined names, and unassigned variables, rather than enforcing style conventions (PEP 8) or code complexity metrics. It works by parsing Python source code into an Abstract Syntax Tree (AST) and then performing a quick traversal to identify common logical errors without executing the code. This approach makes pyflakes exceptionally fast and produces very few false positives, making it an excellent first line of defense for catching basic but crucial mistakes in Python codebases. It is often used as a core component within other larger linting frameworks, most notably Flake8.

pyflakes focuses solely on detecting errors and does not enforce code style (e.g., PEP 8). For style checking, tools like pycodestyle or black are needed. It also does not perform type checking; for that, consider tools like mypy. While generally accurate, in highly dynamic Python codebases (e.g., heavy use of `setattr`/`getattr` or runtime code generation), pyflakes might occasionally produce false positives due to its static analysis nature.

pyflakes reports errors using specific codes, typically prefixed with 'F' (e.g., F401 for unused imports, F821 for undefined names). These codes allow users to selectively enable or disable certain checks using the --disable-msg or --enable-msg options, providing fine-grained control over the analysis output.

While pyflakes can be run as a standalone command, it is most commonly used as a plugin for Flake8. Flake8 acts as a wrapper that runs pyflakes, pycodestyle (formerly pep8), and McCabe (a complexity checker) together, providing a more holistic linting solution. This integration simplifies the command-line usage and allows developers to manage all their code quality checks from a single tool.

pyflakes originated from the Divmod projects, specifically as a component of their Nevow web framework, developed around 2007. Its primary goal was to provide a very fast and lightweight static analysis tool to catch common programming errors without the overhead of more complex linters. It was designed to be easily integrated into development workflows and continuous integration systems due to its speed and low false-positive rate. Over time, it gained significant traction and became a standalone project, widely adopted within the Python community. Its design philosophy of focusing solely on errors (and not style) made it an ideal base for more comprehensive linting tools, leading to its popular integration into Flake8, which combines pyflakes with pycodestyle (for PEP 8 style checking) and a cyclomatic complexity checker.

flake8(1), pylint(1), mypy(1), pycodestyle(1)