Pants is very configurable and has literally hundreds of tuneable parameters, known in Pants parlance as options.
Most options are automatically set to useful defaults. However it is inevitable that sooner or later you'll need to tweak some of them. For example, you may want to pin your Pants version.
The Pants options system is fairly complex. Codebase administrators will need to understand its details and nuances. End users, however, can usually get by with just a superficial view.
Pants has many moving parts, and more can be added via custom plugins. To avoid option naming collisions, each configurable component is qualified by a scope.
- Global options belong to the global scope.
- Options for task
goalbelong to the
compile.zinc. However if the task has the same name as the goal, then the scope is just that name. E.g.,
./pants list, not
- Options for the global instance of subsystem
subsystembelong to the
- Options for the instance of subsystem
subsystembelonging to some other task or subsystem with scope
scopebelong to the
The scope names are used to qualify the option names when setting their values, as explained in the remainder of this document.
Basic vs. Advanced Options
Some options, such as
-l to control the logging verbosity level, are
expected to be set directly by users, as needed. But most options are
expected to be configured once by a codebase administrator and not
directly modified by users. These latter options are called advanced
options, and are not enumerated in help messages by default. Advanced
options may change the way projects are built and packaged, impact the
build cache or change test behavior. For that reason, they should
usually be set in config files and checked in to the repo so that
build output is consistent, no matter which user invokes it.
To show the full list of options for a goal, including advanced
./pants <goal> --help-advanced. You can view
all options for all scopes with
./pants --help-all --help-advanced.
A handful of global options, such as
-l, are recursive. That is, they have a global value which
can be overridden in each scope. This allows you, for example, to set different logging verbosity
levels in different tasks.
Option value literal formats are the same on the command-line, environment variables and in
with a couple of extra command-line conveniences.
The boolean option values are:
On the command line, you can omit the value thus:
--foo-bar is the same as
--no-foo-bar is the same as
Int and Float Options
Specify values in decimal notation:
Surround strings with single or double quotes if they contain embedded spaces:
List options can be appended to and filtered, as well as overridden.
For example, for an option
--foo whose default value is
[1, 2], then in
foo: 3will yield
[1, 2, 3].
foo: +[3, 4]will yield
[1, 2, 3, 4].
foo: -will yield
foo: [3, 4]will yield
Multiple append and filter expressions may be delimited with commas, allowing you to append and filter simultaneously:
foo: +[3,4],-will yield
[2, 3, 4].
On the command line you can append single values multiple times:
--foo=3 --foo=4will yield the value
[1, 2, 3, 4].
Note that these command line values will be appended to the value determined from the defaults
plus the values in
pants.ini. To override the value, use
Filters apply to the entire list constructed so far, and will filter all appearances of the value:
--foo=1 --foo=1 --foo=2 --foo=-will yield
Filters take precedence over appends, so you cannot "add something back in":
--foo=- --foo=2will yield
Dict option values are Python-style dict literals:
The options available in a given Pants-enabled codebase depend on which backends and plugins are activated.
- View all options available in a "vanilla" Pants install.
- To see a complete list of all basic options available in a given Pants-enabled codebase, enter
- To see global (or goal-specific) basic options, enter
./pants help (goal).
- To see global (or goal-specific) basic and advanced options, enter
./pants help-advanced (goal).
Setting Option Values
Every Pants option can be set in one three ways, in descending order of precendence:
- Using a command-line flag.
- Using an environment variable.
- In a config file.
Config files are typically used to set codebase-wide defaults for all users. Individual users can then override various values using environment variables or command-line flags.
Options that aren't set by one of these three methods will fall back to a sensible default, so that Pants will work "out of the box" in common scenarios.
Command Line Flags
option in scope
foo.bar can be set using the flag
Global options are set with no scope qualifier, e.g.,
Values for single-letter flags (those that start with a single dash) can be set without the equals
-ldebug is the same as
-l is a synonym for
--level). All other flags
must use an equals sign to set a value.
There's a useful shorthand that can save some typing when setting multiple options for a single task:
If you invoke a task explicitly on the command line then you can follow that task with unqualified
options in its scope. E.g.,
./pants compile.zinc --no-incremental --name-hashing
./pants compile --no-compile-zinc-incremental --compile-zinc-name-hashing.
Note that this shorthand requires you to mention a specific task, not just a goal:
instead of just
./pants compile as you would usually enter. All tasks in the
compile goal will
still be executed, not just
compile.zinc, but the
.zinc addition is a convenience to support shorthand options.
Of course this works when specifying multiple goals, e.g.,
./pants compile.zinc --no-incremental --name-hashing test.junit --parallel-threads=4
option in scope
foo.bar can be set via the environment variable
Global options can be set using
PANTS_GLOBAL_OPTION as expected, but you can also omit the GLOBAL
If a global option name itself starts with the word 'pants' then you can omit the repetition. E.g.,
PANTS_WORKDIR instead of
Environment variables are overridden by command line flags, but take precedence over settings in config files.
The main Pants config file location is
pants.ini in your source tree's top-level directory.
If you installed pants as recommended this file should already exist.
pants.ini file looks something like:
[scope] option1: value1 option2: value2
Sections in the
.ini file correspond to the task name or
subsystem name, or a combination of both.
[DEFAULT] section is special: its values are available in all other sections. E.g.,
[DEFAULT] thrift_workdir: %(pants_workdir)s/thrift [GLOBAL] print_exception_stacktrace: True [gen.thrift] workdir: %(thrift_workdir)s [compile.zinc] args: [ '-C-Tnowarnprefixes', '-C%(thrift_workdir)s', ]
Note that continuation lines of multiple-line values must be indented. For example, the closing bracket in the multi-line list above.
Settings in config files are overridden by options specified in the environment or by command line flags.
There are a few differences in using options in the config file compared to invoking them from the command line:
- Omit the leading double dash (
- Dash characters (
-) are transposed to underscores (
- Boolean flag values are enabled and disabled by setting the value
of the option to
- The prefix for long form options is not specified. Instead, you must organize the options into their appropriate sections.
Overlaying Config Files
Sometimes it's convenient to keep
.ini settings in more than one file. Perhaps you usually
operate Pants in one "mode", but occasionally need to use a tweaked set of settings.
--pants-config-files command-line option to specify a second
.ini file. Each of
.ini file's values override the corresponding value in
pants.ini, if any.
For example, if your
pants.ini contains the section
[test.junit] coverage_html_open: True debug: False
...and you invoke
--pants-config-files=quick.ini and your
[test.junit] coverage_html_open: False skip: True
...then Pants will act as if you specified
[test.junit] coverage_html_open: False skip: True debug: False
--pants-config-files is a list-valued option, so all the
idioms of lists work. You can add a third file with another invocation
--pants-config-files=<path>, or you can replace the standard one
Troubleshooting Config Files
Use the Right Section Name
Section names must correspond to actual option scopes. Use the correct section name as specified in the help output:
# Wrong [compile] # The correct scope for the 'warnings' option is compile.zinc zinc_warnings: False # Right [compile.zinc] warnings: False
When in doubt, the scope is described in the heading for each option in the help output:
$ ./pants compile.zinc --help compile.zinc options: Compile Scala and Java code using Zinc. --[no-]compile-zinc-debug-symbols (default: False) Compile with debug symbol enabled. ...
Check the Formatting
Settings that span multiple lines should be indented. To minimize problems, follow these conventions:
- Followon lines should be indented four spaces.
- The ending bracket for lists and dicts should be indented two spaces.
Here are some examples of correctly and incorrectly formatted values:
# Right jvm_options: [ "foo", "bar" ] # Right jvm_options: [ "foo", "bar" ] # Wrong jvm_options: [ "foo", "bar" ] # Followon line must be indented # Wrong jvm_options: [ "foo", "bar" ] # closing bracket must be indented