# pycodestyle: a single-file PEP 8 checker, and what it will not do for you

> pycodestyle checks Python source against PEP 8 conventions, reports errors in a parseable format, and ships as one stdlib-only file. It reports style violations; it does not fix them, and it is not a full linter.

**PyCQA/pycodestyle** — Simple Python style checker in one Python file

- Repository: https://github.com/PyCQA/pycodestyle
- Website: https://pycodestyle.pycqa.org
- Stars: 5,169 · Forks: 756
- Language: Python
- License: NOASSERTION
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/pycqa-pycodestyle

## What pycodestyle checks, and the one thing it refuses to do

pycodestyle compares Python source against a subset of the conventions in PEP 8. It is a reporter, not a rewriter: the README describes it as "a tool to check your Python code against some of the style conventions in PEP 8", and no command in the documentation edits a file. The output is line-and-column oriented, which is the point. Each finding looks like optparse.py:69:11: E401 multiple imports on one line, so an editor or a CI log can jump straight to the location. The audience is narrow and clear: Python developers who want a mechanical check for whitespace, blank-line count, indentation and line length, and who want that check to run without pulling dependencies into their environment. The project was formerly called pep8 and was renamed to reduce confusion, a change the README traces to a request from Guido van Rossum and a PyCon 2016 lightning talk. If you are looking for a tool that also rewrites your imports or adds missing blank lines, you are looking at the wrong half of the toolchain.

## One file, stdlib only: the architecture that shapes everything else

The repository's top level contains pycodestyle.py alongside setup.py, setup.cfg, tox.ini, a Makefile, docs/, testing/ and tests/. The README states the design directly: "Small: Just one Python file, requires only stdlib. You can use just the pycodestyle.py file for this purpose." That single-file constraint is the reason the tool is easy to vendor into a build image or drop next to a script, and it is also the reason the feature set stops where it does. There is no plugin runtime to configure beyond the plugin entry points the README calls out ("Plugin architecture: Adding new checks is easy"), and the repository carries a .pre-commit-config.yaml, so the maintainers run it through pre-commit themselves. The check logic is table-driven: each error code corresponds to a pattern, and --show-pep8 prints the relevant PEP 8 text next to the finding. The trade-off is visible in the release history: the newest release listed is 1.7.1 from 2017-10-25, while the last push to the default branch was 2026-08-16. Code keeps moving; the version number does not. Treat the version string as a weak signal of what the tool can do.

## Installing pycodestyle with pip and reading your first report

The README gives the install, upgrade and uninstall commands. The published package name is pycodestyle, and a Debian/Ubuntu package also exists, though the README warns it "is not always the latest version".

```bash
pip install pycodestyle
```

To see findings on a file with the source line printed underneath each one, pass --show-source. The README's own example uses a file from the test data:

```bash
pycodestyle --show-source --show-pep8 testing/data/E40.py
```

The output pairs the finding with the offending line and the relevant PEP 8 text, for example E401 multiple imports on one line under import os, sys. Adding --show-pep8 is what makes the report self-explanatory in a code review. To get counts instead of a stream of lines, use --statistics with -qq:

```bash
pycodestyle --statistics -qq Python-2.5/Lib
```

The README shows the result as a two-column table sorted by count, with entries such as 3615 E501 line too long (82 characters) and 4006 E302 expected 2 blank lines, found 1. That table is the fastest way to decide what to enforce. If you only want the first occurrence of each code, the README documents --first:

```bash
pycodestyle --first optparse.py
```

## Where pycodestyle is the wrong tool

The most common mistake is expecting it to fix anything. There is no auto-fix path in the documentation: pycodestyle reports E501 line too long (82 characters) and stops there. autopep8 exists separately for that purpose, and the two are complements, not substitutes. The second mistake is treating it as a linter in the pylint sense. pycodestyle does not resolve imports, detect unused variables, or reason about types; it matches source patterns. A file can be completely clean under pycodestyle and still be broken. The third issue is volume. On an established codebase the statistics output is dominated by a handful of codes, and E501 in particular fires on every long URL or string literal. Enforcing the default configuration on day one turns CI red for reasons nobody intends to fix, which is why the ignore configuration matters more than the install step. Finally, the release cadence deserves a plain statement: the newest release in the repository's release list is 1.7.1, dated 2017-10-25. The default branch was pushed on 2026-08-16, so work continues, but anyone pinning a version should check what the installed release actually contains rather than assuming the branch state.

## pycodestyle versus flake8, pylint and autopep8

flake8 is the closest neighbour and the one people most often compare against. flake8 is a wrapper: it runs pycodestyle for the E and W codes and adds other checks on top, and the repository's own topics list flake8-plugin. If you already run flake8, adding pycodestyle separately gives you the same E-codes twice. Choose pycodestyle alone when you want the style check and nothing else, for example inside a minimal container or a pre-commit hook where the extra dependency surface of flake8 is unwanted. pylint answers a different question entirely: it builds a model of your program and reports unused imports, undefined names and design warnings, at the cost of configuration effort and runtime. pycodestyle will never tell you that an import is unused. autopep8 is the fixer built around the same conventions; the practical split is pycodestyle in CI to fail the build and autopep8 locally to clean up, though running a fixer in CI means your build mutates source, which most teams avoid. Against Black the difference is philosophical: Black reformats code to a single style, pycodestyle reports deviations from PEP 8 and leaves the decision to you.

## Configuration, ignoring codes, and CI cost

The repository carries setup.cfg and tox.ini at the top level, and the tool reads configuration from those files, which is how most projects set an ignore list rather than passing flags on every invocation. The Makefile is minimal: a release target that builds an sdist and a wheel and leaves the twine upload commented out, and a test target that runs tox. That tells you the maintenance workflow is ordinary Python packaging, and it also tells you the upgrade cost: pycodestyle has no runtime dependencies beyond the standard library, so upgrading it cannot break your dependency graph, only your CI result. That is the real cost of an upgrade. A new release can add a check that fires on code which previously passed, and a build that was green becomes red without a single line of your source changing. Pinning the version in your requirements file and reading CHANGES.txt before bumping is the cheap insurance. On licensing: the repository contains a LICENSE file and the metadata reports NOASSERTION, so the exact terms are not stated in the documentation here. Read the LICENSE file in the repository before redistributing or vendoring pycodestyle.py, and get legal advice if the terms matter to your product.

## Conclusion

Adopt pycodestyle if you want PEP 8 conformance checked by a stdlib-only tool whose output your editor can parse, or if you maintain a flake8 plugin that needs the same error codes. Do not adopt it expecting automatic fixes (that is autopep8's job) or type and logic checks (that is pylint's). Before adding it to CI, run it once over your tree and read the --statistics output, because the volume of E501 and E302 findings on an existing codebase is usually what decides whether you enforce it or ignore it.

## FAQ

### How do I install pycodestyle?

Install it from PyPI with pip install pycodestyle. The README also notes a Debian/Ubuntu package exists, but warns it is not always the latest version.

### What does pycodestyle actually do?

It checks Python source against some of the style conventions in PEP 8 and prints findings in a parseable line:column:code format. It reports violations; it does not modify your files.

### How do I run pycodestyle on a file?

Run pycodestyle followed by the path, for example pycodestyle --first optparse.py. Add --show-source and --show-pep8 to print the offending line and the relevant PEP 8 text beneath each finding.

### How do I use pycodestyle in VS Code?

The README does not document a VS Code integration. What it does state is that the output is parseable so an editor can jump to the error location, which is the property an extension would rely on.

### How do I use pycodestyle in PyCharm?

The README does not document a PyCharm integration. It only states that the output is parseable, so an editor can jump to the error location.

## Sources

- [Issues](https://github.com/PyCQA/pycodestyle/issues)
- [Project website](https://pycodestyle.pycqa.org)
- [PyCQA/pycodestyle on GitHub](https://github.com/PyCQA/pycodestyle)
- [README](https://github.com/PyCQA/pycodestyle/blob/main/README.md)
- [Releases](https://github.com/PyCQA/pycodestyle/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pycqa-pycodestyle