Skip to main content
Version: 2.21

local_environment

Configuration of a local execution environment for specific platforms.

Environment configuration includes the platforms the environment is compatible with, and optionally a fallback environment, along with environment-aware options (such as environment variables and search paths) used by Pants to execute processes in this environment.

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.

Only one local_environment may be defined in [environments-preview].names per platform, and when __local__ is specified as the environment, the local_environment that matches the current platform (if defined) will be selected.

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.

compatible_platforms​

Iterable[str] | None
default: ('linux_arm64', 'linux_x86_64', 'macos_arm64', 'macos_x86_64')

Which platforms this environment can be used with.

This is used for Pants to automatically determine which environment target to use for the user's machine when the environment is set to the special value __local__. Currently, there cannot be more than one environment target registered in [environments-preview].names for a particular platform. If there is no environment target for a certain platform, Pants will use the options system instead to determine environment variables and executable search paths.

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.docker

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.docker

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

fallback_environment​

str | None
default: None

The environment to fallback to when this local environment cannot be used because the field compatible_platforms is not compatible with the local host.

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 this specific local environment cannot be used.

Tip: when targeting Linux, it can be particularly helpful to fallback to a docker_environment or remote_environment target. That allows you to prefer using the local host when possible, which often has less overhead (particularly compared to Docker). If the local host is not compatible, then Pants will use Docker or remote execution to still run in a similar 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_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.java

Overrides the default value from the option [jvm].global_options 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.core

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

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.core

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.core

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.core

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.core

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.shell

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.core

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.core

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.