Pants v2: Fast, consistent builds for Python and more

Welcome to the Pants v2 documentation hub!

Pants v2 is a fast, scalable 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

A deep dive into how options may be configured.

Option scopes

Options are partitioned into named scopes.

Some systemwide options belong in the global scope. For example, the --level option, which controls the logging level, is in the global scope.

Other options belong to a subsystem scope. A subsystem is simply a collection of related options, in a scope. For example, the source subsystem contains options related to source roots.

Setting options

Every option can be set in the following ways, in order of precedence:

  1. Via a command line flag.
  2. In an environment variable.
  3. In the config file.

If an option isn't set in one of these ways, it will take on a default value.

You can inspect both the current value and the default value by using ./pants help $scope or ./pants help-advanced $scope.

Command-line flags

Global options are set using an unqualified flag:

./pants --level=debug ...

Subsystem options are set by providing the flag, with the name prefixed with the lower-case scope name and a dash. So for the option --root-patterns in the scope source:

./pants --source-root-patterns="['^ext']"

Environment variables

Global options are set using the environment variable PANTS_{OPTION_NAME}:

PANTS_LEVEL=debug ./pants ...

Subsystem options are set using the environment variable
PANTS_{SCOPE}_{OPTION_NAME}:

PANTS_SOURCE_ROOT_PATTERNS="['^ext']" ./pants ...

Note that the scope and option name are upper-cased, and any dashes in the option flag name are converted to underscores: --multiword-name becomes MULTIWORD_NAME.

Config file entries

Global options are set in the GLOBAL section of the config file:

[GLOBAL]
level = "debug"

Subsystem options are set in the section named for their scope:

[source]
root_patterns = ["/src/python"]

Note that any dashes in the option flag name are converted to underscores: --multiword-name becomes multiword_name .

Option types

Every option has a type, and any values you set must be of that type.

The option types are:

  • string
  • integer
  • bool
  • list
  • dict

A list-valued option may also declare a specific type for its members (e.g., a list of strings, or a list of integers).

String and integer values

Standalone string and integer values are written without quotes. Any quotes will be considered part of the value, after shell escaping.

Command-line flags:

./pants --scope-intopt=42
./pants --scope-stropt=qux

Environment variables:

PANTS_SCOPE_INTOPT=42
PANTS_SCOPE_STROPT=qux

Config file entries:

[scope]
intopt = 42
stropt = "qux"

Boolean values

Boolean values can be specified using the special strings true and false. When specifying them via command-line flags you can also use the --boolflag/--no-boolflag syntax.

Command-line flags:

./pants --scope-boolopt=true
./pants --scope-boolopt
./pants --no-scope-boolopt

Environment variables:

PANTS_SCOPE_BOOLOPT=true

Config file entries:

[scope]
boolopt = true

List values

List values are parsed as Python list literals, so you must quote string values, and you may need to apply shell-level quoting and/or escaping, as required.

Command-line flags:

./pants --scope-listopt="['foo','bar']"

Environment variables:

PANTS_SCOPE_LISTOPT="['foo','bar']"

Config file entries:

[scope]
listopt = [
  'foo', 
  'bar'
]

List values have some extra semantics:

  • A value can be preceded by +, which will append the elements to the value obtained from lower-precedence sources.
  • A value can be preceded by -, which will remove the elements from the value obtained from lower-precedence sources.
  • Multiple + and - values can be provided, separated by commas.
  • Otherwise, the value replaces the one obtained from lower-precedence sources.

For example, if the value of --listopt in scope is set to [1, 2] in a config file, then

./pants --scope-listopt="+[3,4]"

will set the value to [1, 2, 3, 4].

./pants --scope-listopt="-[1],+[3,4]"

will set the value to [2, 3, 4], and

./pants --scope-listopt="[3,4]"

will set the value to [3, 4].

📘

Add/remove syntax in .toml files

The +/- syntax works in .toml files, but the entire value must be quoted:

[scope]
listopt = "+[1,2],-[3,4]"

This means that TOML treats the value as a string, instead of a TOML list.

Alternatively, you can use this syntactic sugar, which allows the values to be regular TOML lists:

[scope]
listopt.add = [1, 2]
listopt.remove = [3, 4]

But note that this only works in Pants's .toml config files, not in environment variables or command-line flags.

Dict values

Dict values are parsed as Python dict literals, so you must quote string keys and values, and you may need to apply shell-level quoting and/or escaping, as required.

Command-line flags:

./pants --scope-dictopt="{'foo':1,'bar':2}"

Environment variables:

PANTS_SCOPE_DICTOPT="{'foo':1,'bar':2}"

Config file entries:

[scope]
dictopt = """{
  'foo': 1, 
  'bar': 2
}"""
# Note that dict values in .toml files must be quoted.

Dict values have some extra semantics:

  • A value can be preceded by +, which will update the value obtained from lower-precedence sources with the entries.
  • Otherwise, the value replaces the one obtained from lower-precendence sources.

For example, if the value of --dictopt in scope is set to {'foo', 1, 'bar': 2} in a config file, then

./pants --scope-dictopt="+{'foo':42,'baz':3}"

will set the value to {'foo': 42, 'bar': 2, 'baz': 3}, and

./pants --scope-dictopt="{'foo':42,'baz':3}"

will set the value to {'foo': 42, 'baz': 3}.

Updated about a month ago


Options


A deep dive into how options may be configured.

Suggested Edits are limited on API Reference Pages

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