Skip to main content
Version: 2.4 (deprecated)

Linters and formatters

How to activate and use the Python linters and formatters bundled with Pants.

Activating linters and formatters

Linter/formatter support is implemented in separate backends so that they are easy to opt in to individually:

pants.backend.python.lint.banditBandit: security linter
pants.backend.python.lint.blackBlack: code formatter
pants.backend.python.lint.docformatterDocformatter: docstring formatter
pants.backend.python.lint.flake8Flake8: style and bug linter
pants.backend.python.lint.isortisort: import statement formatter
pants.backend.python.lint.pylintPylint: style and bug linter

To enable, add the appropriate backends in pants.toml:

backend_packages = [

You should now be able to run ./pants lint, and possibly ./pants fmt:

$ ./pants lint src/py/
17:54:32.51 [INFO] Completed: lint - Flake8 succeeded.
17:54:32.70 [INFO] Completed: lint - Black succeeded.
All done! ✨ 🍰 ✨
1 file would be left unchanged.

17:54:33.91 [INFO] Completed: lint - isort succeeded.

✓ Black succeeded.
✓ Flake8 succeeded.
✓ isort succeeded.
How to activate MyPy

MyPy is run with the typecheck goal, rather than lint.

Configuring the tools and adding plugins

Each formatter and linter allows you to configure

  • --version: the version to use.
  • --config: the config file location (relative to the build root).
  • --args: any command-line arguments you want to pass to the tool.
  • --extra-requirements: any additional libraries to install, such as any plugins.

For example:

config = "pyproject.toml"

args = ["--wrap-summaries=100", "--wrap-descriptions=100"]

config = "build-support/.flake8"
version = "flake8==3.8.0"
# Add a Flake8 plugin:
extra_requirements.add = ["flake8-2020"]

Run ./pants help-advanced black, ./pants help-advanced flake8, and so on for more information.

Config files must be explicitly declared before Pants 2.5+

Many tools will automatically discover their config files if it's at a standard location, like isort looking for the file .isort.cfg. This auto-discovery does not work with Pants; you must explicitly set the --config option for Pants to use the correct config file.

This was fixed in Pants 2.5.

How to use first-party Pylint plugins

Pants supports custom Pylint plugins written by you. Run ./pants help-advanced pylint for instructions with the --pylint-source-plugins option.

If you want to write first-party plugins for other linters like Flake8, let us know on Slack.

Temporarily skipping a formatter or linter

Use the --skip option. For example, run:

$ ./pants --black-skip --flake8-skip fmt ::

Tip: only run over changed files

With formatters and linters, there is usually no need to rerun on files that have not changed.

Use the option --changed-since to get much better performance, like this:

$ ./pants --changed-since=HEAD fmt


$ ./pants --changed-since=main lint

Pants will find which files have changed and only run over those files. See Advanced target selection for more information.