Global options
Options to control the overall behavior of Pants.
Backend: pants.core
Config section: [GLOBAL]
Basic options
colors
--[no-]colors
PANTS_COLORS
[GLOBAL]
colors = <bool>
False
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.
concurrent
--[no-]concurrent
PANTS_CONCURRENT
[GLOBAL]
concurrent = <bool>
False
Enable concurrent runs of Pants. With this enabled, Pants will start up all concurrent invocations (e.g. in other terminals) without pantsd. As a result, enabling this option will increase the per-run startup cost, but will not block subsequent invocations.
dynamic_ui
--[no-]dynamic-ui
PANTS_DYNAMIC_UI
[GLOBAL]
dynamic_ui = <bool>
True
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.
dynamic_ui_renderer
--dynamic-ui-renderer=<DynamicUIRenderer>
PANTS_DYNAMIC_UI_RENDERER
[GLOBAL]
dynamic_ui_renderer = <DynamicUIRenderer>
indicatif-spinner, experimental-prodash
default:
indicatif-spinner
If --dynamic-ui
is enabled, selects the renderer.
keep_sandboxes
--keep-sandboxes=<KeepSandboxes>
PANTS_KEEP_SANDBOXES
[GLOBAL]
keep_sandboxes = <KeepSandboxes>
always, on_failure, never
default:
never
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.
level
-l=<LogLevel>, --level=<LogLevel>
PANTS_LEVEL
[GLOBAL]
level = <LogLevel>
trace, debug, info, warn, error
default:
info
Set the logging level.
local_cache
--[no-]local-cache
PANTS_LOCAL_CACHE
[GLOBAL]
local_cache = <bool>
True
Whether to cache process executions in a local cache persisted to disk at --local-store-dir
.
loop
--[no-]loop
PANTS_LOOP
[GLOBAL]
loop = <bool>
False
Run goals continuously as file changes are detected.
native_options_validation
--native-options-validation=<NativeOptionsValidation>
PANTS_NATIVE_OPTIONS_VALIDATION
[GLOBAL]
native_options_validation = <NativeOptionsValidation>
ignore, warning, error
default:
warning
Pants is switching its option parsing system from a legacy parser written in Python to a new one written in Rust.
The results of parsing a given option by each system should be identical. However during a transition period we will run both parsers and compare their results. This option controls how to report discrepancies that arise.
-
error
: Discrepancies will cause Pants to exit. -
warning
: Discrepancies will be logged but Pants will continue. -
ignore
: A last resort to turn off this check entirely.
If you encounter discrepancies that are not easily resolvable, please reach out to us on Slack or file an issue: https://www.pantsbuild.org/community/getting-help.
The native parser will become the default in 2.23.x, and the legacy parser will be removed in 2.24.x. So it is imperative that we find out about any discrepancies during this transition period.
pantsd
--[no-]pantsd
PANTS_PANTSD
[GLOBAL]
pantsd = <bool>
True
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.
remote_cache_read
--[no-]remote-cache-read
PANTS_REMOTE_CACHE_READ
[GLOBAL]
remote_cache_read = <bool>
False
Whether to enable reading from a remote cache.
This cannot be used at the same time as [GLOBAL].remote_execution
.
remote_cache_write
--[no-]remote-cache-write
PANTS_REMOTE_CACHE_WRITE
[GLOBAL]
remote_cache_write = <bool>
False
Whether to enable writing results to a remote cache.
This cannot be used at the same time as [GLOBAL].remote_execution
.
remote_execution
--[no-]remote-execution
PANTS_REMOTE_EXECUTION
[GLOBAL]
remote_execution = <bool>
False
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.
remote_provider
--remote-provider=<RemoteProvider>
PANTS_REMOTE_PROVIDER
[GLOBAL]
remote_provider = <RemoteProvider>
reapi, experimental-file, experimental-github-actions-cache
default:
reapi
The type of provider to use, if using a remote cache and/or remote execution, See https://www.pantsbuild.org/2.22/docs/using-pants/remote-caching-and-execution for details.
Each provider supports different remote_store_address
and (optional) remote_execution_address
URIs.
Supported values:
-
reapi
: a server using the Remote Execution API (https://github.com/bazelbuild/remote-apis) (supported schemes for URIs:grpc://
,grpcs://
) -
experimental-file
: a directory mapped on the current machine (supported schemes for URIs:file://
) -
experimental-github-actions-cache
: the GitHub Actions caching service (supported schemes for URIs:http://
,https://
)
session_end_tasks_timeout
--session-end-tasks-timeout=<float>
PANTS_SESSION_END_TASKS_TIMEOUT
[GLOBAL]
session_end_tasks_timeout = <float>
3.0
The time in seconds to wait for still-running "session end" tasks to complete before finishing completion of a Pants invocation. "Session end" tasks include, for example, writing data that was generated during the applicable Pants invocation to a configured remote cache.
spec_files
--spec-files="['<str>', '<str>', ...]"
PANTS_SPEC_FILES
[GLOBAL]
spec_files = [
'<str>',
'<str>',
...,
]
[]
Read additional specs (target addresses, files, and/or globs), one per line, from these files.
tag
--tag="[[+-]tag1,tag2,..., [+-]tag1,tag2,..., ...]"
PANTS_TAG
[GLOBAL]
tag = [
[+-]tag1,tag2,...,
[+-]tag1,tag2,...,
...,
]
[]
Include only targets with these tags (optional '+' prefix) or without these tags ('-' prefix). See https://www.pantsbuild.org/2.22/docs/using-pants/advanced-target-selection.
Advanced options
backend_packages
--backend-packages="['<str>', '<str>', ...]"
PANTS_BACKEND_PACKAGES
[GLOBAL]
backend_packages = [
'<str>',
'<str>',
...,
]
[]
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.
build_file_prelude_globs
--build-file-prelude-globs="['<str>', '<str>', ...]"
PANTS_BUILD_FILE_PRELUDE_GLOBS
[GLOBAL]
build_file_prelude_globs = [
'<str>',
'<str>',
...,
]
[]
Python files to evaluate and whose symbols should be exposed to all BUILD files. See https://www.pantsbuild.org/2.22/docs/writing-plugins/macros.
build_ignore
--build-ignore="['<str>', '<str>', ...]"
PANTS_BUILD_IGNORE
[GLOBAL]
build_ignore = [
'<str>',
'<str>',
...,
]
[]
Path globs or literals to ignore when identifying BUILD files.
This does not affect any other filesystem operations; use --pants-ignore
for that instead.
build_patterns
--build-patterns="['<str>', '<str>', ...]"
PANTS_BUILD_PATTERNS
[GLOBAL]
build_patterns = [
'<str>',
'<str>',
...,
]
[ "BUILD", "BUILD.*" ]
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.
ca_certs_path
--ca-certs-path=<str>
PANTS_CA_CERTS_PATH
[GLOBAL]
ca_certs_path = <str>
None
Path to a file containing PEM-format CA certificates used for verifying secure connections when downloading files required by a build.
Even when using the docker_environment
and remote_environment
targets, this path will be read from the local host, and those certs will be used in the environment.
This option cannot be overridden via environment targets, so if you need a different value than what the rest of your organization is using, override the value via an environment variable, CLI argument, or .pants.rc
file. See https://www.pantsbuild.org/2.22/docs/using-pants/key-concepts/options.
cache_content_behavior
--cache-content-behavior=<CacheContentBehavior>
PANTS_CACHE_CONTENT_BEHAVIOR
[GLOBAL]
cache_content_behavior = <CacheContentBehavior>
fetch, validate, defer
default:
fetch
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).
docker_execution
--[no-]docker-execution
PANTS_DOCKER_EXECUTION
[GLOBAL]
docker_execution = <bool>
True
If true, docker_environment
targets can be used to run builds inside a Docker container.
If false, anytime a docker_environment
target is used, Pants will instead fallback to whatever the target's fallback_environment
field is set to.
This can be useful, for example, if you want to always use Docker locally, but disable it in CI, or vice versa.
engine_visualize_to
--engine-visualize-to=<dir_option>
PANTS_ENGINE_VISUALIZE_TO
[GLOBAL]
engine_visualize_to = <dir_option>
None
A directory to write execution and rule graphs to as dot
files. The contents of the directory will be overwritten if any filenames collide.
ignore_warnings
--ignore-warnings="['<str>', '<str>', ...]"
PANTS_IGNORE_WARNINGS
[GLOBAL]
ignore_warnings = [
'<str>',
'<str>',
...,
]
[]
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:
ignore_warnings = [
"DEPRECATED: option 'config' in scope 'flake8' will be removed",
'$regex$:No files\s*'
]
local_execution_root_dir
--local-execution-root-dir=<str>
PANTS_LOCAL_EXECUTION_ROOT_DIR
[GLOBAL]
local_execution_root_dir = <str>
<tmp_dir>
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
.
local_store_dir
--local-store-dir=<str>
PANTS_LOCAL_STORE_DIR
[GLOBAL]
local_store_dir = <str>
$XDG_CACHE_HOME/pants/lmdb_store
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
.
local_store_directories_max_size_bytes
--local-store-directories-max-size-bytes=<int>
PANTS_LOCAL_STORE_DIRECTORIES_MAX_SIZE_BYTES
[GLOBAL]
local_store_directories_max_size_bytes = <int>
16000000000
The maximum size in bytes of the local store containing directories. Stored below --local-store-dir
.
local_store_files_max_size_bytes
--local-store-files-max-size-bytes=<int>
PANTS_LOCAL_STORE_FILES_MAX_SIZE_BYTES
[GLOBAL]
local_store_files_max_size_bytes = <int>
256000000000
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.
local_store_processes_max_size_bytes
--local-store-processes-max-size-bytes=<int>
PANTS_LOCAL_STORE_PROCESSES_MAX_SIZE_BYTES
[GLOBAL]
local_store_processes_max_size_bytes = <int>
16000000000
The maximum size in bytes of the local store containing process cache entries. Stored below --local-store-dir
.
local_store_shard_count
--local-store-shard-count=<int>
PANTS_LOCAL_STORE_SHARD_COUNT
[GLOBAL]
local_store_shard_count = <int>
16
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.
log_levels_by_target
--log-levels-by-target="{'key1': val1, 'key2': val2, ...}"
PANTS_LOG_LEVELS_BY_TARGET
[GLOBAL.log_levels_by_target]
key1 = val1
key2 = val2
...
{}
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"}'
.
log_show_rust_3rdparty
--[no-]log-show-rust-3rdparty
PANTS_LOG_SHOW_RUST_3RDPARTY
[GLOBAL]
log_show_rust_3rdparty = <bool>
False
Whether to show/hide logging done by 3rdparty Rust crates used by the Pants engine.
logdir
--logdir=<dir>
PANTS_LOGDIR
[GLOBAL]
logdir = <dir>
None
Write logs to files under this directory.
loop_max
--loop-max=<int>
PANTS_LOOP_MAX
[GLOBAL]
loop_max = <int>
4294967296
The maximum number of times to loop when --loop
is specified.
named_caches_dir
--named-caches-dir=<str>
PANTS_NAMED_CACHES_DIR
[GLOBAL]
named_caches_dir = <str>
$XDG_CACHE_HOME/pants/named_caches
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
.
pants_bin_name
--pants-bin-name=<str>
PANTS_BIN_NAME
[GLOBAL]
pants_bin_name = <str>
pants
The name of the script or binary used to invoke Pants. Useful when printing help messages.
pants_config_files
--pants-config-files="['<str>', '<str>', ...]"
PANTS_CONFIG_FILES
[GLOBAL]
pants_config_files = [
'<str>',
'<str>',
...,
]
[ "<buildroot>/pants.toml" ]
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
.
pants_distdir
--pants-distdir=<dir>
PANTS_DISTDIR
[GLOBAL]
pants_distdir = <dir>
<buildroot>/dist
Write end products, such as the results of pants package
, to this dir.
pants_ignore
--pants-ignore="['<str>', '<str>', ...]"
PANTS_IGNORE
[GLOBAL]
pants_ignore = [
'<str>',
'<str>',
...,
]
[ ".*/", "/dist/", "__pycache__", "!.semgrep/", "!.github/" ]
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.
pants_ignore_use_gitignore
--[no-]pants-ignore-use-gitignore
PANTS_IGNORE_USE_GITIGNORE
[GLOBAL]
pants_ignore_use_gitignore = <bool>
True
Include patterns from .gitignore
, .git/info/exclude
, and the global gitignore files in the option [GLOBAL].pants_ignore
, which is used for Pants to ignore filesystem operations on those patterns.
Patterns from [GLOBAL].pants_ignore
take precedence over these files' rules. For example, you can use !my_pattern
in pants_ignore
to have Pants operate on files that are gitignored.
Warning: this does not yet support reading nested gitignore files.
pants_physical_workdir_base
--pants-physical-workdir-base=<dir>
PANTS_PHYSICAL_WORKDIR_BASE
[GLOBAL]
pants_physical_workdir_base = <dir>
None
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.
pants_subprocessdir
--pants-subprocessdir=<str>
PANTS_SUBPROCESSDIR
[GLOBAL]
pants_subprocessdir = <str>
<buildroot>/.pants.d/pids
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.
pants_version
--pants-version=<str>
PANTS_VERSION
[GLOBAL]
pants_version = <str>
<pants_version>
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 https://www.pantsbuild.org/2.22/docs/getting-started/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.
pants_workdir
--pants-workdir=<dir>
PANTS_WORKDIR
[GLOBAL]
pants_workdir = <dir>
<buildroot>/.pants.d/workdir
Write intermediate logs and output files to this dir.
pantsd_invalidation_globs
--pantsd-invalidation-globs="['<str>', '<str>', ...]"
PANTS_PANTSD_INVALIDATION_GLOBS
[GLOBAL]
pantsd_invalidation_globs = [
'<str>',
'<str>',
...,
]
[]
Filesystem events matching any of these globs will trigger a daemon restart. Pants's own code, plugins, and --pants-config-files
are inherently invalidated.
pantsd_max_memory_usage
--pantsd-max-memory-usage=<memory_size>
PANTS_PANTSD_MAX_MEMORY_USAGE
[GLOBAL]
pantsd_max_memory_usage = <memory_size>
4GiB
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.
pantsd_pailgun_port
--pantsd-pailgun-port=<int>
PANTS_PANTSD_PAILGUN_PORT
[GLOBAL]
pantsd_pailgun_port = <int>
0
The port to bind the Pants nailgun server to. Defaults to a random port.
pantsd_timeout_when_multiple_invocations
--pantsd-timeout-when-multiple-invocations=<float>
PANTS_PANTSD_TIMEOUT_WHEN_MULTIPLE_INVOCATIONS
[GLOBAL]
pantsd_timeout_when_multiple_invocations = <float>
60.0
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.
pantsrc
--[no-]pantsrc
PANTS_PANTSRC
[GLOBAL]
pantsrc = <bool>
True
Use pantsrc files located at the paths specified in the global option pantsrc_files
.
pantsrc_files
--pantsrc-files="[<path>, <path>, ...]"
PANTS_PANTSRC_FILES
[GLOBAL]
pantsrc_files = [
<path>,
<path>,
...,
]
[ "/etc/pantsrc", "~/.pants.rc", ".pants.rc" ]
Override config with values from these files, using syntax matching that of --pants-config-files
.
plugins
--plugins="['<str>', '<str>', ...]"
PANTS_PLUGINS
[GLOBAL]
plugins = [
'<str>',
'<str>',
...,
]
[]
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.
plugins_force_resolve
--[no-]plugins-force-resolve
PANTS_PLUGINS_FORCE_RESOLVE
[GLOBAL]
plugins_force_resolve = <bool>
False
Re-resolve plugins, even if previously resolved.
print_stacktrace
--[no-]print-stacktrace
PANTS_PRINT_STACKTRACE
[GLOBAL]
print_stacktrace = <bool>
False
Print the full exception stack trace for any errors.
process_execution_cache_namespace
--process-execution-cache-namespace=<str>
PANTS_PROCESS_EXECUTION_CACHE_NAMESPACE
[GLOBAL]
process_execution_cache_namespace = <str>
None
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 use-cases or users.
process_execution_graceful_shutdown_timeout
--process-execution-graceful-shutdown-timeout=<int>
PANTS_PROCESS_EXECUTION_GRACEFUL_SHUTDOWN_TIMEOUT
[GLOBAL]
process_execution_graceful_shutdown_timeout = <int>
3
The time in seconds to wait when gracefully shutting down an interactive process (such as one opened using pants run
) before killing it.
process_execution_local_enable_nailgun
--[no-]process-execution-local-enable-nailgun
PANTS_PROCESS_EXECUTION_LOCAL_ENABLE_NAILGUN
[GLOBAL]
process_execution_local_enable_nailgun = <bool>
True
Whether or not to use nailgun to run JVM requests that are marked as supporting nailgun.
process_execution_local_parallelism
--process-execution-local-parallelism=<int>
PANTS_PROCESS_EXECUTION_LOCAL_PARALLELISM
[GLOBAL]
process_execution_local_parallelism = <int>
#cores
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
).
process_execution_remote_parallelism
--process-execution-remote-parallelism=<int>
PANTS_PROCESS_EXECUTION_REMOTE_PARALLELISM
[GLOBAL]
process_execution_remote_parallelism = <int>
128
Number of concurrent processes that may be executed remotely.
process_per_child_memory_usage
--process-per-child-memory-usage=<memory_size>
PANTS_PROCESS_PER_CHILD_MEMORY_USAGE
[GLOBAL]
process_per_child_memory_usage = <memory_size>
512MiB
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.
process_total_child_memory_usage
--process-total-child-memory-usage=<memory_size>
PANTS_PROCESS_TOTAL_CHILD_MEMORY_USAGE
[GLOBAL]
process_total_child_memory_usage = <memory_size>
None
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.
pythonpath
--pythonpath="['<str>', '<str>', ...]"
PANTS_PYTHONPATH
[GLOBAL]
pythonpath = [
'<str>',
'<str>',
...,
]
[]
Add these directories to PYTHONPATH to search for plugins. This does not impact the PYTHONPATH used by Pants when running your Python code.
remote_ca_certs_path
--remote-ca-certs-path=<str>
PANTS_REMOTE_CA_CERTS_PATH
[GLOBAL]
remote_ca_certs_path = <str>
None
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.
remote_cache_rpc_concurrency
--remote-cache-rpc-concurrency=<int>
PANTS_REMOTE_CACHE_RPC_CONCURRENCY
[GLOBAL]
remote_cache_rpc_concurrency = <int>
128
The number of concurrent requests allowed to the remote cache service.
remote_cache_rpc_timeout_millis
--remote-cache-rpc-timeout-millis=<int>
PANTS_REMOTE_CACHE_RPC_TIMEOUT_MILLIS
[GLOBAL]
remote_cache_rpc_timeout_millis = <int>
1500
Timeout value for remote cache RPCs in milliseconds.
remote_cache_warnings
--remote-cache-warnings=<RemoteCacheWarningsBehavior>
PANTS_REMOTE_CACHE_WARNINGS
[GLOBAL]
remote_cache_warnings = <RemoteCacheWarningsBehavior>
ignore, first_only, backoff, always
default:
backoff
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.
remote_client_certs_path
--remote-client-certs-path=<str>
PANTS_REMOTE_CLIENT_CERTS_PATH
[GLOBAL]
remote_client_certs_path = <str>
None
Path to a PEM file containing client certificates used for verifying secure connections to [GLOBAL].remote_execution_address
and [GLOBAL].remote_store_address
when using client authentication (mTLS).
If unspecified, will use regular TLS. Requires remote_client_key_path
to also be specified.
remote_client_key_path
--remote-client-key-path=<str>
PANTS_REMOTE_CLIENT_KEY_PATH
[GLOBAL]
remote_client_key_path = <str>
None
Path to a PEM file containing a private key used for verifying secure connections to [GLOBAL].remote_execution_address
and [GLOBAL].remote_store_address
when using client authentication (mTLS).
If unspecified, will use regular TLS. Requires remote_client_certs_path
to also be specified.
remote_execution_address
--remote-execution-address=<str>
PANTS_REMOTE_EXECUTION_ADDRESS
[GLOBAL]
remote_execution_address = <str>
None
The URI of a server/entity used as a remote execution scheduler. The supported URIs depends on the value of the remote_provider
option.
You must also set [GLOBAL].remote_store_address
, which will often be the same value.
remote_execution_append_only_caches_base_path
--remote-execution-append-only-caches-base-path=<str>
PANTS_REMOTE_EXECUTION_APPEND_ONLY_CACHES_BASE_PATH
[GLOBAL]
remote_execution_append_only_caches_base_path = <str>
None
Sets the base path to use when setting up an append-only cache for a process running remotely. If this option is not set, then append-only caches will not be used with remote execution. The option should be set to the absolute path of a writable directory in the remote execution environment where Pants can create append-only caches for use with remotely executing processes.
remote_execution_extra_platform_properties
--remote-execution-extra-platform-properties="['<str>', '<str>', ...]"
PANTS_REMOTE_EXECUTION_EXTRA_PLATFORM_PROPERTIES
[GLOBAL]
remote_execution_extra_platform_properties = [
'<str>',
'<str>',
...,
]
[]
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.
If you are using the remote_environment
target mechanism, set this value as a field on the target instead. This option will be ignored.
remote_execution_headers
--remote-execution-headers="{'key1': val1, 'key2': val2, ...}"
PANTS_REMOTE_EXECUTION_HEADERS
[GLOBAL.remote_execution_headers]
key1 = val1
key2 = val2
...
{'user-agent': 'pants/<pants_version>'}
Headers to set on remote execution requests. Format: header=value. Pants may add additional headers.
See [GLOBAL].remote_store_headers
as well.
remote_execution_overall_deadline_secs
--remote-execution-overall-deadline-secs=<int>
PANTS_REMOTE_EXECUTION_OVERALL_DEADLINE_SECS
[GLOBAL]
remote_execution_overall_deadline_secs = <int>
3600
Overall timeout in seconds for each remote execution request from time of submission
remote_execution_rpc_concurrency
--remote-execution-rpc-concurrency=<int>
PANTS_REMOTE_EXECUTION_RPC_CONCURRENCY
[GLOBAL]
remote_execution_rpc_concurrency = <int>
128
The number of concurrent requests allowed to the remote execution service.
remote_instance_name
--remote-instance-name=<str>
PANTS_REMOTE_INSTANCE_NAME
[GLOBAL]
remote_instance_name = <str>
None
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 a Pants plugin which provides remote authentication to dynamically set this value.
remote_oauth_bearer_token
--remote-oauth-bearer-token=<str>
PANTS_REMOTE_OAUTH_BEARER_TOKEN
[GLOBAL]
remote_oauth_bearer_token = <str>
None
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.
Recommendation: do not place a token directly in pants.toml
, instead do one of: set the token via the environment variable (PANTS_REMOTE_OAUTH_BEARER_TOKEN
), CLI option (--remote-oauth-bearer-token
), or store the token in a file and set the option to "@/path/to/token.txt"
to read the value from that file.
remote_store_address
--remote-store-address=<str>
PANTS_REMOTE_STORE_ADDRESS
[GLOBAL]
remote_store_address = <str>
None
The URI of a server/entity used as a remote file store. The supported URIs depends on the value of the remote_provider
option.
remote_store_batch_api_size_limit
--remote-store-batch-api-size-limit=<int>
PANTS_REMOTE_STORE_BATCH_API_SIZE_LIMIT
[GLOBAL]
remote_store_batch_api_size_limit = <int>
4194304
The maximum total size of blobs allowed to be sent in a single batch API call to the remote store.
remote_store_chunk_bytes
--remote-store-chunk-bytes=<int>
PANTS_REMOTE_STORE_CHUNK_BYTES
[GLOBAL]
remote_store_chunk_bytes = <int>
1048576
Size in bytes of chunks transferred to/from the remote file store.
remote_store_headers
--remote-store-headers="{'key1': val1, 'key2': val2, ...}"
PANTS_REMOTE_STORE_HEADERS
[GLOBAL.remote_store_headers]
key1 = val1
key2 = val2
...
{'user-agent': 'pants/<pants_version>'}
Headers to set on remote store requests.
Format: header=value. Pants may add additional headers.
See [GLOBAL].remote_execution_headers
as well.
remote_store_rpc_concurrency
--remote-store-rpc-concurrency=<int>
PANTS_REMOTE_STORE_RPC_CONCURRENCY
[GLOBAL]
remote_store_rpc_concurrency = <int>
128
The number of concurrent requests allowed to the remote store service.
remote_store_rpc_retries
--remote-store-rpc-retries=<int>
PANTS_REMOTE_STORE_RPC_RETRIES
[GLOBAL]
remote_store_rpc_retries = <int>
2
Number of times to retry any RPC to the remote store before giving up.
remote_store_rpc_timeout_millis
--remote-store-rpc-timeout-millis=<int>
PANTS_REMOTE_STORE_RPC_TIMEOUT_MILLIS
[GLOBAL]
remote_store_rpc_timeout_millis = <int>
30000
Timeout value for remote store RPCs (not including streaming requests) in milliseconds.
rule_threads_core
--rule-threads-core=<int>
PANTS_RULE_THREADS_CORE
[GLOBAL]
rule_threads_core = <int>
max(2, #cores/2)
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
).
rule_threads_max
--rule-threads-max=<int>
PANTS_RULE_THREADS_MAX
[GLOBAL]
rule_threads_max = <int>
None
The maximum number of threads to use to execute @rule
logic. Defaults to a small multiple of --rule-threads-core
.
show_log_target
--[no-]show-log-target
PANTS_SHOW_LOG_TARGET
[GLOBAL]
show_log_target = <bool>
False
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
.
stats_record_option_scopes
--stats-record-option-scopes="['<str>', '<str>', ...]"
PANTS_STATS_RECORD_OPTION_SCOPES
[GLOBAL]
stats_record_option_scopes = [
'<str>',
'<str>',
...,
]
[ "*" ]
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.
streaming_workunits_complete_async
--[no-]streaming-workunits-complete-async
PANTS_STREAMING_WORKUNITS_COMPLETE_ASYNC
[GLOBAL]
streaming_workunits_complete_async = <bool>
True
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.
streaming_workunits_level
--streaming-workunits-level=<LogLevel>
PANTS_STREAMING_WORKUNITS_LEVEL
[GLOBAL]
streaming_workunits_level = <LogLevel>
trace, debug, info, warn, error
default:
debug
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).
streaming_workunits_report_interval
--streaming-workunits-report-interval=<float>
PANTS_STREAMING_WORKUNITS_REPORT_INTERVAL
[GLOBAL]
streaming_workunits_report_interval = <float>
1.0
Interval in seconds between when streaming workunit event receivers will be polled.
subproject_roots
--subproject-roots="['<str>', '<str>', ...]"
PANTS_SUBPROJECT_ROOTS
[GLOBAL]
subproject_roots = [
'<str>',
'<str>',
...,
]
[]
Paths that correspond with build roots for any subproject that this project depends on.