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.

By default, will use a Dockerfile from the same directory as the BUILD file this target is defined in. Point at another file with the source field, or use the instructions field to have the Dockerfile contents verbatim directly in the BUILD file.

dependencies

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

type: str | None
default: None

A human-readable description of the target.

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

extra_build_args

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

type: 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 Tagging Docker images.

instructions

type: Iterable[str] | None
default: None

The Dockerfile content, typically one instruction per list item.

Use the source field instead if you prefer having the Dockerfile in your project source tree.

Example:

# example/BUILD
docker_image(
  instructions=[
    "FROM base/image:1.0",
    "RUN echo example",
  ],
)

registries

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

type: str | None
default: None

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

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

type: bool
default: False

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

secrets

type: Dict[str, str] | None
default: None

Secret files to expose to the build (only if BuildKit enabled).

Secrets may use absolute paths, or paths relative to your project build root, or the BUILD file if prefixed with ./. The id should be valid as used by the Docker build --secret option. See Docker secrets for more information.

Example:

docker_image(
    secrets={
        "mysecret": "/var/secrets/some-secret",
        "repo-secret": "src/proj/secrets/some-secret",
        "target-secret": "./secrets/some-secret",
    }
)

skip_hadolint

type: bool
default: False

If true, don't run hadolint on this target's Dockerfile.

skip_push

type: bool
default: False

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

source

type: str | None
default: 'Dockerfile'

The Dockerfile to use when building the Docker image.

Use the instructions field instead if you prefer not having the Dockerfile in your project source tree.

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.

target_stage

type: str | None
default: None

Specify target build stage, rather than building the entire Dockerfile.

When using multi-stage build, you may name your stages, and can target them when building to only selectively build a certain stage. See also the --docker-build-target-stage option.

Read more about multi-stage Docker builds


Did this page help you?