Global options
Options to control the overall behavior of Pants.
Config section: [GLOBAL]
Basic options
trace, debug, info, warn, error
default:
info
Set the logging level.
[]
Read additional specs (target addresses, files, and/or globs), one per line, from these files.
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.
False
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.
[]
Include only targets with these tags (optional '+' prefix) or without these tags ('-' prefix). See Advanced target selection.
exclude_target_regexp
exclude_target_regexp
--exclude-target-regexp="[<regexp>, <regexp>, ...]"
PANTS_EXCLUDE_TARGET_REGEXP
[]
Exclude targets that match these regexes. This does not impact file arguments.
False
Run goals continuously as file changes are detected.
Advanced options
[]
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.
[]
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.
False
Re-resolve plugins, even if previously resolved.
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.
log_levels_by_target
log_levels_by_target
--log-levels-by-target="{'key1': val1, 'key2': val2, ...}"
PANTS_LOG_LEVELS_BY_TARGET
{}
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"}'
.
False
Whether to show/hide logging done by 3rdparty Rust crates used by the Pants engine.
[]
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*'
]
2.8.1rc2
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.
./pants
The name of the script or binary used to invoke Pants. Useful when printing help messages.
/Users/benjyw/src/pants/.pants.d
Write intermediate logs and output files to this 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.
/Users/benjyw/src/pants/dist
Write end products, such as the results of ./pants package
, to this dir.
/Users/benjyw/src/pants/.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.
[ "/Users/benjyw/src/pants/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
.
True
Use pantsrc files located at the paths specified in the global option pantsrc_files
.
[ "/etc/pantsrc", "~/.pants.rc" ]
Override config with values from these files, using syntax matching that of --pants-config-files
.
[]
Add these directories to PYTHONPATH to search for plugins. This does not impact the PYTHONPATH used by Pants when running your Python code.
True
Verify that all config file values correspond to known options.
stats_record_option_scopes
stats_record_option_scopes
--stats-record-option-scopes="['<str>', '<str>', ...]"
PANTS_STATS_RECORD_OPTION_SCOPES
[ "*" ]
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.
[ ".*/", "/dist/" ]
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.
True
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.
None
Write logs to files under this directory.
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.
False
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.
pantsd_timeout_when_multiple_invocations
pantsd_timeout_when_multiple_invocations
--pantsd-timeout-when-multiple-invocations=<float>
PANTS_PANTSD_TIMEOUT_WHEN_MULTIPLE_INVOCATIONS
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.
1GiB
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.
False
Print the full exception stack trace for any errors.
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.
0
The port to bind the Pants nailgun server to. Defaults to a random port.
pantsd_invalidation_globs
pantsd_invalidation_globs
--pantsd-invalidation-globs="['<str>', '<str>', ...]"
PANTS_PANTSD_INVALIDATION_GLOBS
[]
Filesystem events matching any of these globs will trigger a daemon restart. Pants's own code, plugins, and --pants-config-files
are inherently invalidated.
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
).
None
The maximum number of threads to use to execute @rule
logic. Defaults to a small multiple of --rule-threads-core
.
/Users/benjyw/.cache/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
.
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.
local_store_processes_max_size_bytes
local_store_processes_max_size_bytes
--local-store-processes-max-size-bytes=<int>
PANTS_LOCAL_STORE_PROCESSES_MAX_SIZE_BYTES
16000000000
The maximum size in bytes of the local store containing process cache entries. Stored below --local-store-dir
.
local_store_files_max_size_bytes
local_store_files_max_size_bytes
--local-store-files-max-size-bytes=<int>
PANTS_LOCAL_STORE_FILES_MAX_SIZE_BYTES
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_directories_max_size_bytes
local_store_directories_max_size_bytes
--local-store-directories-max-size-bytes=<int>
PANTS_LOCAL_STORE_DIRECTORIES_MAX_SIZE_BYTES
16000000000
The maximum size in bytes of the local store containing directories. Stored below --local-store-dir
.
/Users/benjyw/.cache/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
.
/var/folders/q4/pv4jnnm944b_ywr3tnp_b1300000gn/T
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
.
process_execution_local_cache
process_execution_local_cache
--[no-]process-execution-local-cache
PANTS_PROCESS_EXECUTION_LOCAL_CACHE
True
Whether to cache process executions in a local cache persisted to disk at --local-store-dir
.
process_execution_local_cleanup
process_execution_local_cleanup
--[no-]process-execution-local-cleanup
PANTS_PROCESS_EXECUTION_LOCAL_CLEANUP
True
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.
None
Path to a file containing PEM-format CA certificates used for verifying secure connections when downloading files required by a build.
process_execution_local_parallelism
process_execution_local_parallelism
--process-execution-local-parallelism=<int>
PANTS_PROCESS_EXECUTION_LOCAL_PARALLELISM
#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
--process-execution-remote-parallelism=<int>
PANTS_PROCESS_EXECUTION_REMOTE_PARALLELISM
128
Number of concurrent processes that may be executed remotely.
process_execution_cache_namespace
process_execution_cache_namespace
--process-execution-cache-namespace=<str>
PANTS_PROCESS_EXECUTION_CACHE_NAMESPACE
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 usecases or users.
process_execution_local_enable_nailgun
process_execution_local_enable_nailgun
--[no-]process-execution-local-enable-nailgun
PANTS_PROCESS_EXECUTION_LOCAL_ENABLE_NAILGUN
True
Whether or not to use nailgun to run JVM requests that are marked as supporting nailgun.
False
Enables remote workers for increased parallelism. (Alpha)
Alternatively, you can use --remote-cache-read
and --remote-cache-write
to still run everything locally, but to use a remote cache.
False
Whether to enable reading from a remote cache.
This cannot be used at the same time as --remote-execution
.
False
Whether to enable writing results to a remote cache.
This cannot be used at the same time as --remote-execution
.
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 --remote-auth-plugin
to provide a plugin to dynamically set this value.
None
Path to a PEM file containing CA certificates used for verifying secure connections to --remote-execution-address
and --remote-store-address
.
If unspecified, Pants will attempt to auto-discover root CA certificates when TLS is enabled with remote execution and caching.
remote_oauth_bearer_token_path
remote_oauth_bearer_token_path
--remote-oauth-bearer-token-path=<str>
PANTS_REMOTE_OAUTH_BEARER_TOKEN_PATH
None
Path to a file containing an oauth token to use for gGRPC connections to --remote-execution-address
and --remote-store-address
.
If specified, Pants will add a header in the format authorization: Bearer <token>
. You can also manually add this header via --remote-execution-headers
and --remote-store-headers
, or use --remote-auth-plugin
to provide a plugin to dynamically set the relevant headers. Otherwise, no authorization will be performed.
None
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 --remote-store-headers
still work.
If you return instance_name
, Pants will replace --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
.
None
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.
remote_store_headers
remote_store_headers
--remote-store-headers="{'key1': val1, 'key2': val2, ...}"
PANTS_REMOTE_STORE_HEADERS
{ "user-agent": "pants/2.8.1rc2" }
Headers to set on remote store requests.
Format: header=value. Pants may add additional headers.
See --remote-execution-headers
as well.
1048576
Size in bytes of chunks transferred to/from the remote file store.
remote_store_chunk_upload_timeout_seconds
remote_store_chunk_upload_timeout_seconds
--remote-store-chunk-upload-timeout-seconds=<int>
PANTS_REMOTE_STORE_CHUNK_UPLOAD_TIMEOUT_SECONDS
60
Timeout (in seconds) for uploads of individual chunks to the remote file store.
2
Number of times to retry any RPC to the remote store before giving up.
remote_store_rpc_concurrency
remote_store_rpc_concurrency
--remote-store-rpc-concurrency=<int>
PANTS_REMOTE_STORE_RPC_CONCURRENCY
128
The number of concurrent requests allowed to the remote store service.
remote_store_batch_api_size_limit
remote_store_batch_api_size_limit
--remote-store-batch-api-size-limit=<int>
PANTS_REMOTE_STORE_BATCH_API_SIZE_LIMIT
4194304
The maximum total size of blobs allowed to be sent in a single batch API call to the remote store.
remote_cache_warnings
remote_cache_warnings
--remote-cache-warnings=<RemoteCacheWarningsBehavior>
PANTS_REMOTE_CACHE_WARNINGS
ignore, first_only, backoff
default:
first_only
Whether 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.
True
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.
remote_cache_rpc_concurrency
remote_cache_rpc_concurrency
--remote-cache-rpc-concurrency=<int>
PANTS_REMOTE_CACHE_RPC_CONCURRENCY
128
The number of concurrent requests allowed to the remote cache service.
None
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 --remote-store-address
, which will often be the same value.
remote_execution_extra_platform_properties
remote_execution_extra_platform_properties
--remote-execution-extra-platform-properties="['<str>', '<str>', ...]"
PANTS_REMOTE_EXECUTION_EXTRA_PLATFORM_PROPERTIES
[]
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.
remote_execution_headers
remote_execution_headers
--remote-execution-headers="{'key1': val1, 'key2': val2, ...}"
PANTS_REMOTE_EXECUTION_HEADERS
{ "user-agent": "pants/2.8.1rc2" }
Headers to set on remote execution requests. Format: header=value. Pants may add additional headers.
See --remote-store-headers
as well.
remote_execution_overall_deadline_secs
remote_execution_overall_deadline_secs
--remote-execution-overall-deadline-secs=<int>
PANTS_REMOTE_EXECUTION_OVERALL_DEADLINE_SECS
3600
Overall timeout in seconds for each remote execution request from time of submission
remote_execution_rpc_concurrency
remote_execution_rpc_concurrency
--remote-execution-rpc-concurrency=<int>
PANTS_REMOTE_EXECUTION_RPC_CONCURRENCY
128
The number of concurrent requests allowed to the remote execution service.
True
Set to False if Pants should not watch the filesystem for changes. pantsd
or loop
may not be enabled.
files_not_found_behavior
files_not_found_behavior
--files-not-found-behavior=<FilesNotFoundBehavior>
PANTS_FILES_NOT_FOUND_BEHAVIOR
warn, error
default:
warn
What to do when files and globs specified in BUILD files, such as in the sources
field, cannot be found. This happens when the files do not exist on your machine or when they are ignored by the --pants-ignore
option.
owners_not_found_behavior
owners_not_found_behavior
--owners-not-found-behavior=<OwnersNotFoundBehavior>
PANTS_OWNERS_NOT_FOUND_BEHAVIOR
ignore, warn, error
default:
error
What to do when file arguments do not have any owning target. This happens when there are no targets whose sources
fields include the file argument.
[ "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.
[]
Paths to ignore when identifying BUILD files.
This does not affect any other filesystem operations; use --pants-ignore
for that instead.
Patterns use the gitignore pattern syntax (https://git-scm.com/docs/gitignore).
build_file_prelude_globs
build_file_prelude_globs
--build-file-prelude-globs="['<str>', '<str>', ...]"
PANTS_BUILD_FILE_PRELUDE_GLOBS
[]
Python files to evaluate and whose symbols should be exposed to all BUILD files. See Macros.
[]
Paths that correspond with build roots for any subproject that this project depends on.
4294967296
The maximum number of times to loop when --loop
is specified.
streaming_workunits_report_interval
streaming_workunits_report_interval
--streaming-workunits-report-interval=<float>
PANTS_STREAMING_WORKUNITS_REPORT_INTERVAL
1.0
Interval in seconds between when streaming workunit event receivers will be polled.
streaming_workunits_complete_async
streaming_workunits_complete_async
--[no-]streaming-workunits-complete-async
PANTS_STREAMING_WORKUNITS_COMPLETE_ASYNC
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.
Deprecated options
/Users/benjyw/src/pants/build-support
Deprecated, will be removed in version: 2.9.0.dev0.
Unused: this option has no necessary equivalent in v2.
Does not do anything.
Updated almost 2 years ago