Version: 2.25 (dev)

docker_environment

Configuration of a Docker environment used for building your code.

Environment configuration includes both Docker-specific information (including the image and platform choice), as well as environment-aware options (such as environment variables and search paths) used by Pants to execute processes in this Docker 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.

Before running Pants using this environment, if you are using Docker Desktop, make sure the option Enable default Docker socket is enabled, you can find it in Docker Desktop Settings > Advanced panel. That option tells Docker to create a socket at /var/run/docker.sock which Pants can use to communicate with Docker.

Backend: pants.core

`image`

str

required

The docker image ID to use when this environment is loaded.

This value may be any image identifier that the local Docker installation can accept. This includes image names with or without tags (e.g. centos6 or centos6:latest), or image names with an immutable digest (e.g. centos@sha256:<some_sha256_value>).

The choice of image ID can affect the reproducibility of builds. Consider using an immutable digest if reproducibility is needed, but regularly ensure that the image is free of relevant bugs or security vulnerabilities.

Note that in order to use an image as a docker_environment it must have a few tools: - /bin/sh - /usr/bin/env - bash - tar

While most images will have these preinstalled, users of base images such as Distroless or scratch will need to bake these tools into the image themselves. All of these except bash are available via busybox.

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

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

`fallback_environment`

str | None

default: None

The environment to fallback to when this Docker environment cannot be used because either the global option --docker-execution is false, or the field platform is not compatible with the local host's CPU architecture (this is only an issue when the local host is Linux; macOS is fine).

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 Docker environment cannot be used.