Skip to main content
Version: 2.23 (prerelease)

docker

Options for interacting with Docker.

Backend: pants.backend.docker.lint.hadolint

Config section: [docker]

Basic options​

build_args​

--docker-build-args="[<shell_str>, <shell_str>, ...]"
PANTS_DOCKER_BUILD_ARGS
pants.toml
[docker]
build_args = [
    <shell_str>,
    <shell_str>,
    ...,
]
default: []

Global build arguments (for Docker --build-arg options) to use for all docker build invocations.

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.

Example:

[docker]
build_args = ["VAR1=value", "VAR2"]

Use the extra_build_args field on a docker_image target for additional image specific build arguments.

build_hosts​

--docker-build-hosts="{'key1': val1, 'key2': val2, ...}"
PANTS_DOCKER_BUILD_HOSTS
pants.toml
[docker.build_hosts]
key1 = val1
key2 = val2
...
default: {}

Hosts entries to be added to the /etc/hosts file in all built images.

Example:

[docker]
build_hosts = {"docker": "10.180.0.1", "docker2": "10.180.0.2"}

Use the extra_build_hosts field on a docker_image target for additional image specific host entries.

build_no_cache​

--[no-]docker-build-no-cache
PANTS_DOCKER_BUILD_NO_CACHE
pants.toml
[docker]
build_no_cache = <bool>
default: False

Do not use the Docker cache when building images.

build_target_stage​

--docker-build-target-stage=<str>
PANTS_DOCKER_BUILD_TARGET_STAGE
pants.toml
[docker]
build_target_stage = <str>
default: None

Global default value for target_stage on docker_image targets, overriding the field value on the targets, if there is a matching stage in the Dockerfile.

This is useful to provide from the command line, to specify the target stage to build for at execution time.

build_verbose​

--[no-]docker-build-verbose
PANTS_DOCKER_BUILD_VERBOSE
pants.toml
[docker]
build_verbose = <bool>
default: False

Whether to log the Docker output to the console. If false, only the image ID is logged.

default_context_root​

--docker-default-context-root=<workspace_path>
PANTS_DOCKER_DEFAULT_CONTEXT_ROOT
pants.toml
[docker]
default_context_root = <workspace_path>
default:

Provide a default Docker build context root path for docker_image targets that does not specify their own context_root field.

The context root is relative to the build root by default, but may be prefixed with ./ to be relative to the directory of the BUILD file of the docker_image.

Examples:

--default-context-root=src/docker
--default-context-root=./relative_to_the_build_file

default_repository​

--docker-default-repository=<str>
PANTS_DOCKER_DEFAULT_REPOSITORY
pants.toml
[docker]
default_repository = <str>
default: {name}

Configure the default repository name used in the Docker image tag.

The value is formatted and may reference these variables (in addition to the normal placeholders derived from the Dockerfile and build args etc):

  • name
  • directory
  • parent_directory
  • full_directory
  • target_repository

Example: --default-repository="{directory}/{name}".

The name variable is the docker_image's target name.

With the directory variables available, given a sample repository path of baz/foo/bar/BUILD, then directory is bar, parent_directory is foo and full_directory will be baz/foo/bar.

Use the repository field to set this value directly on a docker_image target.

Registries may override the repository value for a specific registry.

Any registries or tags are added to the image name as required, and should not be part of the repository name.

experimental_enable_podman​

--[no-]docker-experimental-enable-podman
PANTS_DOCKER_EXPERIMENTAL_ENABLE_PODMAN
pants.toml
[docker]
experimental_enable_podman = <bool>
default: True

Allow support for podman when available.

registries​

--docker-registries="{'key1': val1, 'key2': val2, ...}"
PANTS_DOCKER_REGISTRIES
pants.toml
[docker.registries]
key1 = val1
key2 = val2
...
default: {}

Configure Docker registries. The schema for a registry entry is as follows:

{
    "registry-alias": {
        "address": "registry-domain:port",
        "default": bool,
        "extra_image_tags": [],
        "skip_push": bool,
        "repository": str,
        "use_local_alias": bool,
    },
    ...
}

If no registries are provided in a docker_image target, then all default addresses will be used, if any.

The docker_image.registries may be provided with a list of registry addresses and registry aliases prefixed with @ to be used instead of the defaults.

A configured registry is marked as default either by setting default = true or with an alias of "default".

A docker_image may be pushed to a subset of registries using the per registry skip_push option rather then the all or nothing toggle of the field option skip_push on the docker_image target.

Any image tags that should only be added for specific registries may be provided as the extra_image_tags option. The tags may use value formatting the same as for the image_tags field of the docker_image target.

When a registry provides a repository value, it will be used instead of the docker_image.repository or the default repository. Using the placeholders {target_repository} or {default_repository} those overridden values may be incorporated into the registry specific repository value.

If use_local_alias is true, a built image is additionally tagged locally using the registry alias as the value for repository (i.e. the additional image tag is not pushed) and will be used for any pants run requests.

run_args​

--docker-run-args="[<shell_str>, <shell_str>, ...]"
PANTS_DOCKER_RUN_ARGS
pants.toml
[docker]
run_args = [
    <shell_str>,
    <shell_str>,
    ...,
]
default: []

Additional arguments to use for docker run invocations.

Example:

$ pants run --docker-run-args="-p 127.0.0.1:80:8080/tcp --name demo" src/example:image -- [image entrypoint args]

To provide the top-level options to the docker client, use [docker].env_vars to configure the Environment variables as appropriate.

The arguments for the image entrypoint may be passed on the command line after a double dash (--), or using the --run-args option.

Defaults to --interactive --tty when stdout is connected to a terminal.

use_buildx​

--[no-]docker-use-buildx
PANTS_DOCKER_USE_BUILDX
pants.toml
[docker]
use_buildx = <bool>
default: False

Use buildx (and BuildKit) for builds.

Advanced options​

env_vars​

--docker-env-vars="[<shell_str>, <shell_str>, ...]"
PANTS_DOCKER_ENV_VARS
pants.toml
[docker]
env_vars = [
    <shell_str>,
    <shell_str>,
    ...,
]
default: []

Environment variables to set for docker invocations.

Entries are either strings in the form ENV_VAR=value to set an explicit value; or just ENV_VAR to copy the value from Pants's own environment.

Can be overriden by fielddocker_env_vars on local_environment, docker_environment, or remote_environmenttargets.

executable_search_paths​

--docker-executable-search-paths="[<binary-paths>, <binary-paths>, ...]"
PANTS_DOCKER_EXECUTABLE_SEARCH_PATHS
pants.toml
[docker]
executable_search_paths = [
    <binary-paths>,
    <binary-paths>,
    ...,
]
default: 
[
  "<PATH>"
]

The PATH value that will be used to find the Docker client and any tools required. The special string "<PATH>" will expand to the contents of the PATH env var.

Can be overriden by fielddocker_executable_search_paths on local_environment, docker_environment, or remote_environmenttargets.

optional_tools​

--docker-optional-tools="['<str>', '<str>', ...]"
PANTS_DOCKER_OPTIONAL_TOOLS
pants.toml
[docker]
optional_tools = [
    '<str>',
    '<str>',
    ...,
]
default: []

List any additional executables which are not mandatory for Docker to work, but which should be included if available. The paths to these tools will be included in the PATH used in the execution sandbox, so that they may be used by the Docker client.

tailor​

--[no-]docker-tailor
PANTS_DOCKER_TAILOR
pants.toml
[docker]
tailor = <bool>
default: True

If true, add docker_image targets with the tailor goal.

tools​

--docker-tools="['<str>', '<str>', ...]"
PANTS_DOCKER_TOOLS
pants.toml
[docker]
tools = [
    '<str>',
    '<str>',
    ...,
]
default: []

List any additional executable tools required for Docker to work. The paths to these tools will be included in the PATH used in the execution sandbox, so that they may be used by the Docker client.

Deprecated options​

None

None