How to automatically lint your Python code on commit

Increasing code quality is a constant battle for all developers so it makes sense to use every tool available.

Ian Cordasco’s flake8 is pretty much the standard in Python linting at the moment. It wraps three libraries: pyflakes (a static analyzer/linter), pep8 (a PEP8 checker) and McCabe (a cyclomatic complexity checker).

Running it against a project is dead simple. Just install it, go to your project root, and use the flake8 command:

If you want, you can run it yourself each time, but it is better to set up a pre-commit hook so that it runs every time you try to check in code and blocks the commit if it detects any quality problems.

There is a way to automatically install the hook (flake8 --install-hook), but I have found it unreliable, so I just manually add flake8 to the .git/hooks/pre-commit script. Here’s what my script looks like:

Remember that this script needs to be executable.

After you add that hook, your commits will be blocked if flake8 identifies any issues. The problem is that out of the box it is quite sensitive, so you might want to allow certain things to be committed that it thinks are problematic. There are two ways to do that.

For single lines that cause problems (because they are too long and don’t pass PEP8, for instance), you can add an ignore directive in a comment, like so:

Or if you want to ignore a certain type of error for the entire project, or exclude certain subdirectories, you can add a .flake8 config file and set up ignores and excludes in there. Here’s an example:

The ignore property takes a comma-separated list of error codes that should be ignored. In this case, E501 is the “line too long” error. The exclude property takes a comma-separated list of files and locations not to check. max-complexity specifies the maximum cyclomatic complexity allowed for functions, as determined by the McCabe library. The default value is 10, but I find that very conservative so I like to set it to 16.

That should be more than enough to get started, but if you want to learn more, you can check out the flake8 docs here.