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

# 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`.
Additionally, a few different variables may be interpolated into strings in config files via a `%(var)s` syntax. For example, this expands to the absolute path of a file in the root of your repository:

# 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/remove 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}`.