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

one of: trace, debug, info, warn, error
default: info
Set the logging level. The logging levels are one of: "error", "warn", "info", "debug", "trace".

--[no-]colors
PANTS_COLORS
colors

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

default: []
Read additional specs (e.g., target addresses or file names), one per line,from these files.

--[no-]dynamic-ui
PANTS_DYNAMIC_UI
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; and false otherwise.

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

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

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

default: []
Exclude target roots that match these regexes.

--[no-]loop
PANTS_LOOP
loop

default: False
Run goals continuously as file changes are detected.

--[no-]show-log-target
PANTS_SHOW_LOG_TARGET
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="{'key1': val1, 'key2': val2, ...}"
PANTS_LOG_LEVELS_BY_TARGET
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"}'`

--[no-]log-show-rust-3rdparty
PANTS_LOG_SHOW_RUST_3RDPARTY
log_show_rust_3rdparty

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

default: []
Regexps matching warning strings to ignore, e.g. ["DEPRECATED: scope some_scope will be removed"]. The regexps will be matched from the start of the warning string, and will always be case-insensitive. See the `warnings` Python module documentation for more background on how these are used.

--pants-version=<str>
PANTS_VERSION
pants_version

default: 2.0.0b3
Use this pants version. Note Pants code 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. This option is useful to set in your pants.toml, however, and then you can grep the value to select which version to use for setup scripts (e.g. `./pants`), runner scripts, IDE plugins, etc. For example, the setup script we distribute at https://www.pantsbuild.org/docs/installation uses this value to determine which Pythonversion to run with. You may find the version of the Pants instance you are running by using -v, -V, or --version.

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

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

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

default: []
Allow backends to be loaded from these plugins. The default backends for each plugin will be loaded automatically. Other backends in a plugin can be loaded by listing them in --backend-packages.

--[no-]plugins-force-resolve
PANTS_PLUGINS_FORCE_RESOLVE
plugins_force_resolve

default: False
Re-resolve plugins even if previously resolved.

--plugin-cache-dir=<str>
PANTS_PLUGIN_CACHE_DIR
plugin_cache_dir

default: /Users/benjyw/.cache/pants/plugins
Cache resolved plugin requirements here.

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

default: []
Register rules 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.

--pants-bootstrapdir=<dir>
PANTS_BOOTSTRAPDIR
pants_bootstrapdir

default: /Users/benjyw/.cache/pants
Use this dir for global cache.

--pants-configdir=<dir>
PANTS_CONFIGDIR
pants_configdir

default: /Users/benjyw/.config/pants
Use this dir for global config files.

--pants-workdir=<dir>
PANTS_WORKDIR
pants_workdir

default: /Users/benjyw/src/pants/.pants.d
Write intermediate output files to this dir.

--pants-physical-workdir-base=<dir>
PANTS_PHYSICAL_WORKDIR_BASE
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-supportdir=<dir>
PANTS_SUPPORTDIR
pants_supportdir

default: /Users/benjyw/src/pants/build-support
Use support files from this dir.

--pants-distdir=<dir>
PANTS_DISTDIR
pants_distdir

default: /Users/benjyw/src/pants/dist
Write end-product artifacts to this dir.

--[no-]pants-distdir-legacy-paths
PANTS_DISTDIR_LEGACY_PATHS
pants_distdir_legacy_paths

default: True
Whether to write binaries to the pre-2.0 paths under distdir. These legacy paths are not qualified by target address, so may be ambiguous. This option is a temporary mechanism for easing transition to 2.0. We recommemd switching to the new, unambiguous paths ASAP, by setting this option to true.

--pants-subprocessdir=<str>
PANTS_SUBPROCESSDIR
pants_subprocessdir

default: /Users/benjyw/src/pants/.pids
The directory to use for tracking subprocess metadata, if any. 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

default:

[
  "/Users/benjyw/src/pants/pants.toml"
]

Paths to Pants config files.

--[no-]pantsrc
PANTS_PANTSRC
pantsrc

default: True
Use pantsrc files.

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

default:

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

default: []
Add these directories to PYTHONPATH to search for plugins.

--[no-]verify-config
PANTS_VERIFY_CONFIG
verify_config

default: True
Verify that all config file values correspond to known options.

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

default:

[
  ".*/",
  "/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 inherently ignored. --pants-ignore can be used in tandem with --pants-ignore-use-gitignore, and any rules specified here apply after rules specified in a .gitignore file.

--[no-]pants-ignore-use-gitignore
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.

-d=<dir>, --logdir=<dir>
PANTS_LOGDIR
logdir

default: None
Write logs to files under this directory.

--[no-]pantsd
PANTS_PANTSD
pantsd

default: True
Enables use of the Pants daemon (pantsd). pantsd can significantly improve runtime performance by lowering per-run startup cost, and by caching filesystem operations and rule execution.

--[no-]concurrent
PANTS_CONCURRENT
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

--pantsd-timeout-when-multiple-invocations=<float>
PANTS_PANTSD_TIMEOUT_WHEN_MULTIPLE_INVOCATIONS
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=<int>
PANTS_PANTSD_MAX_MEMORY_USAGE
pantsd_max_memory_usage

default: 1073741824
The maximum memory usage of a pantsd process (in bytes). There is at most one pantsd process per workspace.

--native-engine-visualize-to=<dir_option>
PANTS_NATIVE_ENGINE_VISUALIZE_TO
native_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.

--[no-]print-exception-stacktrace
PANTS_PRINT_EXCEPTION_STACKTRACE
print_exception_stacktrace

default: False
Print to console the full exception stack trace if encountered.

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

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

--pantsd-pailgun-quit-timeout=<float>
PANTS_PANTSD_PAILGUN_QUIT_TIMEOUT
pantsd_pailgun_quit_timeout

default: 5.0
The length of time (in seconds) to wait for further output after sending a signal to the remote pantsd process before killing it.

--pantsd-log-dir=<str>
PANTS_PANTSD_LOG_DIR
pantsd_log_dir

default: None
The directory to log pantsd output to.

--pantsd-invalidation-globs="['<str>', '<str>', ...]"
PANTS_PANTSD_INVALIDATION_GLOBS
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.

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

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

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

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

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

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

--ca-certs-path=<str>
PANTS_CA_CERTS_PATH
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.

--[no-]remote-execution
PANTS_REMOTE_EXECUTION
remote_execution

default: False
Enables remote workers for increased parallelism. (Alpha)

--remote-store-server="['<str>', '<str>', ...]"
PANTS_REMOTE_STORE_SERVER
remote_store_server

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

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

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

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

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

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

default: 5
Number of remote stores to concurrently allow connections to.

--remote-execution-process-cache-namespace=<str>
PANTS_REMOTE_EXECUTION_PROCESS_CACHE_NAMESPACE
remote_execution_process_cache_namespace

default: None
The cache namespace for remote process execution. Bump this to invalidate every artifact's remote execution. This is the remote execution equivalent of the legacy cache-key-gen-version flag.

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

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

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

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

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

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

default: 3600
Overall timeout in seconds for each remote execution request from time of submission

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

default: 8
Number of concurrent processes that may be executed locally.

--process-execution-remote-parallelism=<int>
PANTS_PROCESS_EXECUTION_REMOTE_PARALLELISM
process_execution_remote_parallelism

default: 128
Number of concurrent processes that may be executed remotely.

--[no-]process-execution-cleanup-local-dirs
PANTS_PROCESS_EXECUTION_CLEANUP_LOCAL_DIRS
process_execution_cleanup_local_dirs

default: True
Whether or not to cleanup directories used for local process execution (primarily useful for e.g. debugging).

--process-execution-speculation-delay=<float>
PANTS_PROCESS_EXECUTION_SPECULATION_DELAY
process_execution_speculation_delay

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

one of: 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-use-local-cache
PANTS_PROCESS_EXECUTION_USE_LOCAL_CACHE
process_execution_use_local_cache

default: True
Whether to keep process executions in a local cache persisted to disk.

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

default: False
Whether or not to use nailgun to run the requests that are marked as nailgunnable.

--build-patterns="['<str>', '<str>', ...]"
PANTS_BUILD_PATTERNS
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 ignorepatterns, use the option `--build-ignore`.

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

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

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

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

default: []
Paths that correspond with build roots for any subproject that this project depends on.

--files-not-found-behavior=<FilesNotFoundBehavior>
PANTS_FILES_NOT_FOUND_BEHAVIOR
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=<OwnersNotFoundBehavior>
PANTS_OWNERS_NOT_FOUND_BEHAVIOR
owners_not_found_behavior

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

--loop-max=<int>
PANTS_LOOP_MAX
loop_max

default: 4294967296
The maximum number of times to loop when `--loop` is specified.

--[no-]lock
PANTS_LOCK
lock

default: True
Use a global lock to exclude other versions of Pants from running during critical operations.

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

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

default: []
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".

--[no-]v1
PANTS_V1
v1

default: False
Deprecated, will be removed in version: 2.1.0.dev0.
The v1 engine no longer exists. This option does nothing.
Enables execution of v1 Tasks.

--[no-]v2
PANTS_V2
v2

default: True
Deprecated, will be removed in version: 2.1.0.dev0.
The v2 engine is the only one available. This option does nothing.
Enables execution of v2 @goal_rules.

--option-name-check-distance=<int>
PANTS_OPTION_NAME_CHECK_DISTANCE
option_name_check_distance

default: 2
Deprecated, will be removed in version: 2.1.0.dev0.
The option `--option-name-check-distance` no longer does anything, as Pants now uses a different method to compute suggestions.
The maximum Levenshtein distance to use when offering suggestions for invalid option names.

--plugins2="['<str>', '<str>', ...]"
PANTS_PLUGINS2
plugins2

default: []
Deprecated, will be removed in version: 2.1.0.dev0.
Use --plugins instead.
Allow backends to be loaded from these plugins. The default backends for each plugin will be loaded automatically. Other backends in a plugin can be loaded by listing them in --backend-packages.

--backend-packages2="['<str>', '<str>', ...]"
PANTS_BACKEND_PACKAGES2
backend_packages2

default: []
Deprecated, will be removed in version: 2.1.0.dev0.
Use --backend-packages instead.
Register rules 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.

--spec-file="['<str>', '<str>', ...]"
PANTS_SPEC_FILE
spec_file

default: []
Deprecated, will be removed in version: 2.1.0.dev0.
Use --spec-files
Read additional specs from this file (e.g. target addresses or file names). Each spec should be one per line.

--binaries-baseurls="['<str>', '<str>', ...]"
PANTS_BINARIES_BASEURLS
binaries_baseurls

default:

[
  "https://binaries.pantsbuild.org"
]

Deprecated, will be removed in version: 2.1.0.dev0.
This option has no effect
List of URLs from which binary tools are downloaded. URLs are searched in order until the requested path is found.

--binaries-fetch-timeout-secs=<int>
PANTS_BINARIES_FETCH_TIMEOUT_SECS
binaries_fetch_timeout_secs

default: 30
Deprecated, will be removed in version: 2.1.0.dev0.
This option has no effect
Timeout in seconds for URL reads when fetching binary tools from the repos specified by --baseurls.

--binaries-path-by-id="{'key1': val1, 'key2': val2, ...}"
PANTS_BINARIES_PATH_BY_ID
binaries_path_by_id

default: {}
Deprecated, will be removed in version: 2.1.0.dev0.
This option has no effect
Maps output of uname for a machine to a binary search path: (sysname, id) -> (os, arch), e.g. {('darwin', '15'): ('mac', '10.11'), ('linux', 'arm32'): ('linux', 'arm32')}.

--[no-]allow-external-binary-tool-downloads
PANTS_ALLOW_EXTERNAL_BINARY_TOOL_DOWNLOADS
allow_external_binary_tool_downloads

default: True
Deprecated, will be removed in version: 2.1.0.dev0.
This option has no effect
If False, require BinaryTool subclasses to download their contents from urls generated from --binaries-baseurls, even if the tool has an external url generator. This can be necessary if using Pants in an environment which cannot contact the wider Internet.

--[no-]remote-execution-enable-streaming
PANTS_REMOTE_EXECUTION_ENABLE_STREAMING
remote_execution_enable_streaming

default: True
Deprecated, will be removed in version: 2.1.0.dev0.
This option is no longer applicable.
This option no longer does anything. (It used to enable the streaming remote execution client which is now the only remote execution client.)

--[no-]dependency-inference
PANTS_DEPENDENCY_INFERENCE
dependency_inference

default: False
Deprecated, will be removed in version: 2.1.0.dev0.
This option is now a noop: individual inference providers can be independently enabled or disabled on their relevant subsystems. For Python, see `./pants help python-infer`.
Enable dependency inference, meaning that Pants will read your source code to infer the `dependencies` field for you in BUILD files. You can check what Pants inferred by running `./pants dependencies` on your target. You may still need to explicitly provide some `dependencies` that cannot be inferred.