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, it 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 on upstream/base images defined by another docker_image are inferred if referenced by a build argument with a default value of the target address.
Example:
# src/docker/downstream/Dockerfile
ARG BASE=src/docker/upstream:image
FROM $BASE
...
Backend: pants.backend.docker
build_network
str | NoneNoneSets the networking mode for the run commands during build. Supported standard values are: bridge, host, none, and container:<name|id>. Any other value is taken as a custom network's name to which the container should connect to.
build_platform
Iterable[str] | NoneNoneSet the target platform(s) for the build.
cache_from
Dict[str, str] | NoneNoneUse an external cache source when building the image.
This option requires BuildKit to be enabled via the Docker subsystem options.
Example:
docker_image(
name="example-local-cache-backend",
cache_to={
"type": "local",
"dest": "/tmp/docker-cache/example"
},
cache_from={
"type": "local",
"src": "/tmp/docker-cache/example"
}
)
Values may use placeholders in curly braces to be interpolated. The placeholders are derived from various sources, such as the Dockerfile instructions and build args.
cache_to
Dict[str, str] | NoneNoneExport image build cache to an external cache destination.
This option requires BuildKit to be enabled via the Docker subsystem options.
Example:
docker_image(
name="example-local-cache-backend",
cache_to={
"type": "local",
"dest": "/tmp/docker-cache/example"
},
cache_from={
"type": "local",
"src": "/tmp/docker-cache/example"
}
)
Values may use placeholders in curly braces to be interpolated. The placeholders are derived from various sources, such as the Dockerfile instructions and build args.
context_root
str | NoneNoneSpecify which directory to use as the Docker build context root. This affects the file paths to use for the COPY and ADD instructions. For example, whether COPY files/f.txt should look for the file relative to the build root: <build root>/files/f.txt vs relative to the BUILD file: <build root>/path_to_build_file/files/f.txt.
Specify the context_root path as files for relative to build root, or as ./files for relative to the BUILD file.
If context_root is not specified, it defaults to [docker].default_context_root.
dependencies
Iterable[str] | NoneNoneAddresses to other targets that this target depends on, e.g. ['helloworld/subdir:lib', 'helloworld/main.py:lib', '3rdparty:reqs#django'].
This augments any dependencies inferred by Pants, such as by analyzing your imports. Use pants dependencies or pants peek on this target to get the final result.
See https://www.pantsbuild.org/2.20/docs/using-pants/key-concepts/targets-and-build-files for more about how addresses are formed, including for generated targets. You can also run pants list :: to find all addresses in your project, or pants list dir to find all addresses defined in that directory.
If the target is in the same BUILD file, you can leave off the BUILD file path, e.g. :tgt instead of helloworld/subdir:tgt. For generated first-party addresses, use ./ for the file path, e.g. ./main.py:tgt; for all other generated targets, use :tgt#generated_name.
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 | NoneNoneA human-readable description of the target.
Use pants list --documented :: to see all targets with descriptions.
extra_build_args
Iterable[str] | None()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.
extra_build_hosts
Dict[str, str] | NoneNoneExtra hosts entries to be added to a container's /etc/hosts file.
Use [docker].build_hosts to set default host entries for all images.
image_labels
Dict[str, str] | NoneNoneProvide image metadata.
Label value may use placeholders in curly braces to be interpolated. The placeholders are derived from various sources, such as the Dockerfile instructions and build args.
See Docker labels for more information.
image_tags
Iterable[str] | None('latest',)Any tags to apply to the Docker image name (the version is usually applied as a tag).
tag may use placeholders in curly braces to be interpolated. The placeholders are derived from various sources, such as the Dockerfile instructions and build args.
See https://www.pantsbuild.org/2.20/docs/docker/tagging-docker-images.
instructions
Iterable[str] | NoneNoneThe Dockerfile content, typically one instruction per list item.
Use the source field instead if you prefer having the Dockerfile in your source tree.
Example:
# example/BUILD
docker_image(
instructions=[
"FROM base/image:1.0",
"RUN echo example",
],
)
output
Dict[str, str] | NoneFrozenDict({'type': 'docker'})Sets the export action for the build result.
This option requires BuildKit to be enabled via the Docker subsystem options.
When using pants publish to publish Docker images to a registry, the output type must be 'docker', as publish expects that the built images exist in the local image store.
Values may use placeholders in curly braces to be interpolated. The placeholders are derived from various sources, such as the Dockerfile instructions and build args.
output_path
str | NoneNoneWhere the built asset should be located.
If undefined, this will use the path to the BUILD file, followed by the target name. For example, src/python/project:app would be src.python.project/app.ext.
When running pants package, this path will be prefixed by --distdir (e.g. dist/).
Warning: setting this value risks naming collisions with other package targets you may have.
pull
boolFalseIf true, then docker will always attempt to pull a newer version of the image.
NOTE: This option cannot be used on images that build off of "transitive" base images referenced by address (i.e. FROM path/to/your/base/Dockerfile).
registries
Iterable[str] | None('<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
str | NoneNoneThe repository name for the Docker image. e.g. "<repository>/<name>".
It uses the [docker].default_repository by default.
Repository may use placeholders in curly braces to be interpolated. The placeholders are derived from various sources, such as the Dockerfile instructions and build args.
Additional placeholders for the repository field are: name, directory, parent_directory, and default_repository.
Registries may also configure the repository value for specific registries.
See the documentation for [docker].default_repository for more information.
restartable
boolFalseIf true, runs of this target with the run goal may be interrupted and restarted when its input files change.
secrets
Dict[str, str] | NoneNoneSecret files to expose to the build (only if BuildKit enabled).
Secrets may use absolute paths, or paths relative to your build root, or the BUILD file if prefixed with ./. Paths to your home directory will be automatically expanded. 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",
"home-dir-secret": "~/.config/some-secret",
"target-secret": "./secrets/some-secret",
}
)
skip_hadolint
boolFalsepants.backend.docker.lint.hadolintIf true, don't run hadolint on this target's Dockerfile.
skip_push
boolFalseIf true, do not push this image to registries when running pants publish.
source
str | None'Dockerfile'The Dockerfile to use when building the Docker image.
Use the instructions field instead if you prefer not having the Dockerfile in your source tree.
squash
boolFalseIf true, then docker will squash newly built layers into a single new layer.
Note that this option is only supported on a Docker daemon with experimental features enabled.
ssh
Iterable[str] | None()SSH agent socket or keys to expose to the build (only if BuildKit enabled) (format: default|<id>[=<socket>|<key>[,<key>]])
The exposed agent and/or keys can then be used in your Dockerfile by mounting them in your RUN instructions:
RUN --mount=type=ssh ...
See Docker documentation for more information.
tags
Iterable[str] | NoneNoneArbitrary 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
str | NoneNoneSpecify 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