Pants is highly configurable. There are hundreds of options whose values can be modified in order to fine-tune the behavior of the system.

This page will explain how options work, and how to set their values.

Option scopes

Pants is an extensible system. Each backend can introduce its own options, so it's important to ensure that option names in different parts of the system cannot collide, and to do so without requiring global name coordination.

To achieve this, the options namespace is partitioned into named scopes. The scope name qualifies the option, so that two options that happen to have the same name, but are in different scopes, don't collide.

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 these default values using the help system.

Command-line flags

Global options are set using an unqualified flag:

<<pantscmd>> --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:

<<pantscmd>> --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 = ['^ext/']

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:

<<pantscmd>> --scope-intopt=42
<<pantscmd>> --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:

<<pantscmd>> --scope-boolopt=true
<<pantscmd>> --scope-boolopt
<<pantscmd>>--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:

<<pantscmd>> --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

<<pantscmd>> --scope-listopt="+[3,4]"

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

<<pantscmd>> --scope-listopt="-[1],+[3,4]"

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

<<pantscmd>> --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:

TOML

[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:

TOML

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

But note that this only works in Pants' .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:

<<pantscmd>> --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

<<pantscmd>> --scope-dictopt="+{'foo':42,'baz':3}"

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

<<pantscmd>> --scope-dictopt="{'foo':42,'baz':3}"

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