flake8: a wrapper for pycodestyle, pyflakes and mccabe

What flake8 glues together, and who ends up using it

flake8 is a wrapper. The README lists exactly three tools it runs: PyFlakes, pycodestyle, and Ned Batchelder's McCabe script. It launches all of them through the single flake8 command and prints the warnings in a per-file, merged output. That is the whole product idea: instead of wiring three separate executables into a CI pipeline and reconciling three output formats, you get one exit code and one list of findings sorted by file.

The audience follows from that. Teams that already run pycodestyle for PEP 8 spacing and pyflakes for unused imports and undefined names can replace two invocations with one. Projects that want a complexity ceiling get mccabe in the same pass. The README also mentions Git and Mercurial hooks, so the intended workflow includes running the check before a commit rather than only in CI.

What flake8 is not, based on the README, is a formatter. Nothing in the description says it rewrites or fixes code. It reports. If you want the file changed, that is a separate tool.

How the merged output and noqa suppression actually work

The mechanism is a dispatcher. flake8 loads the three bundled checkers plus anything registered through the flake8.extension and flake8.formatting entry points, runs them over each file, and merges the results into one per-file listing. The plugin system is the reason flake8 outlived any single checker: a plugin author publishes a package that declares an entry point, and flake8 picks it up without changes to the core.

Suppression is line-oriented and documented in the README. A file containing the line `# flake8: noqa` is skipped entirely. A `# noqa` comment at the end of a line suppresses warnings for that line. You can narrow it with `# noqa: E234`, and multiple codes can be given separated by commas. The README states the noqa token is case insensitive and that the colon before the list of codes is required; without the colon, the part after noqa is ignored. That last detail matters: a typo silently turns a targeted suppression into a blanket one.

Because output is merged, error codes are the only way to tell which checker spoke. The prefix tells you the family, and the README's own example uses E234, an E-series pycodestyle code. Flake8 itself does not renumber anything, so the codes you see are the codes the underlying tool produced.

Installing flake8 and running it on a real file

The README does not contain install commands. It points at the quickstart documentation instead, at https://flake8.pycqa.org/en/latest/index.html#quickstart, and says that page covers how to install and get started. So the honest first step is to open that page and follow the command it gives for your environment rather than copying a command from this article. What the repository does confirm is the shape of the tool: one executable named flake8, installed from the PyCQA/flake8 project, with a src/ layout and packaging driven by setup.py and setup.cfg.

Once flake8 is on your path, the invocation is a single command over a path. The README gives no flags, so what follows is the bare form the README describes, with the path replaced by your own source directory:

flake8

What you should see is a per-file, merged list of warnings, grouped by filename, each line carrying a code such as E234. Exit status is what CI reads, so a non-empty report is a failing run.

Suppression goes in the source, not in the command. A file that should be skipped entirely starts with this line, which the README shows verbatim:

# flake8: noqa

For a single line, the README's form is a trailing comment with an optional code list:

# noqa: E234

The colon is required. A noqa comment without it is treated as a plain noqa and suppresses everything on that line, which is usually not what the author intended.

Where flake8 stops: reporting, config sprawl and the missing quickstart

The first limitation is structural. flake8 reports problems; it does not repair them. A codebase with thousands of pycodestyle findings stays broken until someone edits the files or runs a different tool. That is a deliberate division of labour, but it means flake8 alone is not a migration path for a legacy repository.

The second is documentation placement. The README is short by design and delegates installation and getting started to https://flake8.pycqa.org/en/latest/index.html#quickstart, and it delegates common questions to an FAQ at https://flake8.pycqa.org/en/latest/faq.html. It does not document configuration filenames, per-checker behaviour, or how plugin versions interact. If you are evaluating flake8 from the repository alone, you cannot tell from the README where a config file should live or which keys it accepts.

Third, the plugin surface is a double-edged feature. Because flake8 loads anything registered under flake8.extension, two environments with the same flake8 version can produce different output if their plugin sets differ. The README does not describe a lockfile or a compatibility policy for plugins, so pinning is on you.

Finally, the licence. The repository reports NOASSERTION for the licence field, and a LICENSE file sits at the top level. NOASSERTION means the tooling could not classify it automatically. Read the LICENSE file itself before you rely on any particular permission; this article cannot tell you what it grants.

flake8 versus Ruff, Pylint and Black

The search data around this project is dominated by comparisons, and the differences are real rather than cosmetic.

Ruff is a linter written in Rust that reimplements a large set of flake8 rules natively. The practical difference is architecture: flake8 is a Python wrapper that imports and runs separate checker packages, while Ruff is a single binary with the rules built in. That makes flake8 the more extensible of the two through third-party entry points, and Ruff the one that does not need a Python environment per plugin. If your rule set is stock pycodestyle plus pyflakes, the choice is mostly about whether you value the plugin ecosystem.

Pylint takes a different route again. It is a single checker that builds a fuller model of the program and reports on things like design and duplication, rather than gluing independent tools together. Pylint's findings and flake8's findings overlap but do not match, which is why the two are often run side by side instead of one replacing the other.

Black is not a competitor at all. It is a formatter: it rewrites files into one canonical style. flake8 checks style and reports. Running Black and then flake8 is a common pairing precisely because they do different jobs, and the search phrase flake8 vs black reflects people discovering that they are not substitutes.

Maintenance, upgrade cost and the licence question

The repository is not archived, and the last push was on 2026-09-23. The README names two current maintainers: Anthony Sottile and Ian Cordasco, with the project originally created by Tarek Ziadé. That is a two-person maintenance model, which is worth weighing if flake8 sits in a critical CI path.

Upgrade cost is dominated by plugins, not by flake8 itself. Because checkers arrive through entry points, a flake8 bump can change which plugin versions resolve, and therefore which codes appear. The repository layout includes dev-requirements.txt and tox.ini, which suggests the project's own test matrix is pinned, but the README does not publish a compatibility table for downstream plugins. Pin both flake8 and your plugin set in your own requirements, and re-run the check after any bump to see what changed.

The licence field reads NOASSERTION. That is not a licence; it is the absence of a machine-readable classification. A LICENSE file is present at the top level of the repository. Whether you can vendor flake8, ship it in a container image, or bundle it into a product depends on what that file says, and that is a question for your own review, not something the README answers.

Editorial conclusion

Adopt flake8 if you want one command that merges pycodestyle, pyflakes and mccabe output, and you accept that the README hands installation and configuration to the documentation site rather than spelling them out. Skip it if you need formatter-grade rewriting, since flake8 only reports; the README says nothing about fixing code. Before committing, verify the exact install and invocation steps against https://flake8.pycqa.org/en/latest/index.html#quickstart, confirm which plugin versions your pins resolve to, and check whether your existing config lives in setup.cfg, tox.ini or .flake8, because the repository does not document every accepted filename.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. PyCQA/flake8 on GitHub
4. README