Version: 2.13.x (deprecated)

Global options

Options to control the overall behavior of Pants.

Backend: pants.core

Config section: [GLOBAL]

Basic options

`level`

-l=<LogLevel>, --level=<LogLevel>
PANTS_LEVEL

one of: trace, debug, info, warn, error
default: info

Set the logging level.

`spec_files`

--spec-files="['<str>', '<str>', ...]"
PANTS_SPEC_FILES

default: []

Read additional specs (target addresses, files, and/or globs), one per line, from these files.

`pantsd`

--[no-]pantsd
PANTS_PANTSD

default: 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.

`concurrent`

--[no-]concurrent
PANTS_CONCURRENT

default: 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.

`local_cache`

--[no-]local-cache
PANTS_LOCAL_CACHE

default: True

Whether to cache process executions in a local cache persisted to disk at --local-store-dir.

`process_cleanup`

--[no-]process-cleanup
PANTS_PROCESS_CLEANUP

default: 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.

`keep_sandboxes`

--keep-sandboxes=<KeepSandboxes>
PANTS_KEEP_SANDBOXES

one of: 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.

`remote_execution`

--[no-]remote-execution
PANTS_REMOTE_EXECUTION

default: 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.

`remote_cache_read`

--[no-]remote-cache-read
PANTS_REMOTE_CACHE_READ

default: False

Whether to enable reading from a remote cache.

This cannot be used at the same time as --remote-execution.

`remote_cache_write`

--[no-]remote-cache-write
PANTS_REMOTE_CACHE_WRITE

default: False

Whether to enable writing results to a remote cache.

This cannot be used at the same time as --remote-execution.

`colors`

--[no-]colors
PANTS_COLORS

default: 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.

`dynamic_ui`

--[no-]dynamic-ui
PANTS_DYNAMIC_UI

default: 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

one of: indicatif-spinner, experimental-prodash
default: indicatif-spinner

If --dynamic-ui is enabled, selects the renderer.

`tag`

--tag="[[+-]tag1,tag2,..., [+-]tag1,tag2,..., ...]"
PANTS_TAG

default: []

Include only targets with these tags (optional '+' prefix) or without these tags ('-' prefix). See https://www.pantsbuild.org/v2.13/docs/advanced-target-selection.

`loop`

--[no-]loop
PANTS_LOOP

default: False

Run goals continuously as file changes are detected.

`use_deprecated_directory_cli_args_semantics`

--[no-]use-deprecated-directory-cli-args-semantics
PANTS_USE_DEPRECATED_DIRECTORY_CLI_ARGS_SEMANTICS

default: True

If true, Pants will use the old, deprecated semantics for directory arguments like /home/josh/work/scie-pants/dist/scie-pants-linux-x86_64 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. /home/josh/work/scie-pants/dist/scie-pants-linux-x86_64 test dir will run all tests in dir.

The new semantics will become the default in Pants 2.14, and the old semantics will be removed in 2.15.

This also impacts the behavior of the tailor goal. If this option is true, /home/josh/work/scie-pants/dist/scie-pants-linux-x86_64 tailor without additional arguments will run over the whole project, and /home/josh/work/scie-pants/dist/scie-pants-linux-x86_64 tailor dir will run over dir and all recursive sub-directories. If false, you must specify arguments, like /home/josh/work/scie-pants/dist/scie-pants-linux-x86_64 tailor :: to run over the whole project; specifying a directory will only add targets for that directory.

`use_deprecated_pex_binary_run_semantics`

--[no-]use-deprecated-pex-binary-run-semantics
PANTS_USE_DEPRECATED_PEX_BINARY_RUN_SEMANTICS

default: True

If true, running 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, running 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).

Advanced options

`backend_packages`

--backend-packages="['<str>', '<str>', ...]"
PANTS_BACKEND_PACKAGES

default: []

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.

`plugins`

--plugins="['<str>', '<str>', ...]"
PANTS_PLUGINS

default: []

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

default: False

Re-resolve plugins, even if previously resolved.

`show_log_target`

--[no-]show-log-target
PANTS_SHOW_LOG_TARGET

default: 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="{'key1': val1, 'key2': val2, ...}"
PANTS_LOG_LEVELS_BY_TARGET

default: {}

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

default: False

Whether to show/hide logging done by 3rdparty Rust crates used by the Pants engine.

`ignore_warnings`

--ignore-warnings="['<str>', '<str>', ...]"
PANTS_IGNORE_WARNINGS

default: []

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*'
]

`pants_version`

--pants-version=<str>
PANTS_VERSION

default: <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 /home/josh/work/scie-pants/dist/scie-pants-linux-x86_64 script from https://www.pantsbuild.org/v2.13/docs/installation, however, changing the value in your pants.toml will cause the new version to be installed and run automatically.

Run /home/josh/work/scie-pants/dist/scie-pants-linux-x86_64 --version to check what is being used.

`pants_bin_name`

--pants-bin-name=<str>
PANTS_BIN_NAME

default: ./pants

The name of the script or binary used to invoke Pants. Useful when printing help messages.

`pants_workdir`

--pants-workdir=<dir>
PANTS_WORKDIR

default: <buildroot>/.pants.d

Write intermediate logs and output files to this dir.

`pants_physical_workdir_base`

--pants-physical-workdir-base=<dir>
PANTS_PHYSICAL_WORKDIR_BASE

default: 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_distdir`

--pants-distdir=<dir>
PANTS_DISTDIR

default: <buildroot>/dist

Write end products, such as the results of ./pants package, to this dir.

`pants_subprocessdir`

--pants-subprocessdir=<str>
PANTS_SUBPROCESSDIR

default: <buildroot>/.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_config_files`

--pants-config-files="['<str>', '<str>', ...]"
PANTS_CONFIG_FILES

default: ["/tmp/tmp.MpwSc5OGVo/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.

`pantsrc`

--[no-]pantsrc
PANTS_PANTSRC

default: True

Use pantsrc files located at the paths specified in the global option pantsrc_files.

`pantsrc_files`

--pantsrc-files="[<path>, <path>, ...]"
PANTS_PANTSRC_FILES

default:

[
  "/etc/pantsrc",
  "~/.pants.rc",
  ".pants.rc"
]

Override config with values from these files, using syntax matching that of --pants-config-files.

`pythonpath`

--pythonpath="['<str>', '<str>', ...]"
PANTS_PYTHONPATH

default: []

Add these directories to PYTHONPATH to search for plugins. This does not impact the PYTHONPATH used by Pants when running your Python code.

`verify_config`

--[no-]verify-config
PANTS_VERIFY_CONFIG

default: True

Verify that all config file values correspond to known options.

`stats_record_option_scopes`

--stats-record-option-scopes="['<str>', '<str>', ...]"
PANTS_STATS_RECORD_OPTION_SCOPES

default: ["*"]

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.

`pants_ignore`

--pants-ignore="['<str>', '<str>', ...]"
PANTS_IGNORE

default:

[
  ".*/",
  "/dist/",
  "__pycache__"
]

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

default: 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.

`logdir`

--logdir=<dir>
PANTS_LOGDIR

default: None

Write logs to files under this directory.

`pantsd_timeout_when_multiple_invocations`

--pantsd-timeout-when-multiple-invocations=<float>
PANTS_PANTSD_TIMEOUT_WHEN_MULTIPLE_INVOCATIONS

default: 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.

`pantsd_max_memory_usage`

--pantsd-max-memory-usage=<memory_size>
PANTS_PANTSD_MAX_MEMORY_USAGE

default: 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.

`print_stacktrace`

--[no-]print-stacktrace
PANTS_PRINT_STACKTRACE

default: False

Print the full exception stack trace for any errors.

`engine_visualize_to`

--engine-visualize-to=<dir_option>
PANTS_ENGINE_VISUALIZE_TO

default: 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.

`pantsd_pailgun_port`

--pantsd-pailgun-port=<int>
PANTS_PANTSD_PAILGUN_PORT

default: 0

The port to bind the Pants nailgun server to. Defaults to a random port.

`pantsd_invalidation_globs`

--pantsd-invalidation-globs="['<str>', '<str>', ...]"
PANTS_PANTSD_INVALIDATION_GLOBS

default: []

Filesystem events matching any of these globs will trigger a daemon restart. Pants's own code, plugins, and --pants-config-files are inherently invalidated.

`rule_threads_core`

--rule-threads-core=<int>
PANTS_RULE_THREADS_CORE

default: 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

default: None

The maximum number of threads to use to execute @rule logic. Defaults to a small multiple of --rule-threads-core.

`local_store_dir`

--local-store-dir=<str>
PANTS_LOCAL_STORE_DIR

default: $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_shard_count`

--local-store-shard-count=<int>
PANTS_LOCAL_STORE_SHARD_COUNT

default: 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=<int>
PANTS_LOCAL_STORE_PROCESSES_MAX_SIZE_BYTES

default: 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=<int>
PANTS_LOCAL_STORE_FILES_MAX_SIZE_BYTES

default: 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=<int>
PANTS_LOCAL_STORE_DIRECTORIES_MAX_SIZE_BYTES

default: 16000000000

The maximum size in bytes of the local store containing directories. Stored below --local-store-dir.

`named_caches_dir`

--named-caches-dir=<str>
PANTS_NAMED_CACHES_DIR

default: $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.

`local_execution_root_dir`

--local-execution-root-dir=<str>
PANTS_LOCAL_EXECUTION_ROOT_DIR

default: <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.

`cache_content_behavior`

--cache-content-behavior=<CacheContentBehavior>
PANTS_CACHE_CONTENT_BEHAVIOR

one of: 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).

`ca_certs_path`

--ca-certs-path=<str>
PANTS_CA_CERTS_PATH

default: None

Path to a file containing PEM-format CA certificates used for verifying secure connections when downloading files required by a build.

`process_total_child_memory_usage`

--process-total-child-memory-usage=<memory_size>
PANTS_PROCESS_TOTAL_CHILD_MEMORY_USAGE

default: 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.

`process_per_child_memory_usage`

--process-per-child-memory-usage=<memory_size>
PANTS_PROCESS_PER_CHILD_MEMORY_USAGE

default: 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_execution_local_parallelism`

--process-execution-local-parallelism=<int>
PANTS_PROCESS_EXECUTION_LOCAL_PARALLELISM

default: #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

default: 128

Number of concurrent processes that may be executed remotely.

`process_execution_cache_namespace`

--process-execution-cache-namespace=<str>
PANTS_PROCESS_EXECUTION_CACHE_NAMESPACE

default: 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`

--[no-]process-execution-local-enable-nailgun
PANTS_PROCESS_EXECUTION_LOCAL_ENABLE_NAILGUN

default: True

Whether or not to use nailgun to run JVM requests that are marked as supporting nailgun.

`process_execution_graceful_shutdown_timeout`

--process-execution-graceful-shutdown-timeout=<int>
PANTS_PROCESS_EXECUTION_GRACEFUL_SHUTDOWN_TIMEOUT

default: 3

The time in seconds to wait when gracefully shutting down an interactive process (such as one opened using /home/josh/work/scie-pants/dist/scie-pants-linux-x86_64 run) before killing it.

`remote_instance_name`

--remote-instance-name=<str>
PANTS_REMOTE_INSTANCE_NAME

default: 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.

`remote_ca_certs_path`

--remote-ca-certs-path=<str>
PANTS_REMOTE_CA_CERTS_PATH

default: 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=<str>
PANTS_REMOTE_OAUTH_BEARER_TOKEN_PATH

default: 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.

`remote_auth_plugin`

--remote-auth-plugin=<str>
PANTS_REMOTE_AUTH_PLUGIN

default: 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.

`remote_store_address`

--remote-store-address=<str>
PANTS_REMOTE_STORE_ADDRESS

default: 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="{'key1': val1, 'key2': val2, ...}"
PANTS_REMOTE_STORE_HEADERS

default: {'user-agent': 'pants/<pants_version>'}

Headers to set on remote store requests.

Format: header=value. Pants may add additional headers.

See --remote-execution-headers as well.

`remote_store_chunk_bytes`

--remote-store-chunk-bytes=<int>
PANTS_REMOTE_STORE_CHUNK_BYTES

default: 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=<int>
PANTS_REMOTE_STORE_CHUNK_UPLOAD_TIMEOUT_SECONDS

default: 60

Timeout (in seconds) for uploads of individual chunks to the remote file store.

`remote_store_rpc_retries`

--remote-store-rpc-retries=<int>
PANTS_REMOTE_STORE_RPC_RETRIES

default: 2

Number of times to retry any RPC to the remote store before giving up.

`remote_store_rpc_concurrency`

--remote-store-rpc-concurrency=<int>
PANTS_REMOTE_STORE_RPC_CONCURRENCY

default: 128

The number of concurrent requests allowed to the remote store service.

`remote_store_batch_api_size_limit`

--remote-store-batch-api-size-limit=<int>
PANTS_REMOTE_STORE_BATCH_API_SIZE_LIMIT

default: 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=<RemoteCacheWarningsBehavior>
PANTS_REMOTE_CACHE_WARNINGS

one of: ignore, first_only, backoff
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_cache_rpc_concurrency`

--remote-cache-rpc-concurrency=<int>
PANTS_REMOTE_CACHE_RPC_CONCURRENCY

default: 128

The number of concurrent requests allowed to the remote cache service.

`remote_cache_read_timeout_millis`

--remote-cache-read-timeout-millis=<int>
PANTS_REMOTE_CACHE_READ_TIMEOUT_MILLIS

default: 1500

Timeout value for remote cache lookups in milliseconds.

`remote_execution_address`

--remote-execution-address=<str>
PANTS_REMOTE_EXECUTION_ADDRESS

default: 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="['<str>', '<str>', ...]"
PANTS_REMOTE_EXECUTION_EXTRA_PLATFORM_PROPERTIES

default: []

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="{'key1': val1, 'key2': val2, ...}"
PANTS_REMOTE_EXECUTION_HEADERS

default: {'user-agent': 'pants/<pants_version>'}

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=<int>
PANTS_REMOTE_EXECUTION_OVERALL_DEADLINE_SECS

default: 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

default: 128

The number of concurrent requests allowed to the remote execution service.

`watch_filesystem`

--[no-]watch-filesystem
PANTS_WATCH_FILESYSTEM

default: True

Set to False if Pants should not watch the filesystem for changes. pantsd or loop may not be enabled.

`unmatched_build_file_globs`

--unmatched-build-file-globs=<UnmatchedBuildFileGlobs>
PANTS_UNMATCHED_BUILD_FILE_GLOBS

one of: 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 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.

`unmatched_cli_globs`

--unmatched-cli-globs=<UnmatchedCliGlobs>
PANTS_UNMATCHED_CLI_GLOBS

one of: ignore, warn, error
default: error

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.

`build_patterns`

--build-patterns="['<str>', '<str>', ...]"
PANTS_BUILD_PATTERNS

default:

[
  "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.

`build_ignore`

--build-ignore="['<str>', '<str>', ...]"
PANTS_BUILD_IGNORE

default: []

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_file_prelude_globs`

--build-file-prelude-globs="['<str>', '<str>', ...]"
PANTS_BUILD_FILE_PRELUDE_GLOBS

default: []

Python files to evaluate and whose symbols should be exposed to all BUILD files. See https://www.pantsbuild.org/v2.13/docs/macros.

`subproject_roots`

--subproject-roots="['<str>', '<str>', ...]"
PANTS_SUBPROJECT_ROOTS

default: []

Paths that correspond with build roots for any subproject that this project depends on.

`loop_max`

--loop-max=<int>
PANTS_LOOP_MAX

default: 4294967296

The maximum number of times to loop when --loop is specified.

`streaming_workunits_report_interval`

--streaming-workunits-report-interval=<float>
PANTS_STREAMING_WORKUNITS_REPORT_INTERVAL

default: 1.0

Interval in seconds between when streaming workunit event receivers will be polled.

`streaming_workunits_level`

--streaming-workunits-level=<LogLevel>
PANTS_STREAMING_WORKUNITS_LEVEL

one of: 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_complete_async`

--[no-]streaming-workunits-complete-async
PANTS_STREAMING_WORKUNITS_COMPLETE_ASYNC

default: 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

`remote_cache_eager_fetch`

--[no-]remote-cache-eager-fetch
PANTS_REMOTE_CACHE_EAGER_FETCH

default: 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.

`exclude_target_regexp`

--exclude-target-regexp="[<regexp>, <regexp>, ...]"
PANTS_EXCLUDE_TARGET_REGEXP

default: []

Exclude targets that match these regexes. This does not impact file arguments.

`files_not_found_behavior`

--files-not-found-behavior=<UnmatchedBuildFileGlobs>
PANTS_FILES_NOT_FOUND_BEHAVIOR

one of: 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=<OwnersNotFoundBehavior>
PANTS_OWNERS_NOT_FOUND_BEHAVIOR

one of: ignore, warn, error
default: ignore

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.

Basic options
Advanced options
Deprecated options

Basic options​

level​

spec_files​

pantsd​

concurrent​

local_cache​

process_cleanup​

keep_sandboxes​

remote_execution​

remote_cache_read​

remote_cache_write​

colors​

dynamic_ui​

dynamic_ui_renderer​

tag​

loop​

use_deprecated_directory_cli_args_semantics​

use_deprecated_pex_binary_run_semantics​

Advanced options​

backend_packages​

plugins​

plugins_force_resolve​

show_log_target​

log_levels_by_target​

log_show_rust_3rdparty​

ignore_warnings​

pants_version​

pants_bin_name​

pants_workdir​

pants_physical_workdir_base​

pants_distdir​

pants_subprocessdir​

pants_config_files​

pantsrc​

pantsrc_files​

pythonpath​

verify_config​

stats_record_option_scopes​

pants_ignore​

pants_ignore_use_gitignore​

logdir​

pantsd_timeout_when_multiple_invocations​

pantsd_max_memory_usage​

print_stacktrace​

engine_visualize_to​

pantsd_pailgun_port​

pantsd_invalidation_globs​

rule_threads_core​

rule_threads_max​

local_store_dir​

local_store_shard_count​

local_store_processes_max_size_bytes​

local_store_files_max_size_bytes​

local_store_directories_max_size_bytes​

named_caches_dir​

local_execution_root_dir​

cache_content_behavior​

ca_certs_path​

process_total_child_memory_usage​

process_per_child_memory_usage​

process_execution_local_parallelism​

process_execution_remote_parallelism​

process_execution_cache_namespace​

process_execution_local_enable_nailgun​

process_execution_graceful_shutdown_timeout​

remote_instance_name​

remote_ca_certs_path​

remote_oauth_bearer_token_path​

remote_auth_plugin​

remote_store_address​

remote_store_headers​

remote_store_chunk_bytes​

remote_store_chunk_upload_timeout_seconds​

remote_store_rpc_retries​

remote_store_rpc_concurrency​

remote_store_batch_api_size_limit​

remote_cache_warnings​

remote_cache_rpc_concurrency​

remote_cache_read_timeout_millis​

remote_execution_address​

Basic options

`level`

`spec_files`

`pantsd`

`concurrent`

`local_cache`

`process_cleanup`

`keep_sandboxes`

`remote_execution`

`remote_cache_read`

`remote_cache_write`

`colors`

`dynamic_ui`

`dynamic_ui_renderer`

`tag`

`loop`

`use_deprecated_directory_cli_args_semantics`

`use_deprecated_pex_binary_run_semantics`

Advanced options

`backend_packages`

`plugins`

`plugins_force_resolve`

`show_log_target`

`log_levels_by_target`

`log_show_rust_3rdparty`

`ignore_warnings`

`pants_version`

`pants_bin_name`

`pants_workdir`

`pants_physical_workdir_base`

`pants_distdir`

`pants_subprocessdir`

`pants_config_files`

`pantsrc`

`pantsrc_files`

`pythonpath`

`verify_config`

`stats_record_option_scopes`

`pants_ignore`

`pants_ignore_use_gitignore`

`logdir`

`pantsd_timeout_when_multiple_invocations`

`pantsd_max_memory_usage`

`print_stacktrace`

`engine_visualize_to`

`pantsd_pailgun_port`

`pantsd_invalidation_globs`

`rule_threads_core`

`rule_threads_max`

`local_store_dir`

`local_store_shard_count`

`local_store_processes_max_size_bytes`

`local_store_files_max_size_bytes`

`local_store_directories_max_size_bytes`

`named_caches_dir`

`local_execution_root_dir`

`cache_content_behavior`

`ca_certs_path`

`process_total_child_memory_usage`

`process_per_child_memory_usage`

`process_execution_local_parallelism`

`process_execution_remote_parallelism`

`process_execution_cache_namespace`

`process_execution_local_enable_nailgun`

`process_execution_graceful_shutdown_timeout`

`remote_instance_name`

`remote_ca_certs_path`

`remote_oauth_bearer_token_path`

`remote_auth_plugin`

`remote_store_address`

`remote_store_headers`

`remote_store_chunk_bytes`

`remote_store_chunk_upload_timeout_seconds`

`remote_store_rpc_retries`

`remote_store_rpc_concurrency`

`remote_store_batch_api_size_limit`

`remote_cache_warnings`

`remote_cache_rpc_concurrency`

`remote_cache_read_timeout_millis`

`remote_execution_address`