DocsCommunityTestimonialsUsersGitHubTwitterBlogJobs
HomeDocs
DocsCommunityTestimonialsUsersGitHubTwitterBlogJobsTermsPrivacyCookies
TermsPrivacyCookies
Hey! These docs are for version 2.12, which is no longer officially supported. Click here for the latest version, 2.18!

# 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 `pytest` subsystem contains options related to [Python's test framework pytest](🔗).

# 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 a config file (`pants.toml`).

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`, e.g. `./pants help global`.

## Command-line flags

Global options are set using an unqualified flag:


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

## Environment variables
Global options are set using the environment variable `PANTS_{OPTION_NAME}`:

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

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:

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

Note that any dashes in the option flag name are converted to underscores: `--multiword-name` becomes `multiword_name`.
### Config file interpolation
Environment variables can be interpolated by using the syntax `%(env.ENV_VAR)s`, e.g.:

Additionally, a few special values are pre-populated with the `%(var)s` syntax:
  • `%(buildroot)s`: absolute path to the root of your repository
  • `%(homedir)s`: equivalent to `$HOME` or `~`
  • `%(user)s`: equivalent to `$USER`
  • `%(pants_distdir)s`: absolute path of the global option `--pants-distdir`, which defaults
 to `{buildroot}/dist/`
# 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:

### Environment variables:

### Config file entries:

## 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 `--boolopt/--no-boolopt` syntax.
### Command-line flags:

### Environment variables:

### Config file entries:

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

You can also leave off the `[]` to _append_ elements. So we can rewrite the above to:

### Environment variables:

Like with command-line flags, you can leave off the `[]` to _append_ elements:

### Config file entries:

### Add/remove semantics
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 

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

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

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:

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: 

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 on the command-line and environment variables, 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:

### Environment variables:

### Config file entries:
You can use TOML's [nested table features](🔗). These are equivalent:


You can also use a string literal. Note the quotes:

### Add/replace 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 

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

will set the value to `{'foo': 42, 'baz': 3}`.
# Reading individual option values from files
If an option value is too large or elaborate to use directly, or if you don't want to hard-code
values directly in `pants.toml`, you can set the value of any option to the string
`@relative/path/from/repo/root/to/file` (note the leading `@`), and the value will be read
from that file. 
If the file name ends with `.json` or `.yaml` then the file will be parsed as the relevant
format, which is useful for list- and dict-valued options. 
Otherwise, the file is parsed as a literal as described above for each option type.
Note that you can use this feature on the command-line, in an env var, or in a config file:



Gotcha: If you modify the value file, you must manually restart pantsd
Until we resolve [this issue](🔗), changing
the value in a file used with the `@` syntax as described above will not invalidate the build.
For now, if such a file changes you will have to restart the Pants daemon manually. You can
do so by `kill`ing it (after using `ps -ef | grep pantsd` to find its pid), or by running
Pants once with `--no-pantsd`.
# `.pants.rc` file
You can set up personal Pants config files, using the same TOML syntax as `pants.toml`. By default, Pants looks for the paths `/etc/pantsrc`, `~/.pants.rc`, and `.pants.rc` in the repository root.
For example:

If you want to ban this feature, set `[GLOBAL].pantsrc = false` in `pants.toml`.