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


Options for Pants's Python support.

Config section: [python-setup]

Basic options


Advanced options


--python-setup-interpreter-constraints="[<requirement>, <requirement>, ...]"

The Python interpreters your codebase is compatible with.

Specify with requirement syntax, e.g. 'CPython>=2.7,<3' (A CPython interpreter with version >=2.7 AND version <3) or 'PyPy' (A pypy interpreter of any version). Multiple constraint strings will be ORed together.

These constraints are used as the default value for the interpreter_constraints field of Python targets.


default: None

When resolving third-party requirements, use this constraints file to determine which versions to use.

See for more information on the format of constraint files and how constraints are applied in Pex and pip.

Mutually exclusive with --requirement-constraints-target.


default: None

When resolving third-party requirements, use this _python_constraints target to determine which versions to use.

This is primarily intended for macros (for now). Normally, use --requirement-constraints instead with a constraints file.

See for more information on the format of constraints and how constraints are applied in Pex and pip.


one of: never, nondeployables, always
default: nondeployables

If set, and the requirements of the code being operated on are a subset of the constraints file, then the entire constraints file will be used instead of the subset. If unset, or any requirement of the code being operated on is not in the constraints file, each subset will be independently resolved as needed, which is more correct - work is only invalidated if a requirement it actually depends on changes - but also a lot slower, due to the extra resolving.

  • never will always use proper subsets, regardless of the goal being run.
  • nondeployables will use proper subsets for ./pants package, but otherwise attempt to use a single resolve.
  • always will always attempt to use a single resolve.

Requires [python-setup].requirement_constraints to be set.


--python-setup-interpreter-search-paths="[<binary-paths>, <binary-paths>, ...]"

A list of paths to search for Python interpreters that match your project's interpreter constraints. You can specify absolute paths to interpreter binaries and/or to directories containing interpreter binaries. The order of entries does not matter. The following special strings are supported:

  • "<PATH>", the contents of the PATH env var
  • "<PYENV>", all Python versions under $(pyenv root)/versions
  • "<PYENV_LOCAL>", the Pyenv interpreter with the version in BUILD_ROOT/.python-version
  • "<PEXRC>", paths in the PEX_PYTHON_PATH variable in /etc/pexrc or ~/.pexrc


default: manylinux2014

Whether to allow resolution of manylinux wheels when resolving requirements for foreign linux platforms. The value should be a manylinux platform upper bound, e.g.: 'manylinux2010', or else the string 'no' to disallow.


default: 4

The maximum number of concurrent jobs to build wheels with. Because Pants can run multiple subprocesses in parallel, the maximum total parallelism will be `--process-execution-{local,remote}-parallelism x --python-setup-resolver-jobs`. Setting this option higher may result in better parallelism, but, if set too high, may result in starvation and Out of Memory errors.

Deprecated options


one of: pip-legacy-resolver, pip-2020-resolver
default: pip-2020-resolver

Deprecated, will be removed in version: 2.5.0.dev0.
Support for configuring --resolver-version and selecting pip's legacy resolver will be removed in Pants 2.5. Refer to for more information on the new resolver.

The resolver implementation to use when resolving Python requirements.

Updated about a month ago


Suggested Edits are limited on API Reference Pages

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