Skip to main content
Version: 2.8 (deprecated)

docker_image

The docker_image target describes how to build and tag a Docker image.

Any dependencies, as inferred or explicitly specified, will be included in the Docker build context, after being packaged if applicable.

Backend: ``

dependencies​

Iterable[str] | None
default: None

Addresses to other targets that this target depends on, e.g. ['helloworld/subdir:lib'].

Alternatively, you may include file names. Pants will find which target owns that file, and create a new target from that which only includes the file in its sources field. For files relative to the current BUILD file, prefix with ./; otherwise, put the full path, e.g. ['./sibling.txt', 'resources/demo.json'].

You may exclude dependencies by prefixing with !, e.g. ['!helloworld/subdir:lib', '!./sibling.txt']. Ignores are intended for false positives with dependency inference; otherwise, simply leave off the dependency from the BUILD file.

description​

str | None
default: None

A human-readable description of the target.

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

extra_build_args​

Iterable[str] | None
default: ()

Build arguments (--build-arg) to use when building this image. Entries are either strings in the form ARG_NAME=value to set an explicit value; or just ARG_NAME to copy the value from Pants's own environment.

Use [docker].build_args to set default build args for all images.

image_tags​

Iterable[str] | None
default: ('latest',)

Any tags to apply to the Docker image name (the version is usually applied as a tag).

Each tag may use placeholders in curly braces to be interpolated. The placeholders are derived from various sources, such as the Dockerfile FROM instructions tags and build args.

See {doc_url('tagging-docker-images')}.

registries​

Iterable[str] | None
default: ('<all default registries>',)

List of addresses or configured aliases to any Docker registries to use for the built image.

The address is a domain name with optional port for your registry, and any registry aliases are prefixed with @ for addresses in the [docker].registries configuration section.

By default, all configured registries with default = true are used.

Example:

# pants.toml
[docker]
registries = "@registries.yaml"

# registries.yaml
my-registry-alias:
    address = "myregistrydomain:port"
    default = False  # optional

# example/BUILD
docker_image(
    registries = [
        "@my-registry-alias",
        "myregistrydomain:port",
    ],
)

The above example shows two valid registry options: using an alias to a configured registry and the address to a registry verbatim in the BUILD file.

repository​

str | None
default: None

The repository name for the Docker image. e.g. "<repository>/<name>".

It uses the [docker].default_repository by default.This field value may contain format strings that will be interpolated at runtime. See the documentation for [docker].default_repository for details.

restartable​

bool
default: False

If true, runs of this target with the run goal may be interrupted and restarted when its input files change.

skip_push​

bool
default: False

If set to true, do not push this image to registries when running ./pants publish.

source​

str | None
default: 'Dockerfile'

The Dockerfile to use when building the Docker image.

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.