Options to control the overall behavior of Pants.
Config section: [GLOBAL]
Basic options
-l=<LogLevel>, --level=<LogLevel>
PANTS_LEVEL
level
trace, debug, info, warn, error
default:
info
Set the logging level.
--[no-]colors
PANTS_COLORS
colors
False
Whether Pants should use colors in output or not. This may also impact whether some tools Pants run use color.
--spec-files="['<str>', '<str>', ...]"
PANTS_SPEC_FILES
spec_files
[]
Read additional specs (target addresses, files, and/or globs), one per line,from these files.
--[no-]dynamic-ui
PANTS_DYNAMIC_UI
dynamic_ui
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.
--tag="[[+-]tag1,tag2,..., [+-]tag1,tag2,..., ...]"
PANTS_TAG
tag
[]
Include only targets with these tags (optional '+' prefix) or without these tags ('-' prefix). See https://www.pantsbuild.org/v2.2/docs/advanced-target-selection.
--exclude-target-regexp="[<regexp>, <regexp>, ...]"
PANTS_EXCLUDE_TARGET_REGEXP
exclude_target_regexp
[]
Exclude targets that match these regexes. This does not impact file arguments.
--[no-]loop
PANTS_LOOP
loop
False
Run goals continuously as file changes are detected. Alpha feature.
Advanced options
--backend-packages="['<str>', '<str>', ...]"
PANTS_BACKEND_PACKAGES
backend_packages
[]
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.
--plugins="['<str>', '<str>', ...]"
PANTS_PLUGINS
plugins
[]
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.
--[no-]plugins-force-resolve
PANTS_PLUGINS_FORCE_RESOLVE
plugins_force_resolve
False
Re-resolve plugins, even if previously resolved.
--plugin-cache-dir=<str>
PANTS_PLUGIN_CACHE_DIR
plugin_cache_dir
/Users/eric/.cache/pants/plugins
Cache resolved plugin requirements here.
--[no-]show-log-target
PANTS_SHOW_LOG_TARGET
show_log_target
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="{'key1': val1, 'key2': val2, ...}"
PANTS_LOG_LEVELS_BY_TARGET
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"}'`.
--[no-]log-show-rust-3rdparty
PANTS_LOG_SHOW_RUST_3RDPARTY
log_show_rust_3rdparty
False
Whether to show/hide logging done by 3rdparty Rust crates used by the Pants engine.
--ignore-pants-warnings="['<str>', '<str>', ...]"
PANTS_IGNORE_PANTS_WARNINGS
ignore_pants_warnings
[]
Regexps matching warning strings to ignore, e.g. ["DEPRECATED: the option `--my-opt` will be removed"]. The regex patterns will be matched from the start of the warning string, and are case-insensitive.
--pants-version=<str>
PANTS_VERSION
pants_version
2.2.0.dev2
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/v2.2/docs/installation, 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-bin-name=<str>
PANTS_BIN_NAME
pants_bin_name
./pants
The name of the script or binary used to invoke Pants. Useful when printing help messages.
--pants-workdir=<dir>
PANTS_WORKDIR
pants_workdir
/Users/eric/DocsLocal/code/projects/pants/.pants.d
Write intermediate logs and output files to this dir.
--pants-physical-workdir-base=<dir>
PANTS_PHYSICAL_WORKDIR_BASE
pants_physical_workdir_base
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-supportdir=<dir>
PANTS_SUPPORTDIR
pants_supportdir
/Users/eric/DocsLocal/code/projects/pants/build-support
Unused. Will be deprecated in 2.2.0.
--pants-distdir=<dir>
PANTS_DISTDIR
pants_distdir
/Users/eric/DocsLocal/code/projects/pants/dist
Write end products, such as the results of `./pants package`, to this dir.
--pants-subprocessdir=<str>
PANTS_SUBPROCESSDIR
pants_subprocessdir
/Users/eric/DocsLocal/code/projects/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.
--pants-config-files="['<str>', '<str>', ...]"
PANTS_CONFIG_FILES
pants_config_files
[ "/Users/eric/DocsLocal/code/projects/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`.
--[no-]pantsrc
PANTS_PANTSRC
pantsrc
True
Use pantsrc files located at the paths specified in the global option `pantsrc_files`.
--pantsrc-files="[<path>, <path>, ...]"
PANTS_PANTSRC_FILES
pantsrc_files
[ "/etc/pantsrc", "~/.pants.rc" ]
Override config with values from these files, using syntax matching that of `--pants-config-files`.
--pythonpath="['<str>', '<str>', ...]"
PANTS_PYTHONPATH
pythonpath
[]
Add these directories to PYTHONPATH to search for plugins. This does not impact the PYTHONPATH used by Pants when running your Python code.
--[no-]verify-config
PANTS_VERIFY_CONFIG
verify_config
True
Verify that all config file values correspond to known options.
--pants-ignore="['<str>', '<str>', ...]"
PANTS_IGNORE
pants_ignore
[ ".*/", "/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.
--[no-]pants-ignore-use-gitignore
PANTS_IGNORE_USE_GITIGNORE
pants_ignore_use_gitignore
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.
-d=<dir>, --logdir=<dir>
PANTS_LOGDIR
logdir
None
Write logs to files under this directory.
--[no-]pantsd
PANTS_PANTSD
pantsd
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.
--[no-]concurrent
PANTS_CONCURRENT
concurrent
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=<float>
PANTS_PANTSD_TIMEOUT_WHEN_MULTIPLE_INVOCATIONS
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.
--pantsd-max-memory-usage=<int>
PANTS_PANTSD_MAX_MEMORY_USAGE
pantsd_max_memory_usage
1073741824
The maximum memory usage of a pantsd process (in bytes). There is at most one pantsd process per workspace.
--[no-]print-stacktrace
PANTS_PRINT_STACKTRACE
print_stacktrace
False
Print the full exception stack trace for any errors.
--native-engine-visualize-to=<dir_option>
PANTS_NATIVE_ENGINE_VISUALIZE_TO
native_engine_visualize_to
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=<int>
PANTS_PANTSD_PAILGUN_PORT
pantsd_pailgun_port
0
The port to bind the Pants nailgun server to. Defaults to a random port.
--pantsd-invalidation-globs="['<str>', '<str>', ...]"
PANTS_PANTSD_INVALIDATION_GLOBS
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.
--rule-threads-core=<int>
PANTS_RULE_THREADS_CORE
rule_threads_core
6
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=<int>
PANTS_RULE_THREADS_MAX
rule_threads_max
None
The maximum number of threads to use to execute `@rule` logic. Defaults to a small multiple of `--rule-threads-core`.
--local-store-dir=<str>
PANTS_LOCAL_STORE_DIR
local_store_dir
/Users/eric/.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`.
--named-caches-dir=<str>
PANTS_NAMED_CACHES_DIR
named_caches_dir
/Users/eric/.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`.
--local-execution-root-dir=<str>
PANTS_LOCAL_EXECUTION_ROOT_DIR
local_execution_root_dir
/var/folders/sx/pdpbqz4x5cscn9hhfpbsbqvm0000gn/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`.
--[no-]process-execution-use-local-cache
PANTS_PROCESS_EXECUTION_USE_LOCAL_CACHE
process_execution_use_local_cache
True
Whether to keep process executions in a local cache persisted to disk.
--[no-]process-execution-cleanup-local-dirs
PANTS_PROCESS_EXECUTION_CLEANUP_LOCAL_DIRS
process_execution_cleanup_local_dirs
True
Whether or not to cleanup directories used for local process execution (primarily useful for e.g. debugging).
--ca-certs-path=<str>
PANTS_CA_CERTS_PATH
ca_certs_path
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=<int>
PANTS_PROCESS_EXECUTION_LOCAL_PARALLELISM
process_execution_local_parallelism
12
Number of concurrent processes that may be executed locally.
--process-execution-remote-parallelism=<int>
PANTS_PROCESS_EXECUTION_REMOTE_PARALLELISM
process_execution_remote_parallelism
128
Number of concurrent processes that may be executed remotely.
--process-execution-cache-namespace=<str>
PANTS_PROCESS_EXECUTION_CACHE_NAMESPACE
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-speculation-delay=<float>
PANTS_PROCESS_EXECUTION_SPECULATION_DELAY
process_execution_speculation_delay
1.0
Number of seconds to wait before speculating a second request for a slow process. see `--process-execution-speculation-strategy`
--process-execution-speculation-strategy=<str>
PANTS_PROCESS_EXECUTION_SPECULATION_STRATEGY
process_execution_speculation_strategy
remote_first, local_first, none
default:
none
Speculate a second request for an underlying process if the first one does not complete within `--process-execution-speculation-delay` seconds. `local_first` (default): Try to run the process locally first, and fall back to remote execution if available. `remote_first`: Run the process on the remote execution backend if available, and fall back to the local host if remote calls take longer than the speculation timeout. `none`: Do not speculate about long running processes.
--[no-]process-execution-local-enable-nailgun
PANTS_PROCESS_EXECUTION_LOCAL_ENABLE_NAILGUN
process_execution_local_enable_nailgun
False
Whether or not to use nailgun to run the requests that are marked as nailgunnable.
--[no-]remote-execution
PANTS_REMOTE_EXECUTION
remote_execution
False
Enables remote workers for increased parallelism. (Alpha)
--[no-]remote-cache-read
PANTS_REMOTE_CACHE_READ
remote_cache_read
False
Whether to enable reading from a remote cache
--[no-]remote-cache-write
PANTS_REMOTE_CACHE_WRITE
remote_cache_write
False
Whether to enable writing results to a remote cache
--remote-store-server="['<str>', '<str>', ...]"
PANTS_REMOTE_STORE_SERVER
remote_store_server
[]
host:port of grpc server to use as remote execution file store.
--remote-store-thread-count=<int>
PANTS_REMOTE_STORE_THREAD_COUNT
remote_store_thread_count
1
Thread count to use for the pool that interacts with the remote file store.
--remote-execution-server=<str>
PANTS_REMOTE_EXECUTION_SERVER
remote_execution_server
None
host:port of grpc server to use as remote execution scheduler.
--remote-store-chunk-bytes=<int>
PANTS_REMOTE_STORE_CHUNK_BYTES
remote_store_chunk_bytes
1048576
Size in bytes of chunks transferred to/from the remote file store.
--remote-store-chunk-upload-timeout-seconds=<int>
PANTS_REMOTE_STORE_CHUNK_UPLOAD_TIMEOUT_SECONDS
remote_store_chunk_upload_timeout_seconds
60
Timeout (in seconds) for uploads of individual chunks to the remote file store.
--remote-store-rpc-retries=<int>
PANTS_REMOTE_STORE_RPC_RETRIES
remote_store_rpc_retries
2
Number of times to retry any RPC to the remote store before giving up.
--remote-store-connection-limit=<int>
PANTS_REMOTE_STORE_CONNECTION_LIMIT
remote_store_connection_limit
5
Number of remote stores to concurrently allow connections to.
--remote-store-initial-timeout=<int>
PANTS_REMOTE_STORE_INITIAL_TIMEOUT
remote_store_initial_timeout
10
Initial timeout (in milliseconds) when there is a failure in accessing a remote store.
--remote-store-timeout-multiplier=<float>
PANTS_REMOTE_STORE_TIMEOUT_MULTIPLIER
remote_store_timeout_multiplier
2.0
Multiplier used to increase the timeout (starting with value of --remote-store-initial-timeout) between retry attempts in accessing a remote store.
--remote-store-maximum-timeout=<int>
PANTS_REMOTE_STORE_MAXIMUM_TIMEOUT
remote_store_maximum_timeout
10
Maximum timeout (in millseconds) to allow between retry attempts in accessing a remote store.
--remote-instance-name=<str>
PANTS_REMOTE_INSTANCE_NAME
remote_instance_name
None
Name of the remote execution instance to use. Used for routing within --remote-execution-server and --remote-store-server.
--remote-ca-certs-path=<str>
PANTS_REMOTE_CA_CERTS_PATH
remote_ca_certs_path
None
Path to a PEM file containing CA certificates used for verifying secure connections to --remote-execution-server and --remote-store-server. If not specified, TLS will not be used.
--remote-oauth-bearer-token-path=<str>
PANTS_REMOTE_OAUTH_BEARER_TOKEN_PATH
remote_oauth_bearer_token_path
None
Path to a file containing an oauth token to use for grpc connections to --remote-execution-server and --remote-store-server. If not specified, no authorization will be performed.
--remote-execution-extra-platform-properties="['<str>', '<str>', ...]"
PANTS_REMOTE_EXECUTION_EXTRA_PLATFORM_PROPERTIES
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="{'key1': val1, 'key2': val2, ...}"
PANTS_REMOTE_EXECUTION_HEADERS
remote_execution_headers
{}
Headers to set on remote execution requests. Format: header=value. Pants itself may add additional headers.
--remote-execution-overall-deadline-secs=<int>
PANTS_REMOTE_EXECUTION_OVERALL_DEADLINE_SECS
remote_execution_overall_deadline_secs
3600
Overall timeout in seconds for each remote execution request from time of submission
--files-not-found-behavior=<FilesNotFoundBehavior>
PANTS_FILES_NOT_FOUND_BEHAVIOR
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=<OwnersNotFoundBehavior>
PANTS_OWNERS_NOT_FOUND_BEHAVIOR
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-patterns="['<str>', '<str>', ...]"
PANTS_BUILD_PATTERNS
build_patterns
[ "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 ignorepatterns, use the option `--build-ignore`.
--build-ignore="['<str>', '<str>', ...]"
PANTS_BUILD_IGNORE
build_ignore
[]
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="['<str>', '<str>', ...]"
PANTS_BUILD_FILE_PRELUDE_GLOBS
build_file_prelude_globs
[]
Python files to evaluate and whose symbols should be exposed to all BUILD files. See https://www.pantsbuild.org/v2.2/docs/macros.
--subproject-roots="['<str>', '<str>', ...]"
PANTS_SUBPROJECT_ROOTS
subproject_roots
[]
Paths that correspond with build roots for any subproject that this project depends on.
--loop-max=<int>
PANTS_LOOP_MAX
loop_max
4294967296
The maximum number of times to loop when `--loop` is specified.
--streaming-workunits-report-interval=<float>
PANTS_STREAMING_WORKUNITS_REPORT_INTERVAL
streaming_workunits_report_interval
1.0
Interval in seconds between when streaming workunit event receivers will be polled.
--streaming-workunits-handlers="['<str>', '<str>', ...]"
PANTS_STREAMING_WORKUNITS_HANDLERS
streaming_workunits_handlers
[]
Use this option to name Subsystems which will receive streaming workunit events. For instance, `--streaming-workunits-handlers="['pants.reporting.workunit.Workunits']"` will register a Subsystem called Workunits defined in the module "pants.reporting.workunit".
Deprecated options
--pants-bootstrapdir=<dir>
PANTS_BOOTSTRAPDIR
pants_bootstrapdir
None
Deprecated, will be removed in version: 2.3.0.dev1.
Unused.
Unused.
--pants-configdir=<dir>
PANTS_CONFIGDIR
pants_configdir
None
Deprecated, will be removed in version: 2.3.0.dev1.
Unused.
Unused.
--pantsd-pailgun-quit-timeout=<float>
PANTS_PANTSD_PAILGUN_QUIT_TIMEOUT
pantsd_pailgun_quit_timeout
5.0
Deprecated, will be removed in version: 2.3.0.dev0.
The pailgun client has been rewritten to no longer use this
The length of time (in seconds) to wait for further output after sending a signal to the remote pantsd process before killing it.
Updated about a month ago