Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 38 ยท Linting, Types and Formatting

Linting with Ruff and Pyflakes

Catch bugs and style problems automatically in Python. Learn what a linter checks, run pyflakes and pycodestyle for real, and configure Ruff in pyproject.toml.

A linter reads your code without running it and reports things that look wrong: a variable you never use, a name that does not exist, an import nobody needs, a line that breaks the team's style rules. Linters find a surprising number of real bugs for free, because they inspect every line, including the error-handling branch you have never executed.

This lesson shows what linters catch, runs two classic linters for real, and then explains Ruff, the fast modern linter that has largely replaced a whole collection of older tools.

What a linter finds

Linters group their findings into rule families. A few examples:

  • Correctness: undefined names, unused variables, duplicate dictionary keys, == against None.
  • Imports: unused imports, imports in the wrong order, wildcard imports.
  • Style: line length, whitespace, naming conventions (PEP 8).
  • Simplifications: if x == True, a for loop that could be a comprehension.
  • Security smells: eval, hard-coded passwords, subprocess with shell=True.
  • Modernization: old syntax that has a newer replacement.

Not every warning is a bug. Linters are advisers: you fix the real problems and configure or silence the rest.

Pyflakes: the correctness checker

pyflakes only reports things that are almost certainly errors, and it never complains about style. That makes it a great minimum. Here it is running for real on a buggy snippet:

Python Run pyflakes on buggy code

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Read each message and match it to a line: the unused imports, the star import, the unused variable count, the undefined name tax (a real crash waiting to happen; pyflakes says "may be undefined" only because the star import could have supplied it), an f-string with no placeholders, a format string with too few arguments, and the repeated dictionary key.

pycodestyle: the style checker

pycodestyle (formerly called pep8) checks the layout rules from PEP 8. Its codes start with E (errors) and W (warnings):

Python Check PEP 8 style

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

You will see codes like E401 (multiple imports on one line), E302 (expected two blank lines), E225 (missing whitespace around an operator), E231 (missing whitespace after a comma) and E731 (do not assign a lambda). The code is the thing you search for, and tools let you ignore or select by code.

Older projects combined these with other plugins through flake8, which runs pyflakes, pycodestyle and a complexity checker together. It still works, but it needs many plugins to cover everything.

Ruff: one fast tool

Ruff is a linter (and formatter) written in Rust. It reimplements the rules of pyflakes, pycodestyle, isort, pyupgrade, bandit, flake8-bugbear and dozens of other plugins, and it runs in milliseconds even on huge code bases. You install it like any tool and run it from the project root:

Terminal
pip install ruff           # or: uv tool install ruff
ruff check .               # report problems
ruff check . --fix         # fix the ones that are safe to fix automatically
ruff check . --select I --fix   # only sort imports
ruff rule F401             # explain one rule

Ruff cannot run in this browser page, so the commands above are read-only. Everything it reports uses the same codes you just saw (F for pyflakes, E and W for pycodestyle) plus its own families.

Configuring Ruff

Put the configuration in pyproject.toml so your project has one source of truth:

TOML
[tool.ruff]
line-length = 88
target-version = "py311"
extend-exclude = ["migrations"]

[tool.ruff.lint]
select = [
    "E", "W",   # pycodestyle
    "F",        # pyflakes
    "I",        # import sorting
    "B",        # bugbear: likely bugs
    "UP",       # modernize syntax for the target version
    "SIM",      # simplifications
]
ignore = ["E501"]   # line length is the formatter's job

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"]   # allow assert in tests
  • select chooses which rule families run; ignore removes specific codes.
  • per-file-ignores relaxes rules where they do not fit, such as asserts in tests.
  • target-version tells rules like UP which syntax is safe to use.

To silence a single line when you have a good reason, add a comment, and say why:

Python
import legacy_hook  # noqa: F401  (imported for its side effects)

Start with a small rule set (E, F, I) and add families gradually. Turning on everything in a large existing code base gives thousands of warnings and teaches the team to ignore the tool.

A tiny linter of your own

Linters are not magic: they walk the syntax tree that Python's own ast module produces. This stand-in finds unused imports, the most common F-code, in about twenty lines:

Python Build a mini unused-import checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A real linter handles many more cases (scopes, __all__, conditional imports), but the principle is the same: parse, walk the tree, compare what is defined with what is used.

Make linting automatic

A rule nobody runs does not protect anyone. Run the linter in three places: your editor (instant feedback), a pre-commit hook (before code is committed), and CI (the final gate). Fail the build on lint errors so style discussions disappear from code review.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does pyflakes report?

    Pyflakes deliberately avoids style rules and reports things that are almost certainly mistakes.
  2. 2. What is the advantage of Ruff over flake8 with many plugins?

    Ruff bundles rules from many plugins and runs quickly, so one dependency and one config section replace a collection of tools.
  3. 3. In [tool.ruff.lint], what does select = ["E", "F", "I"] do?

    select lists rule families or codes that should run.
  4. 4. What is the best way to silence one justified warning on one line?

    A targeted noqa comment documents the exception without disabling the rule everywhere.

Summary

  • Linters analyze code without running it and report likely bugs and style problems.
  • Pyflakes finds correctness issues, pycodestyle checks PEP 8 layout, and Ruff combines these and many more in one fast tool.
  • Configure Ruff in pyproject.toml with select, ignore and per-file-ignores; adopt rules gradually.
  • Run linting in the editor, in pre-commit and in CI.

Next: Formatting with Black and Ruff Format