Pants v2: The ergonomic build system

Welcome to the Pants v2 documentation hub!

Pants v2 is a fast, scalable, user-friendly build system for growing codebases. It's currently focused on Python, with support for other languages coming soon.

Here you'll find guides to help you get started with Pants v2, comprehensive documentation on how to configure, run and customize Pants v2, and information on how to get help from the Pants community.

Get Started

Enabling Python support

How to enable Pants's bundled Python backend package.


Example Python repository

See here for examples of Pants's Python functionality.

Enable the Python backend like this:

backend_packages = [

You should now see some new goals available:

$ ./pants help goals

package       Create a distributable package.

repl          Open a REPL with the specified code loadable.


run           Runs a binary target.

test          Run tests.


Have content in your files?

Pants automatically uses all relevant files, even if dependency inference does not include the files and you don't add it to the dependencies fields of your targets.

This works if you have empty files, like most Python projects do; but if you have actual code in your files, you should turn on this option in your pants.toml:

inits = true

This option will cause Pants to infer "proper" dependencies on any ancestor file. If you run ./pants dependencies project/util/, you should see project/ and project/util/ show up. This will ensure that any of the dependencies of your files are included.


macOS users: you may need to change interpreter search paths

By default, Pants will look at both your $PATH and—if you use Pyenv—your $(pyenv root)/versions folder when discovering Python interpreters. Your $PATH likely includes the system Pythons at /usr/bin/python and /usr/bin/python3, which are known to have many issues like failing to install some dependencies.

Pants will prefer new Python versions, like 3.6.10 over 3.6.3. Because macOS system Pythons are usually very old, they will usually be ignored.

However, if you run into issues, you can set the interpreter_search_paths option in the [python-setup] scope:

interpreter_search_paths = [
    # This will use all interpreters in `$(pyenv root)/versions`.
     # Brew usually installs Python here. 

See here for more information.

Updated 2 months ago

Enabling Python support

How to enable Pants's bundled Python backend package.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.