Configure Flake8 with setup.cfg

Flake8 is a popular linter for Python. It checks your code for style issues and errors.

By default, Flake8 works with no setup. But most projects need custom rules.

You can configure Flake8 in several files. The setup.cfg file is one of the best choices.

This guide shows you how to set up Flake8 using setup.cfg. It covers the basics and advanced tips.

What Is Flake8?

Flake8 is a tool that combines several Python checkers. It includes PyFlakes, pycodestyle, and McCabe.

PyFlakes finds logical errors. pycodestyle checks PEP 8 style. McCabe checks code complexity.

Flake8 runs all three at once. It gives you a single report.

You can install it with pip:

pip install flake8

After install, you can run it on any file or folder:

flake8 my_project/

Flake8 prints a list of issues. Each line shows a file, line number, column, and error code.

Why Use setup.cfg for Flake8?

Flake8 reads config from many files. These include setup.cfg, tox.ini, and .flake8.

The setup.cfg file is common in Python projects. It often holds packaging and tool settings.

Using setup.cfg keeps your config in one place. You do not need extra files.

It also works well with other tools like pytest and mypy.

This makes setup.cfg a clean choice for small and large projects.

Basic setup.cfg Structure

Flake8 reads a section called [flake8]. All settings go under this header.

Here is a simple example:

[flake8]
max-line-length = 88
exclude = .git,__pycache__,build,dist
ignore = E203, W503

Let us break down each line.

max-line-length sets the longest allowed line. The default is 79. Many teams use 88 or 100.

exclude lists files and folders to skip. Flake8 will not check them.

ignore lists error codes to skip. This is useful for rules you do not want.

Save the file in your project root. Then run Flake8 again.

flake8 .

Flake8 now uses your settings. The output will reflect your custom rules.

Common Flake8 Options

Flake8 has many options. Here are the ones you will use most.

Line Length

PEP 8 suggests 79 characters. But many teams prefer 88 or 100.

Set it like this:

[flake8]
max-line-length = 100

This tells Flake8 to allow lines up to 100 characters.

Ignoring Errors

Some errors may not fit your project. You can ignore them by code.

[flake8]
ignore = E501, W503, E203

Each code is separated by a comma. Flake8 will skip these.

Be careful. Ignoring too many codes hides real problems.

Selecting Errors

You can also choose only certain codes. Use the select option.

[flake8]
select = E, W, F

This runs only pycodestyle and PyFlakes checks. It skips complexity checks.

Excluding Files

You may want to skip tests, migrations, or build folders.

[flake8]
exclude = .git,__pycache__,build,dist,migrations

Flake8 will not check any file in those folders.

Per-File Ignores

Sometimes one file needs different rules. Use per-file-ignores.

[flake8]
per-file-ignores =
    __init__.py:F401
    tests/*:E501

This ignores unused imports in __init__.py. It also ignores long lines in tests.

This is very useful for real projects.

Full Example setup.cfg

Here is a complete example. It covers many common needs.

[flake8]
max-line-length = 88
exclude = .git,__pycache__,build,dist,.venv
ignore = E203, W503
per-file-ignores =
    __init__.py:F401
    tests/*:E501
max-complexity = 10

The max-complexity option sets a limit for McCabe checks. A value of 10 is common.

This config keeps your code clean and readable.

How to Test Your Config

After you edit setup.cfg, run Flake8 again.

flake8 .

If you see fewer or different errors, your config works.

You can also check a single file:

flake8 my_script.py

This is a fast way to test new rules.

Using Flake8 with Other Tools

Flake8 works well with editors and CI tools.

In VS Code, install the Flake8 extension. It reads your setup.cfg automatically.

In GitHub Actions, add a step to run Flake8. This keeps code clean on every push.

You can also use pre-commit to run Flake8 before each commit.

This saves time and catches issues early.

Common Mistakes to Avoid

One mistake is putting settings in the wrong section. The header must be [flake8].

Another mistake is a typo in an error code. Flake8 will not warn you. It just ignores the bad code.

Also, do not ignore too many errors. It hides real bugs.

Keep your ignore list short and clear.

Why setup.cfg Beats Other Files

You can use .flake8 or tox.ini. But setup.cfg has benefits.

It is already used by many Python tools. So you avoid extra files.

It is also easy to read and edit. This helps new team members.

For most projects, setup.cfg is the best choice.

Conclusion

Configuring Flake8 with setup.cfg is simple and powerful.

You set rules for line length, ignored errors, and excluded files.

You can also add per-file rules and complexity limits.

This keeps your Python code clean and consistent.

Start with a small config. Add more rules as your project grows.

Run Flake8 often. Fix issues early. Your code will thank you.