HomeDocs

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

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

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

type: `str | None`
default: `None`

A human-readable description of the target.

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

## `docker_env_vars`

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

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

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

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

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

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

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

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

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

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

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

type: `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_go_search_paths`

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

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

type: `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.

## `pex_executable_search_paths`

type: `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.

## `python_bootstrap_names`

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

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

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

type: `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_path`

type: `Iterable[str] | None`
default: `None`
backend: `pants.backend.shell`

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

## `subprocess_environment_env_vars`

type: `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.

## `tags`

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

type: `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.