HomeDocs
DocsCommunityTestimonialsUsersGitHubTwitterBlogJobsTermsPrivacyCookies
TermsPrivacyCookies
Hey! These docs are for version 2.8, 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`.

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}`.