flake8: installing and using a Python code checker

Python

Flake8 inspects Python source without running it, reporting style issues and potential mistakes such as unused imports. Install it in your project environment, run python -m flake8 filename.py, and use the reported locations and diagnostic codes to make corrections. It does not validate every PEP or automatically rewrite your code.

What Flake8 checks, and what PEP means

PEP means Python Enhancement Proposal: a document describing a proposed feature, process, or design. Within the PEP document system, PEP 8 specifically describes Python code style. Checking style therefore does not mean validating compliance with every Python proposal.

Flake8 combines pycodestyle style checks, Pyflakes static analysis, and mccabe complexity checking. Complexity checking requires a threshold such as --max-complexity. E and W diagnostics mainly concern style; F diagnostics come from Pyflakes. Installed plugins can add checks and codes. Flake8 does not replace a type checker or a test runner.

Install in an isolated project environment

Open a new practice folder in Windows PowerShell. These commands require Python and the Windows py launcher. If your project already has a virtual environment with this name, select its interpreter instead of creating it again. Using the environment's executable directly avoids changing PowerShell's activation-script execution policy.

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install "flake8==7.4.1"
.\.venv\Scripts\python.exe -m flake8 --version

Flake8 7.4.1 requires Python 3.10 or newer. The commands and diagnostics here were checked on Windows with Python 3.12.14 and Flake8 7.4.1. Pinning the version makes the example reproducible; check Python requirements and diagnostic changes when selecting another release. The final command prints Flake8 and component versions.

On macOS or Linux, create the environment with your available Python 3 and invoke pip and Flake8 with .venv/bin/python, rather than copying the Windows executable path. Module invocation helps ensure that installation and inspection use the same Python environment.

Read diagnostic locations and codes

Create bad.py in the project folder with the complete code below, including a newline after the final line. Running it with the environment's Python prints 1.

import os
value=1
print(value)

A program that runs successfully can still contain unnecessary code or style problems. Inspect the same file from the project folder:

.\.venv\Scripts\python.exe -m flake8 bad.py

bad.py:1:1: F401 'os' imported but unused
bad.py:2:6: E225 missing whitespace around operator

The format is file:line:column: code explanation. F401 identifies the unused os import on line 1. E225 identifies missing whitespace around the assignment operator at line 2, column 6. This inspection exits with code 1 because it found violations. Consult the Flake8 diagnostic reference and the relevant component's documentation to understand each cause.

Correct the file and inspect it again

Remove the unused import and add spaces around the assignment operator. Replace the entire contents of the existing bad.py with this code, keeping the final newline. Running it still prints 1:

value = 1
print(value)

Inspect the same file again. --count adds the number of violations to the output:

.\.venv\Scripts\python.exe -m flake8 --count bad.py

The corrected example has zero violations and exits with code 0. Without --count, a clean check normally prints no diagnostics. Flake8 does not perform these edits itself: save the corrections in your editor and rerun the check. Verify program output separately from lint results.

Save project rules in .flake8

Create .flake8 at the project root. This is INI configuration, not Python code. The limit of 88 below is an example project policy. Flake8's default maximum line length is 79; choosing 88 does not change PEP 8's default guidance.

[flake8]
max-line-length = 88
extend-exclude = .venv,build,dist

extend-exclude retains default exclusions while adding the environment and build-output directories. Check that the patterns do not accidentally hide source files you need to inspect. Explicitly select the configuration when checking the corrected file:

.\.venv\Scripts\python.exe -m flake8 --config .flake8 --count bad.py

This also reports zero violations. Replace the final bad.py with . to inspect the project; other files may produce diagnostics. The configuration documentation describes the [flake8] section in .flake8, setup.cfg, and tox.ini. Command-line settings take priority, so check arguments passed by your editor or continuous integration system.

Use exceptions carefully and preserve failure results

Before suppressing a diagnostic, decide whether the code is unnecessary or genuinely needs an exception to project policy. For an unavoidable single-line exception, document the reason and restrict suppression to the relevant code, for example # noqa: F401. ignore replaces the default ignore list, while extend-ignore adds to it; review the option semantics before choosing.

In continuous integration (CI), preserve a failing exit status. --exit-zero reports success even when violations exist, so it is unsuitable for enforcing a passing check. Record the Flake8 and plugin versions in project dependencies, and review changed rules when upgrading. A clean static check does not establish correct input handling, business logic, or runtime compatibility; run the program and relevant tests as well.

Python