Options to control the overall behavior of Pants.
Backend: <span style="color: purple"><code>pants.core</code></span> Config section: <span style="color: purple"><code>[GLOBAL]</code></span>
## Basic options
<div style="color: purple">
### `level`
<code>-l=<LogLevel>, --level=<LogLevel></code><br> <code>PANTS_LEVEL</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">one of: <code>trace, debug, info, warn, error</code></span><br> <span style="color: green">default: <code>info</code></span>
<br>
Set the logging level.
</div> <br>
<div style="color: purple">
### `spec_files`
<code>--spec-files="['<str>', '<str>', ...]"</code><br> <code>PANTS_SPEC_FILES</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
Read additional specs (target addresses, files, and/or globs), one per line, from these files.
</div> <br>
<div style="color: purple">
### `pantsd`
<code>--[no-]pantsd</code><br> <code>PANTS_PANTSD</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>True</code></span>
<br>
Enables use of the Pants daemon (pantsd). pantsd can significantly improve runtime performance by lowering per-run startup cost, and by memoizing filesystem operations and rule execution.
</div> <br>
<div style="color: purple">
### `concurrent`
<code>--[no-]concurrent</code><br> <code>PANTS_CONCURRENT</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
Enable concurrent runs of Pants. Without this enabled, Pants will start up all concurrent invocations (e.g. in other terminals) without pantsd. Enabling this option requires parallel Pants invocations to block on the first.
</div> <br>
<div style="color: purple">
### `local_cache`
<code>--[no-]local-cache</code><br> <code>PANTS_LOCAL_CACHE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>True</code></span>
<br>
Whether to cache process executions in a local cache persisted to disk at `--local-store-dir`.
</div> <br>
<div style="color: purple">
### `process_cleanup`
<code>--[no-]process-cleanup</code><br> <code>PANTS_PROCESS_CLEANUP</code><br>
</div>
<div style="padding-left: 2em;">
<span style="color: green">default: <code>True</code></span>
<p style="color: darkred">Upcoming deprecation in version: 2.15.0.dev1, is scheduled to be removed in version: 2.17.0.dev1.<br>Use the `keep_sandboxes` option instead.</p>
<br>
If false, Pants will not clean up local directories used as chroots for running processes. Pants will log their location so that you can inspect the chroot, and run the `__run.sh` script to recreate the process using the same argv and environment variables used by Pants. This option is useful for debugging.
</div> <br>
<div style="color: purple">
### `keep_sandboxes`
<code>--keep-sandboxes=<KeepSandboxes></code><br> <code>PANTS_KEEP_SANDBOXES</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">one of: <code>always, on_failure, never</code></span><br> <span style="color: green">default: <code>never</code></span>
<br>
Controls whether Pants will clean up local directories used as chroots for running processes.
Pants will log their location so that you can inspect the chroot, and run the `__run.sh` script to recreate the process using the same argv and environment variables used by Pants. This option is useful for debugging.
</div> <br>
<div style="color: purple">
### `remote_execution`
<code>--[no-]remote-execution</code><br> <code>PANTS_REMOTE_EXECUTION</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
Enables remote workers for increased parallelism. (Alpha)
Alternatively, you can use `[GLOBAL].remote_cache_read` and `[GLOBAL].remote_cache_write` to still run everything locally, but to use a remote cache.
</div> <br>
<div style="color: purple">
### `remote_cache_read`
<code>--[no-]remote-cache-read</code><br> <code>PANTS_REMOTE_CACHE_READ</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
Whether to enable reading from a remote cache.
This cannot be used at the same time as `[GLOBAL].remote_execution`.
</div> <br>
<div style="color: purple">
### `remote_cache_write`
<code>--[no-]remote-cache-write</code><br> <code>PANTS_REMOTE_CACHE_WRITE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
Whether to enable writing results to a remote cache.
This cannot be used at the same time as `[GLOBAL].remote_execution`.
</div> <br>
<div style="color: purple">
### `colors`
<code>--[no-]colors</code><br> <code>PANTS_COLORS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
Whether Pants should use colors in output or not. This may also impact whether some tools Pants runs use color.
When unset, this value defaults based on whether the output destination supports color.
</div> <br>
<div style="color: purple">
### `dynamic_ui`
<code>--[no-]dynamic-ui</code><br> <code>PANTS_DYNAMIC_UI</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
Display a dynamically-updating console UI as Pants runs. This is true by default if Pants detects a TTY and there is no 'CI' environment variable indicating that Pants is running in a continuous integration environment.
</div> <br>
<div style="color: purple">
### `dynamic_ui_renderer`
<code>--dynamic-ui-renderer=<DynamicUIRenderer></code><br> <code>PANTS_DYNAMIC_UI_RENDERER</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">one of: <code>indicatif-spinner, experimental-prodash</code></span><br> <span style="color: green">default: <code>indicatif-spinner</code></span>
<br>
If `--dynamic-ui` is enabled, selects the renderer.
</div> <br>
<div style="color: purple">
### `tag`
<code>--tag="[[+-]tag1,tag2,..., [+-]tag1,tag2,..., ...]"</code><br> <code>PANTS_TAG</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
Include only targets with these tags (optional '+' prefix) or without these tags ('-' prefix). See [Advanced target selection](🔗).
</div> <br>
<div style="color: purple">
### `loop`
<code>--[no-]loop</code><br> <code>PANTS_LOOP</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
Run goals continuously as file changes are detected.
</div> <br>
## Advanced options
<div style="color: purple">
### `backend_packages`
<code>--backend-packages="['<str>', '<str>', ...]"</code><br> <code>PANTS_BACKEND_PACKAGES</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
Register functionality from these backends.
The backend packages must be present on the PYTHONPATH, typically because they are in the Pants core dist, in a plugin dist, or available as sources in the repo.
</div> <br>
<div style="color: purple">
### `plugins`
<code>--plugins="['<str>', '<str>', ...]"</code><br> <code>PANTS_PLUGINS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
Allow backends to be loaded from these plugins (usually released through PyPI). The default backends for each plugin will be loaded automatically. Other backends in a plugin can be loaded by listing them in `backend_packages` in the `[GLOBAL]` scope.
</div> <br>
<div style="color: purple">
### `plugins_force_resolve`
<code>--[no-]plugins-force-resolve</code><br> <code>PANTS_PLUGINS_FORCE_RESOLVE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
Re-resolve plugins, even if previously resolved.
</div> <br>
<div style="color: purple">
### `show_log_target`
<code>--[no-]show-log-target</code><br> <code>PANTS_SHOW_LOG_TARGET</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
Display the target where a log message originates in that log message's output. This can be helpful when paired with --log-levels-by-target.
</div> <br>
<div style="color: purple">
### `log_levels_by_target`
<code>--log-levels-by-target="{'key1': val1, 'key2': val2, ...}"</code><br> <code>PANTS_LOG_LEVELS_BY_TARGET</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>{}</code></span>
<br>
Set a more specific logging level for one or more logging targets. The names of logging targets are specified in log strings when the --show-log-target option is set. The logging levels are one of: "error", "warn", "info", "debug", "trace". All logging targets not specified here use the global log level set with --level. For example, you can set `--log-levels-by-target='{"workunit_store": "info", "pants.engine.rules": "warn"}'`.
</div> <br>
<div style="color: purple">
### `log_show_rust_3rdparty`
<code>--[no-]log-show-rust-3rdparty</code><br> <code>PANTS_LOG_SHOW_RUST_3RDPARTY</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
Whether to show/hide logging done by 3rdparty Rust crates used by the Pants engine.
</div> <br>
<div style="color: purple">
### `ignore_warnings`
<code>--ignore-warnings="['<str>', '<str>', ...]"</code><br> <code>PANTS_IGNORE_WARNINGS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
Ignore logs and warnings matching these strings.
Normally, Pants will look for literal matches from the start of the log/warning message, but you can prefix the ignore with `$regex$` for Pants to instead treat your string as a regex pattern. For example:
</div> <br>
<div style="color: purple">
### `pants_version`
<code>--pants-version=<str></code><br> <code>PANTS_VERSION</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code><pants_version></code></span>
<br>
Use this Pants version. Note that Pants only uses this to verify that you are using the requested version, as Pants cannot dynamically change the version it is using once the program is already running.
If you use the `./pants` script from [Installing Pants](🔗), however, changing the value in your `pants.toml` will cause the new version to be installed and run automatically.
Run `./pants --version` to check what is being used.
</div> <br>
<div style="color: purple">
### `pants_bin_name`
<code>--pants-bin-name=<str></code><br> <code>PANTS_BIN_NAME</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>./pants</code></span>
<br>
The name of the script or binary used to invoke Pants. Useful when printing help messages.
</div> <br>
<div style="color: purple">
### `pants_workdir`
<code>--pants-workdir=<dir></code><br> <code>PANTS_WORKDIR</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code><buildroot>/.pants.d</code></span>
<br>
Write intermediate logs and output files to this dir.
</div> <br>
<div style="color: purple">
### `pants_physical_workdir_base`
<code>--pants-physical-workdir-base=<dir></code><br> <code>PANTS_PHYSICAL_WORKDIR_BASE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
When set, a base directory in which to store `--pants-workdir` contents. If this option is a set, the workdir will be created as symlink into a per-workspace subdirectory.
</div> <br>
<div style="color: purple">
### `pants_distdir`
<code>--pants-distdir=<dir></code><br> <code>PANTS_DISTDIR</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code><buildroot>/dist</code></span>
<br>
Write end products, such as the results of `./pants package`, to this dir.
</div> <br>
<div style="color: purple">
### `pants_subprocessdir`
<code>--pants-subprocessdir=<str></code><br> <code>PANTS_SUBPROCESSDIR</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code><buildroot>/.pids</code></span>
<br>
The directory to use for tracking subprocess metadata. This should live outside of the dir used by `pants_workdir` to allow for tracking subprocesses that outlive the workdir data.
</div> <br>
<div style="color: purple">
### `pants_config_files`
<code>--pants-config-files="['<str>', '<str>', ...]"</code><br> <code>PANTS_CONFIG_FILES</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <pre>[ "<buildroot>/pants.toml" ]</pre></span>
<br>
Paths to Pants config files. This may only be set through the environment variable `PANTS_CONFIG_FILES` and the command line argument `--pants-config-files`; it will be ignored if in a config file like `pants.toml`.
</div> <br>
<div style="color: purple">
### `pantsrc`
<code>--[no-]pantsrc</code><br> <code>PANTS_PANTSRC</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>True</code></span>
<br>
Use pantsrc files located at the paths specified in the global option `pantsrc_files`.
</div> <br>
<div style="color: purple">
### `pantsrc_files`
<code>--pantsrc-files="[<path>, <path>, ...]"</code><br> <code>PANTS_PANTSRC_FILES</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <pre>[ "/etc/pantsrc", "~/.pants.rc", ".pants.rc" ]</pre></span>
<br>
Override config with values from these files, using syntax matching that of `--pants-config-files`.
</div> <br>
<div style="color: purple">
### `pythonpath`
<code>--pythonpath="['<str>', '<str>', ...]"</code><br> <code>PANTS_PYTHONPATH</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
Add these directories to PYTHONPATH to search for plugins. This does not impact the PYTHONPATH used by Pants when running your Python code.
</div> <br>
<div style="color: purple">
### `verify_config`
<code>--[no-]verify-config</code><br> <code>PANTS_VERIFY_CONFIG</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>True</code></span>
<br>
Verify that all config file values correspond to known options.
</div> <br>
<div style="color: purple">
### `stats_record_option_scopes`
<code>--stats-record-option-scopes="['<str>', '<str>', ...]"</code><br> <code>PANTS_STATS_RECORD_OPTION_SCOPES</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <pre>[ "*" ]</pre></span>
<br>
Option scopes to record in stats on run completion. Options may be selected by joining the scope and the option with a ^ character, i.e. to get option `pantsd` in the GLOBAL scope, you'd pass `GLOBAL^pantsd`. Add a '*' to the list to capture all known scopes.
</div> <br>
<div style="color: purple">
### `pants_ignore`
<code>--pants-ignore="['<str>', '<str>', ...]"</code><br> <code>PANTS_IGNORE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <pre>[ ".*/", "/dist/", "__pycache__" ]</pre></span>
<br>
Paths to ignore for all filesystem operations performed by pants (e.g. BUILD file scanning, glob matching, etc). Patterns use the gitignore syntax (https://git-scm.com/docs/gitignore). The `pants_distdir` and `pants_workdir` locations are automatically ignored. `pants_ignore` can be used in tandem with `pants_ignore_use_gitignore`; any rules specified here are applied after rules specified in a .gitignore file.
</div> <br>
<div style="color: purple">
### `pants_ignore_use_gitignore`
<code>--[no-]pants-ignore-use-gitignore</code><br> <code>PANTS_IGNORE_USE_GITIGNORE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>True</code></span>
<br>
Make use of a root .gitignore file when determining whether to ignore filesystem operations performed by Pants. If used together with `--pants-ignore`, any exclude/include patterns specified there apply after .gitignore rules.
</div> <br>
<div style="color: purple">
### `logdir`
<code>--logdir=<dir></code><br> <code>PANTS_LOGDIR</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
Write logs to files under this directory.
</div> <br>
<div style="color: purple">
### `pantsd_timeout_when_multiple_invocations`
<code>--pantsd-timeout-when-multiple-invocations=<float></code><br> <code>PANTS_PANTSD_TIMEOUT_WHEN_MULTIPLE_INVOCATIONS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>60.0</code></span>
<br>
The maximum amount of time to wait for the invocation to start until raising a timeout exception. Because pantsd currently does not support parallel runs, any prior running Pants command must be finished for the current one to start. To never timeout, use the value -1.
</div> <br>
<div style="color: purple">
### `pantsd_max_memory_usage`
<code>--pantsd-max-memory-usage=<memory_size></code><br> <code>PANTS_PANTSD_MAX_MEMORY_USAGE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>1GiB</code></span>
<br>
The maximum memory usage of the pantsd process.
When the maximum memory is exceeded, the daemon will restart gracefully, although all previous in-memory caching will be lost. Setting too low means that you may miss out on some caching, whereas setting too high may over-consume resources and may result in the operating system killing Pantsd due to memory overconsumption (e.g. via the OOM killer).
You can suffix with `GiB`, `MiB`, `KiB`, or `B` to indicate the unit, e.g. `2GiB` or `2.12GiB`. A bare number will be in bytes.
There is at most one pantsd process per workspace.
</div> <br>
<div style="color: purple">
### `print_stacktrace`
<code>--[no-]print-stacktrace</code><br> <code>PANTS_PRINT_STACKTRACE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
Print the full exception stack trace for any errors.
</div> <br>
<div style="color: purple">
### `engine_visualize_to`
<code>--engine-visualize-to=<dir_option></code><br> <code>PANTS_ENGINE_VISUALIZE_TO</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
A directory to write execution and rule graphs to as `dot` files. The contents of the directory will be overwritten if any filenames collide.
</div> <br>
<div style="color: purple">
### `pantsd_pailgun_port`
<code>--pantsd-pailgun-port=<int></code><br> <code>PANTS_PANTSD_PAILGUN_PORT</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>0</code></span>
<br>
The port to bind the Pants nailgun server to. Defaults to a random port.
</div> <br>
<div style="color: purple">
### `pantsd_invalidation_globs`
<code>--pantsd-invalidation-globs="['<str>', '<str>', ...]"</code><br> <code>PANTS_PANTSD_INVALIDATION_GLOBS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
Filesystem events matching any of these globs will trigger a daemon restart. Pants's own code, plugins, and `--pants-config-files` are inherently invalidated.
</div> <br>
<div style="color: purple">
### `rule_threads_core`
<code>--rule-threads-core=<int></code><br> <code>PANTS_RULE_THREADS_CORE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>max(2, #cores/2)</code></span>
<br>
The number of threads to keep active and ready to execute `@rule` logic (see also: `--rule-threads-max`).
Values less than 2 are not currently supported.
This value is independent of the number of processes that may be spawned in parallel locally (controlled by `--process-execution-local-parallelism`).
</div> <br>
<div style="color: purple">
### `rule_threads_max`
<code>--rule-threads-max=<int></code><br> <code>PANTS_RULE_THREADS_MAX</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
The maximum number of threads to use to execute `@rule` logic. Defaults to a small multiple of `--rule-threads-core`.
</div> <br>
<div style="color: purple">
### `local_store_dir`
<code>--local-store-dir=<str></code><br> <code>PANTS_LOCAL_STORE_DIR</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>$XDG_CACHE_HOME/lmdb_store</code></span>
<br>
Directory to use for the local file store, which stores the results of subprocesses run by Pants.
The path may be absolute or relative. If the directory is within the build root, be sure to include it in `--pants-ignore`.
</div> <br>
<div style="color: purple">
### `local_store_shard_count`
<code>--local-store-shard-count=<int></code><br> <code>PANTS_LOCAL_STORE_SHARD_COUNT</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>16</code></span>
<br>
The number of LMDB shards created for the local store. This setting also impacts the maximum size of stored files: see `--local-store-files-max-size-bytes` for more information.
Because LMDB allows only one simultaneous writer per database, the store is split into multiple shards to allow for more concurrent writers. The faster your disks are, the fewer shards you are likely to need for performance.
NB: After changing this value, you will likely want to manually clear the `--local-store-dir` directory to clear the space used by old shard layouts.
</div> <br>
<div style="color: purple">
### `local_store_processes_max_size_bytes`
<code>--local-store-processes-max-size-bytes=<int></code><br> <code>PANTS_LOCAL_STORE_PROCESSES_MAX_SIZE_BYTES</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>16000000000</code></span>
<br>
The maximum size in bytes of the local store containing process cache entries. Stored below `--local-store-dir`.
</div> <br>
<div style="color: purple">
### `local_store_files_max_size_bytes`
<code>--local-store-files-max-size-bytes=<int></code><br> <code>PANTS_LOCAL_STORE_FILES_MAX_SIZE_BYTES</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>256000000000</code></span>
<br>
The maximum size in bytes of the local store containing files. Stored below `--local-store-dir`.
NB: This size value bounds the total size of all files, but (due to sharding of the store on disk) it also bounds the per-file size to (VALUE / `--local-store-shard-count`).
This value doesn't reflect space allocated on disk, or RAM allocated (it may be reflected in VIRT but not RSS). However, the default is lower than you might otherwise choose because macOS creates core dumps that include MMAP'd pages, and setting this too high might cause core dumps to use an unreasonable amount of disk if they are enabled.
</div> <br>
<div style="color: purple">
### `local_store_directories_max_size_bytes`
<code>--local-store-directories-max-size-bytes=<int></code><br> <code>PANTS_LOCAL_STORE_DIRECTORIES_MAX_SIZE_BYTES</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>16000000000</code></span>
<br>
The maximum size in bytes of the local store containing directories. Stored below `--local-store-dir`.
</div> <br>
<div style="color: purple">
### `named_caches_dir`
<code>--named-caches-dir=<str></code><br> <code>PANTS_NAMED_CACHES_DIR</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>$XDG_CACHE_HOME/named_caches</code></span>
<br>
Directory to use for named global caches for tools and processes with trusted, concurrency-safe caches.
The path may be absolute or relative. If the directory is within the build root, be sure to include it in `--pants-ignore`.
</div> <br>
<div style="color: purple">
### `local_execution_root_dir`
<code>--local-execution-root-dir=<str></code><br> <code>PANTS_LOCAL_EXECUTION_ROOT_DIR</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code><tmp_dir></code></span>
<br>
Directory to use for local process execution sandboxing.
The path may be absolute or relative. If the directory is within the build root, be sure to include it in `--pants-ignore`.
</div> <br>
<div style="color: purple">
### `cache_content_behavior`
<code>--cache-content-behavior=<CacheContentBehavior></code><br> <code>PANTS_CACHE_CONTENT_BEHAVIOR</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">one of: <code>fetch, validate, defer</code></span><br> <span style="color: green">default: <code>fetch</code></span>
<br>
Controls how the content of cache entries is handled during process execution.
When using a remote cache, the `fetch` behavior will fetch remote cache content from the remote store before considering the cache lookup a hit, while the `validate` behavior will only validate (for either a local or remote cache) that the content exists, without fetching it.
The `defer` behavior, on the other hand, will neither fetch nor validate the cache content before calling a cache hit a hit. This "defers" actually fetching the cache entry until Pants needs it (which may be never).
The `defer` mode is the most network efficient (because it will completely skip network requests in many cases), followed by the `validate` mode (since it can still skip fetching the content if no consumer ends up needing it). But both the `validate` and `defer` modes rely on an experimental feature called "backtracking" to attempt to recover if content later turns out to be missing (`validate` has a much narrower window for backtracking though, since content would need to disappear between validation and consumption: generally, within one `pantsd` session).
</div> <br>
<div style="color: purple">
### `ca_certs_path`
<code>--ca-certs-path=<str></code><br> <code>PANTS_CA_CERTS_PATH</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
Path to a file containing PEM-format CA certificates used for verifying secure connections when downloading files required by a build.
</div> <br>
<div style="color: purple">
### `process_total_child_memory_usage`
<code>--process-total-child-memory-usage=<memory_size></code><br> <code>PANTS_PROCESS_TOTAL_CHILD_MEMORY_USAGE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
The maximum memory usage for all "pooled" child processes.
When set, this value participates in precomputing the pool size of child processes used by Pants (pooling is currently used only for the JVM). When not set, Pants will default to spawning `2 * --process-execution-local-parallelism` pooled processes.
A high value would result in a high number of child processes spawned, potentially overconsuming your resources and triggering the OS' OOM killer. A low value would mean a low number of child processes launched and therefore less parallelism for the tasks that need those processes.
If setting this value, consider also adjusting the value of the `--process-per-child-memory-usage` option.
You can suffix with `GiB`, `MiB`, `KiB`, or `B` to indicate the unit, e.g. `2GiB` or `2.12GiB`. A bare number will be in bytes.
</div> <br>
<div style="color: purple">
### `process_per_child_memory_usage`
<code>--process-per-child-memory-usage=<memory_size></code><br> <code>PANTS_PROCESS_PER_CHILD_MEMORY_USAGE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>512MiB</code></span>
<br>
The default memory usage for a single "pooled" child process.
Check the documentation for the `--process-total-child-memory-usage` for advice on how to choose an appropriate value for this option.
You can suffix with `GiB`, `MiB`, `KiB`, or `B` to indicate the unit, e.g. `2GiB` or `2.12GiB`. A bare number will be in bytes.
</div> <br>
<div style="color: purple">
### `process_execution_local_parallelism`
<code>--process-execution-local-parallelism=<int></code><br> <code>PANTS_PROCESS_EXECUTION_LOCAL_PARALLELISM</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>#cores</code></span>
<br>
Number of concurrent processes that may be executed locally.
This value is independent of the number of threads that may be used to execute the logic in `@rules` (controlled by `--rule-threads-core`).
</div> <br>
<div style="color: purple">
### `process_execution_remote_parallelism`
<code>--process-execution-remote-parallelism=<int></code><br> <code>PANTS_PROCESS_EXECUTION_REMOTE_PARALLELISM</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>128</code></span>
<br>
Number of concurrent processes that may be executed remotely.
</div> <br>
<div style="color: purple">
### `process_execution_cache_namespace`
<code>--process-execution-cache-namespace=<str></code><br> <code>PANTS_PROCESS_EXECUTION_CACHE_NAMESPACE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
The cache namespace for process execution. Change this value to invalidate every artifact's execution, or to prevent process cache entries from being (re)used for different usecases or users.
</div> <br>
<div style="color: purple">
### `process_execution_local_enable_nailgun`
<code>--[no-]process-execution-local-enable-nailgun</code><br> <code>PANTS_PROCESS_EXECUTION_LOCAL_ENABLE_NAILGUN</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>True</code></span>
<br>
Whether or not to use nailgun to run JVM requests that are marked as supporting nailgun.
</div> <br>
<div style="color: purple">
### `process_execution_graceful_shutdown_timeout`
<code>--process-execution-graceful-shutdown-timeout=<int></code><br> <code>PANTS_PROCESS_EXECUTION_GRACEFUL_SHUTDOWN_TIMEOUT</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>3</code></span>
<br>
The time in seconds to wait when gracefully shutting down an interactive process (such as one opened using `./pants run`) before killing it.
</div> <br>
<div style="color: purple">
### `remote_instance_name`
<code>--remote-instance-name=<str></code><br> <code>PANTS_REMOTE_INSTANCE_NAME</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
Name of the remote instance to use by remote caching and remote execution.
This is used by some remote servers for routing. Consult your remote server for whether this should be set.
You can also use `[GLOBAL].remote_auth_plugin` to provide a plugin to dynamically set this value.
</div> <br>
<div style="color: purple">
### `remote_ca_certs_path`
<code>--remote-ca-certs-path=<str></code><br> <code>PANTS_REMOTE_CA_CERTS_PATH</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
Path to a PEM file containing CA certificates used for verifying secure connections to `[GLOBAL].remote_execution_address` and `[GLOBAL].remote_store_address`.
If unspecified, Pants will attempt to auto-discover root CA certificates when TLS is enabled with remote execution and caching.
</div> <br>
<div style="color: purple">
### `remote_oauth_bearer_token_path`
<code>--remote-oauth-bearer-token-path=<str></code><br> <code>PANTS_REMOTE_OAUTH_BEARER_TOKEN_PATH</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
Path to a file containing an oauth token to use for gGRPC connections to `[GLOBAL].remote_execution_address` and `[GLOBAL].remote_store_address`.
If specified, Pants will add a header in the format `authorization: Bearer <token>`. You can also manually add this header via `[GLOBAL].remote_execution_headers` and `[GLOBAL].remote_store_headers`, or use `[GLOBAL].remote_auth_plugin` to provide a plugin to dynamically set the relevant headers. Otherwise, no authorization will be performed.
</div> <br>
<div style="color: purple">
### `remote_auth_plugin`
<code>--remote-auth-plugin=<str></code><br> <code>PANTS_REMOTE_AUTH_PLUGIN</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
Path to a plugin to dynamically configure remote caching and execution options.
Format: `path.to.module:my_func`. Pants will import your module and run your function. Update the `--pythonpath` option to ensure your file is loadable.
The function should take the kwargs `initial_store_headers: dict[str, str]`, `initial_execution_headers: dict[str, str]`, `options: Options` (from pants.option.options), `env: dict[str, str]`, and `prior_result: AuthPluginResult | None`. It should return an instance of `AuthPluginResult` from `pants.option.global_options`.
Pants will replace the headers it would normally use with whatever your plugin returns; usually, you should include the `initial_store_headers` and `initial_execution_headers` in your result so that options like `[GLOBAL].remote_store_headers` still work.
If you return `instance_name`, Pants will replace `[GLOBAL].remote_instance_name` with this value.
If the returned auth state is `AuthPluginState.UNAVAILABLE`, Pants will disable remote caching and execution.
If Pantsd is in use, `prior_result` will be the previous `AuthPluginResult` returned by your plugin, which allows you to reuse the result. Otherwise, if Pantsd has been restarted or is not used, the `prior_result` will be `None`.
</div> <br>
<div style="color: purple">
### `remote_store_address`
<code>--remote-store-address=<str></code><br> <code>PANTS_REMOTE_STORE_ADDRESS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
The URI of a server used for the remote file store.
Format: `scheme://host:port`. The supported schemes are `grpc` and `grpcs`, i.e. gRPC with TLS enabled. If `grpc` is used, TLS will be disabled.
</div> <br>
<div style="color: purple">
### `remote_store_headers`
<code>--remote-store-headers="{'key1': val1, 'key2': val2, ...}"</code><br> <code>PANTS_REMOTE_STORE_HEADERS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>{'user-agent': 'pants/<pants_version>'}</code></span>
<br>
Headers to set on remote store requests.
Format: header=value. Pants may add additional headers.
See `[GLOBAL].remote_execution_headers` as well.
</div> <br>
<div style="color: purple">
### `remote_store_chunk_bytes`
<code>--remote-store-chunk-bytes=<int></code><br> <code>PANTS_REMOTE_STORE_CHUNK_BYTES</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>1048576</code></span>
<br>
Size in bytes of chunks transferred to/from the remote file store.
</div> <br>
<div style="color: purple">
### `remote_store_chunk_upload_timeout_seconds`
<code>--remote-store-chunk-upload-timeout-seconds=<int></code><br> <code>PANTS_REMOTE_STORE_CHUNK_UPLOAD_TIMEOUT_SECONDS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>60</code></span>
<br>
Timeout (in seconds) for uploads of individual chunks to the remote file store.
</div> <br>
<div style="color: purple">
### `remote_store_rpc_retries`
<code>--remote-store-rpc-retries=<int></code><br> <code>PANTS_REMOTE_STORE_RPC_RETRIES</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>2</code></span>
<br>
Number of times to retry any RPC to the remote store before giving up.
</div> <br>
<div style="color: purple">
### `remote_store_rpc_concurrency`
<code>--remote-store-rpc-concurrency=<int></code><br> <code>PANTS_REMOTE_STORE_RPC_CONCURRENCY</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>128</code></span>
<br>
The number of concurrent requests allowed to the remote store service.
</div> <br>
<div style="color: purple">
### `remote_store_batch_api_size_limit`
<code>--remote-store-batch-api-size-limit=<int></code><br> <code>PANTS_REMOTE_STORE_BATCH_API_SIZE_LIMIT</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>4194304</code></span>
<br>
The maximum total size of blobs allowed to be sent in a single batch API call to the remote store.
</div> <br>
<div style="color: purple">
### `remote_cache_warnings`
<code>--remote-cache-warnings=<RemoteCacheWarningsBehavior></code><br> <code>PANTS_REMOTE_CACHE_WARNINGS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">one of: <code>ignore, first_only, backoff</code></span><br> <span style="color: green">default: <code>backoff</code></span>
<br>
How frequently to log remote cache failures at the `warn` log level.
All errors not logged at the `warn` level will instead be logged at the `debug` level.
</div> <br>
<div style="color: purple">
### `remote_cache_rpc_concurrency`
<code>--remote-cache-rpc-concurrency=<int></code><br> <code>PANTS_REMOTE_CACHE_RPC_CONCURRENCY</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>128</code></span>
<br>
The number of concurrent requests allowed to the remote cache service.
</div> <br>
<div style="color: purple">
### `remote_cache_read_timeout_millis`
<code>--remote-cache-read-timeout-millis=<int></code><br> <code>PANTS_REMOTE_CACHE_READ_TIMEOUT_MILLIS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>1500</code></span>
<br>
Timeout value for remote cache lookups in milliseconds.
</div> <br>
<div style="color: purple">
### `remote_execution_address`
<code>--remote-execution-address=<str></code><br> <code>PANTS_REMOTE_EXECUTION_ADDRESS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
The URI of a server used as a remote execution scheduler.
Format: `scheme://host:port`. The supported schemes are `grpc` and `grpcs`, i.e. gRPC with TLS enabled. If `grpc` is used, TLS will be disabled.
You must also set `[GLOBAL].remote_store_address`, which will often be the same value.
</div> <br>
<div style="color: purple">
### `remote_execution_extra_platform_properties`
<code>--remote-execution-extra-platform-properties="['<str>', '<str>', ...]"</code><br> <code>PANTS_REMOTE_EXECUTION_EXTRA_PLATFORM_PROPERTIES</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
Platform properties to set on remote execution requests. Format: property=value. Multiple values should be specified as multiple occurrences of this flag. Pants itself may add additional platform properties.
</div> <br>
<div style="color: purple">
### `remote_execution_headers`
<code>--remote-execution-headers="{'key1': val1, 'key2': val2, ...}"</code><br> <code>PANTS_REMOTE_EXECUTION_HEADERS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>{'user-agent': 'pants/<pants_version>'}</code></span>
<br>
Headers to set on remote execution requests. Format: header=value. Pants may add additional headers.
See `[GLOBAL].remote_store_headers` as well.
</div> <br>
<div style="color: purple">
### `remote_execution_overall_deadline_secs`
<code>--remote-execution-overall-deadline-secs=<int></code><br> <code>PANTS_REMOTE_EXECUTION_OVERALL_DEADLINE_SECS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>3600</code></span>
<br>
Overall timeout in seconds for each remote execution request from time of submission
</div> <br>
<div style="color: purple">
### `remote_execution_rpc_concurrency`
<code>--remote-execution-rpc-concurrency=<int></code><br> <code>PANTS_REMOTE_EXECUTION_RPC_CONCURRENCY</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>128</code></span>
<br>
The number of concurrent requests allowed to the remote execution service.
</div> <br>
<div style="color: purple">
### `watch_filesystem`
<code>--[no-]watch-filesystem</code><br> <code>PANTS_WATCH_FILESYSTEM</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>True</code></span>
<br>
Set to False if Pants should not watch the filesystem for changes. `pantsd` or `loop` may not be enabled.
</div> <br>
<div style="color: purple">
### `unmatched_build_file_globs`
<code>--unmatched-build-file-globs=<UnmatchedBuildFileGlobs></code><br> <code>PANTS_UNMATCHED_BUILD_FILE_GLOBS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">one of: <code>warn, error</code></span><br> <span style="color: green">default: <code>warn</code></span>
<br>
What to do when files and globs specified in BUILD files, such as in the `sources` field, cannot be found.
This usually happens when the files do not exist on your machine. It can also happen if they are ignored by the `[GLOBAL].pants_ignore` option, which causes the files to be invisible to Pants.
</div> <br>
<div style="color: purple">
### `unmatched_cli_globs`
<code>--unmatched-cli-globs=<UnmatchedCliGlobs></code><br> <code>PANTS_UNMATCHED_CLI_GLOBS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">one of: <code>ignore, warn, error</code></span><br> <span style="color: green">default: <code>error</code></span>
<br>
What to do when command line arguments, e.g. files and globs like `dir::`, cannot be found.
This usually happens when the files do not exist on your machine. It can also happen if they are ignored by the `[GLOBAL].pants_ignore` option, which causes the files to be invisible to Pants.
</div> <br>
<div style="color: purple">
### `build_patterns`
<code>--build-patterns="['<str>', '<str>', ...]"</code><br> <code>PANTS_BUILD_PATTERNS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <pre>[ "BUILD", "BUILD.*" ]</pre></span>
<br>
The naming scheme for BUILD files, i.e. where you define targets.
This only sets the naming scheme, not the directory paths to look for. To add ignore patterns, use the option `[GLOBAL].build_ignore`.
You may also need to update the option `[tailor].build_file_name` so that it is compatible with this option.
</div> <br>
<div style="color: purple">
### `build_ignore`
<code>--build-ignore="['<str>', '<str>', ...]"</code><br> <code>PANTS_BUILD_IGNORE</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
Path globs or literals to ignore when identifying BUILD files.
This does not affect any other filesystem operations; use `--pants-ignore` for that instead.
</div> <br>
<div style="color: purple">
### `build_file_prelude_globs`
<code>--build-file-prelude-globs="['<str>', '<str>', ...]"</code><br> <code>PANTS_BUILD_FILE_PRELUDE_GLOBS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
Python files to evaluate and whose symbols should be exposed to all BUILD files. See [Macros](🔗).
</div> <br>
<div style="color: purple">
### `subproject_roots`
<code>--subproject-roots="['<str>', '<str>', ...]"</code><br> <code>PANTS_SUBPROJECT_ROOTS</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
Paths that correspond with build roots for any subproject that this project depends on.
</div> <br>
<div style="color: purple">
### `loop_max`
<code>--loop-max=<int></code><br> <code>PANTS_LOOP_MAX</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>4294967296</code></span>
<br>
The maximum number of times to loop when `--loop` is specified.
</div> <br>
<div style="color: purple">
### `streaming_workunits_report_interval`
<code>--streaming-workunits-report-interval=<float></code><br> <code>PANTS_STREAMING_WORKUNITS_REPORT_INTERVAL</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>1.0</code></span>
<br>
Interval in seconds between when streaming workunit event receivers will be polled.
</div> <br>
<div style="color: purple">
### `streaming_workunits_level`
<code>--streaming-workunits-level=<LogLevel></code><br> <code>PANTS_STREAMING_WORKUNITS_LEVEL</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">one of: <code>trace, debug, info, warn, error</code></span><br> <span style="color: green">default: <code>debug</code></span>
<br>
The level of workunits that will be reported to streaming workunit event receivers.
Workunits form a tree, and even when workunits are filtered out by this setting, the workunit tree structure will be preserved (by adjusting the parent pointers of the remaining workunits).
</div> <br>
<div style="color: purple">
### `streaming_workunits_complete_async`
<code>--[no-]streaming-workunits-complete-async</code><br> <code>PANTS_STREAMING_WORKUNITS_COMPLETE_ASYNC</code><br>
</div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>True</code></span>
<br>
True if stats recording should be allowed to complete asynchronously when `pantsd` is enabled. When `pantsd` is disabled, stats recording is always synchronous. To reduce data loss, this flag defaults to false inside of containers, such as when run with Docker.
</div> <br>
## Deprecated options
<div style="color: purple">
### `remote_cache_eager_fetch`
<code>--[no-]remote-cache-eager-fetch</code><br> <code>PANTS_REMOTE_CACHE_EAGER_FETCH</code><br>
</div>
<div style="padding-left: 2em;">
<span style="color: green">default: <code>True</code></span>
<p style="color: darkred">Deprecated, is scheduled to be removed in version: 2.15.0.dev1.<br>Use the `cache_content_behavior` option instead.</p>
<br>
Eagerly fetch relevant content from the remote store instead of lazily fetching.
This may result in worse performance, but reduce the frequency of errors encountered by reducing the surface area of when remote caching is used.
</div> <br>
<div style="color: purple">
### `use_deprecated_directory_cli_args_semantics`
<code>--[no-]use-deprecated-directory-cli-args-semantics</code><br> <code>PANTS_USE_DEPRECATED_DIRECTORY_CLI_ARGS_SEMANTICS</code><br>
</div>
<div style="padding-left: 2em;">
<span style="color: green">default: <code>False</code></span>
<p style="color: darkred">Deprecated, is scheduled to be removed in version: 2.15.0.dev0.<br>If `use_deprecated_directory_cli_args_semantics` is already set explicitly to `false`, simply delete the option from `pants.toml` because `false` is now the default.
If set to true, removing the option will cause directory arguments like `./pants test project/dir` to now match all files and targets in the directory, whereas before it matched the target `project/dir:dir`. To keep the old semantics, use the explicit address syntax.</p>
<br>
If true, Pants will use the old, deprecated semantics for directory arguments like `./pants test dir`: directories are shorthand for the target `dir:dir`, i.e. the target that leaves off `name=`.
If false, Pants will use the new semantics: directory arguments will match all files and targets in the directory, e.g. `./pants test dir` will run all tests in `dir`.
This also impacts the behavior of the `tailor` goal. If this option is true, `./pants tailor dir` will run over `dir` and all recursive sub-directories. If false, specifying a directory will only add targets for that directory.
</div> <br>
<div style="color: purple">
### `use_deprecated_pex_binary_run_semantics`
<code>--[no-]use-deprecated-pex-binary-run-semantics</code><br> <code>PANTS_USE_DEPRECATED_PEX_BINARY_RUN_SEMANTICS</code><br>
</div>
<div style="padding-left: 2em;">
<span style="color: green">default: <code>False</code></span>
<p style="color: darkred">Deprecated, is scheduled to be removed in version: 2.15.0.dev0.<br>If `use_deprecated_pex_binary_run_semantics` is already set explicitly to `false`, simply delete the option from `pants.toml` because `false` is now the default.
If set to `true`, removing the option will cause `run` on a `pex_binary` to package and run the built PEX file. Additionally, the `pex_binary` must be referred to by its address. To keep the old `run` semantics, use `run` on the relevant `python_source` target.</p>
<br>
If `true`, `run`ning a `pex_binary` will run your firstparty code by copying sources to a sandbox (while still using a PEX for thirdparty dependencies). Additionally, you can refer to the `pex_binary` using the value of its `entry_point` field (if it is a filename).
If `false`, `run`ning a `pex_binary` will build the PEX via `package` and run it directly. This makes `run` equivalent to using `package` and running the artifact. Additionally, the binary must be `run` using the `pex_binary`'s address, as passing a filename to `run` will run the `python_source`.
Note that support has been added to Pants to allow you to `run` any `python_source`, so setting this to `true` should be reserved for maintaining backwards-compatibility with previous versions of Pants. Additionally, you can remove any `pex_binary` targets that exist solely for running Python code (and aren't meant to be packaged).
</div> <br>