HomeDocs
DocsCommunityTestimonialsUsersGitHubTwitterBlogJobsTermsPrivacyCookies
TermsPrivacyCookies
Hey! These docs are for version 2.8, which is no longer officially supported. Click here for the latest version, 2.17!


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.

## <code>dependencies</code>

<span style="color: purple">type: <code>Iterable[str] | None</code></span> <span style="color: green">default: <code>None</code></span>

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.

## <code>description</code>

<span style="color: purple">type: <code>str | None</code></span> <span style="color: green">default: <code>None</code></span>

A human-readable description of the target.

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

## <code>extra_build_args</code>

<span style="color: purple">type: <code>Iterable[str] | None</code></span> <span style="color: green">default: <code>()</code></span>

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.

## <code>image_tags</code>

<span style="color: purple">type: <code>Iterable[str] | None</code></span> <span style="color: green">default: <code>('latest',)</code></span>

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')}.

## <code>registries</code>

<span style="color: purple">type: <code>Iterable[str] | None</code></span> <span style="color: green">default: <code>('<all default registries>',)</code></span>

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:



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.

## <code>repository</code>

<span style="color: purple">type: <code>str | None</code></span> <span style="color: green">default: <code>None</code></span>

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.

## <code>restartable</code>

<span style="color: purple">type: <code>bool</code></span> <span style="color: green">default: <code>False</code></span>

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

## <code>skip_push</code>

<span style="color: purple">type: <code>bool</code></span> <span style="color: green">default: <code>False</code></span>

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

## <code>source</code>

<span style="color: purple">type: <code>str | None</code></span> <span style="color: green">default: <code>'Dockerfile'</code></span>

The Dockerfile to use when building the Docker image.

## <code>tags</code>

<span style="color: purple">type: <code>Iterable[str] | None</code></span> <span style="color: green">default: <code>None</code></span>

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.