remote_environment

---

Configuration of a remote execution environment used for building your code.

Environment configuration includes platform properties and a fallback environment, as well as environment-aware options (such as environment variables and search paths) used by Pants to execute processes in this remote environment.

Note that you must also configure remote execution with the global options like remote_execution and remote_execution_address.

To use this environment, map this target's address with a memorable name in [environments-preview].names. You can then consume this environment by specifying the name in the environment field defined on other targets.

Often, it is only necessary to have a single remote_environment target for your repository, but it can be useful to have >1 so that you can set different extra_platform_properties. For example, with some servers, you could use this to configure a different Docker image per environment.

Backend: pants.core

---

apache_thrift_thrift_search_paths

Iterable[str] | None

default: None

backend: pants.backend.codegen.thrift.apache.python

Overrides the default value from the option [apache-thrift].thrift_search_paths when this environment target is active.

cache_binary_discovery

bool

default: False

If true, will cache system binary discovery, e.g. finding Python interpreters.

When safe to do, it is preferable to set this option to True for faster performance by avoiding wasted work. Otherwise, Pants will search for system binaries whenever the Pants daemon is restarted.

However, it is only safe to set this to True if the remote execution environment has a stable environment, e.g. the server will not change versions of installed system binaries. Otherwise, you risk caching results that become stale when the server changes its environment, which may break your builds. With some remote execution servers, you can specify a Docker image to run with via the field extra_platform_properties; if you are able to specify what Docker image to use, and also use a pinned tag of the image, it is likely safe to set this field to true.

description

str | None

default: None

A human-readable description of the target.

Use pants list --documented :: to see all targets with descriptions.

docker_env_vars

Iterable[str] | None

default: None

backend: pants.backend.experimental.helm

Overrides the default value from the option [docker].env_vars when this environment target is active.

docker_executable_search_paths

Iterable[str] | None

default: None

backend: pants.backend.experimental.helm

Overrides the default value from the option [docker].executable_search_paths when this environment target is active.

extra_platform_properties

Iterable[str] | None

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.

fallback_environment

str | None

default: None

The environment to fallback to when remote execution is disabled via the global option --remote-execution.

Must be an environment name from the option [environments-preview].names, the special string __local__ to use the relevant local environment, or the Python value None to error when remote execution is disabled.

Tip: if you are using a Docker image with your remote execution environment (usually enabled by setting the field extra_platform_properties), then it can be useful to fallback to an equivalent docker_image target so that you have a consistent execution environment.

go_generate_env_vars

Iterable[str] | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [go-generate].env_vars when this environment target is active.

golang_cgo_c_flags

Iterable[str] | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [golang].cgo_c_flags when this environment target is active.

golang_cgo_cxx_flags

Iterable[str] | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [golang].cgo_cxx_flags when this environment target is active.

golang_cgo_fortran_binary_name

str | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [golang].cgo_fortran_binary_name when this environment target is active.

golang_cgo_fortran_flags

Iterable[str] | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [golang].cgo_fortran_flags when this environment target is active.

golang_cgo_gcc_binary_name

str | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [golang].cgo_gcc_binary_name when this environment target is active.

golang_cgo_gxx_binary_name

str | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [golang].cgo_gxx_binary_name when this environment target is active.

golang_cgo_linker_flags

Iterable[str] | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [golang].cgo_linker_flags when this environment target is active.

golang_cgo_tool_search_paths

Iterable[str] | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [golang].cgo_tool_search_paths when this environment target is active.

golang_external_linker_binary_name

str | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [golang].external_linker_binary_name when this environment target is active.

golang_extra_tools

Iterable[str] | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [golang].extra_tools when this environment target is active.

golang_go_search_paths

Iterable[str] | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [golang].go_search_paths when this environment target is active.

golang_subprocess_env_vars

Iterable[str] | None

default: None

backend: pants.backend.experimental.go

Overrides the default value from the option [golang].subprocess_env_vars when this environment target is active.

jvm_global_options

Iterable[str] | None

default: None

backend: pants.backend.experimental.scala

Overrides the default value from the option [jvm].global_options when this environment target is active.

nfpm_default_mtime

str | None

default: None

backend: pants.backend.experimental.nfpm

Overrides the default value from the option [nfpm].default_mtime when this environment target is active.

nodejs_corepack_env_vars

Iterable[str] | None

default: None

backend: pants.backend.experimental.javascript

Overrides the default value from the option [nodejs].corepack_env_vars when this environment target is active.

nodejs_executable_search_paths

Iterable[str] | None

default: None

backend: pants.backend.experimental.javascript

Overrides the default value from the option [nodejs].executable_search_paths when this environment target is active.

nodejs_search_path

Iterable[str] | None

default: None

backend: pants.backend.experimental.javascript

Overrides the default value from the option [nodejs].search_path when this environment target is active.

pex_executable_search_paths

Iterable[str] | None

default: None

backend: pants.backend.build_files.fmt.ruff

Overrides the default value from the option [pex].executable_search_paths when this environment target is active.

platform

'linux_arm64' | 'linux_x86_64' | 'macos_arm64' | 'macos_x86_64' | None

default: 'linux_x86_64'

The platform used by the remote execution environment.

pyenv_python_provider_installation_extra_env_vars

Iterable[str] | None

default: None

backend: pants.backend.python.providers.experimental.pyenv

Overrides the default value from the option [pyenv-python-provider].installation_extra_env_vars when this environment target is active.

python_bootstrap_names

Iterable[str] | None

default: None

backend: pants.backend.build_files.fmt.ruff

Overrides the default value from the option [python-bootstrap].names when this environment target is active.

python_bootstrap_search_path

Iterable[str] | None

default: None

backend: pants.backend.build_files.fmt.ruff

Overrides the default value from the option [python-bootstrap].search_path when this environment target is active.

python_native_code_cpp_flags

Iterable[str] | None

default: None

backend: pants.backend.build_files.fmt.ruff

Overrides the default value from the option [python-native-code].cpp_flags when this environment target is active.

python_native_code_ld_flags

Iterable[str] | None

default: None

backend: pants.backend.build_files.fmt.ruff

Overrides the default value from the option [python-native-code].ld_flags when this environment target is active.

shell_setup_executable_search_paths

Iterable[str] | None

default: None

backend: pants.backend.experimental.makeself

Overrides the default value from the option [shell-setup].executable_search_paths when this environment target is active.

subprocess_environment_env_vars

Iterable[str] | None

default: None

backend: pants.backend.build_files.fmt.ruff

Overrides the default value from the option [subprocess-environment].env_vars when this environment target is active.

system_binaries_system_binary_paths

Iterable[str] | None

default: None

backend: pants.backend.build_files.fmt.ruff

Overrides the default value from the option [system-binaries].system_binary_paths when this environment target is active.

tags

Iterable[str] | None

default: None

Arbitrary strings to describe a target.

For example, you may tag some test targets with 'integration_test' so that you could run pants --tag='integration_test' test :: to only run on targets with that tag.

test_extra_env_vars

Iterable[str] | None

default: None

backend: pants.core

Overrides the default value from the option [test].extra_env_vars when this environment target is active.