Configuring Flake8

Once you have learned how to invoke Flake8, you will soon want to learn how to configure it so you do not have to specify the same options every time you use it.

This section will show you how to make

flake8

Remember that you want to specify certain options without writing

flake8 --select E123,W456 --enable-extensions H111

Configuration Locations

Flake8 supports storing its configuration in the following places:

  • Your top-level user directory
  • In your project in one of setup.cfg, tox.ini, or .flake8.

“User” Configuration

Flake8 allows a user to use “global” configuration file to store preferences. The user configuration file is expected to be stored somewhere in the user’s “home” directory.

  • On Windows the “home” directory will be something like C:\\Users\sigmavirus24, a.k.a, ~\.
  • On Linux and other Unix like systems (including OS X) we will look in ~/.

Note that Flake8 looks for ~\.flake8 on Windows and ~/.config/flake8 on Linux and other Unix systems.

User configuration files use the same syntax as Project Configuration files. Keep reading to see that syntax.

Project Configuration

Flake8 is written with the understanding that people organize projects into sub-directories. Let’s take for example Flake8‘s own project structure

flake8
├── docs
│   ├── build
│   └── source
│       ├── _static
│       ├── _templates
│       ├── dev
│       ├── internal
│       └── user
├── flake8
│   ├── formatting
│   ├── main
│   ├── options
│   └── plugins
└── tests
    ├── fixtures
    │   └── config_files
    ├── integration
    └── unit

In the top-level flake8 directory (which contains docs, flake8, and tests) there’s also tox.ini and setup.cfg files. In our case, we keep our Flake8 configuration in tox.ini. Regardless of whether you keep your config in .flake8, setup.cfg, or tox.ini we expect you to use INI to configure Flake8 (since each of these files already uses INI as a format). This means that any Flake8 configuration you wish to set needs to be in the flake8 section, which means it needs to start like so:

[flake8]

Each command-line option that you want to specify in your config file can be named in either of two ways:

  1. Using underscores (_) instead of hyphens (-)
  2. Simply using hyphens (without the leading hyphens)

Note

Not every Flake8 command-line option can be specified in the configuration file. See our list of options to determine which options will be parsed from the configuration files.

Let’s actually look at Flake8‘s own configuration section:

[flake8]
ignore = D203
exclude = .git,__pycache__,docs/source/conf.py,old,build,dist
max-complexity = 10

This is equivalent to:

flake8 --ignore D203 \
         --exclude .git,__pycache__,docs/source/conf.py,old,build,dist \
         --max-complexity 10

In our case, if we wanted to, we could also do

[flake8]
ignore = D203
exclude =
    .git,
    __pycache__,
    docs/source/conf.py,
    old,
    build,
    dist
max-complexity = 10

This would allow us to add comments for why we’re excluding items, e.g.,

[flake8]
ignore = D203
exclude =
    # No need to traverse our git directory
    .git,
    # There's no value in checking cache directories
    __pycache__,
    # The conf file is mostly autogenerated, ignore it
    docs/source/conf.py,
    # The old directory contains Flake8 2.0
    old,
    # This contains our built documentation
    build,
    # This contains builds of flake8 that we don't want to check
    dist
max-complexity = 10

Note

If you’re using Python 2, you will notice that we download the configparser backport from PyPI. That backport enables us to support this behaviour on all supported versions of Python.

Please do not open issues about this dependency to Flake8.

Note

You can also specify --max-complexity as max_complexity = 10.

This is also useful if you have a long list of error codes to ignore. Let’s look at a portion of OpenStack’s Swift project configuration:

[flake8]
# it's not a bug that we aren't using all of hacking, ignore:
# F812: list comprehension redefines ...
# H101: Use TODO(NAME)
# H202: assertRaises Exception too broad
# H233: Python 3.x incompatible use of print operator
# H301: one import per line
# H306: imports not in alphabetical order (time, os)
# H401: docstring should not start with a space
# H403: multi line docstrings should end on a new line
# H404: multi line docstring should start without a leading new line
# H405: multi line docstring summary not separated with an empty line
# H501: Do not use self.__dict__ for string formatting
ignore = F812,H101,H202,H233,H301,H306,H401,H403,H404,H405,H501

They use the comments to describe the check but they could also write this as:

[flake8]
# it's not a bug that we aren't using all of hacking
ignore =
    # F812: list comprehension redefines ...
    F812,
    # H101: Use TODO(NAME)
    H101,
    # H202: assertRaises Exception too broad
    H202,
    # H233: Python 3.x incompatible use of print operator
    H233,
    # H301: one import per line
    H301,
    # H306: imports not in alphabetical order (time, os)
    H306,
    # H401: docstring should not start with a space
    H401,
    # H403: multi line docstrings should end on a new line
    H403,
    # H404: multi line docstring should start without a leading new line
    H404,
    # H405: multi line docstring summary not separated with an empty line
    H405,
    # H501: Do not use self.__dict__ for string formatting
    H501

Or they could use each comment to describe why they’ve ignored the check. Flake8 knows how to parse these lists and will appropriatey handle these situations.