docker buildx build [OPTIONS] PATH | URL | -
Start a build
build
, b
Name | Type | Default | Description |
---|---|---|---|
--add-host |
stringSlice |
Add a custom host-to-IP mapping (format: host:ip ) |
|
--allow |
stringSlice |
Allow extra privileged entitlement (e.g., network.host , security.insecure ) |
|
--build-arg |
stringArray |
Set build-time variables | |
--build-context |
stringArray |
Additional build contexts (e.g., name=path) | |
--builder |
string |
Override the configured builder instance | |
--cache-from |
stringArray |
External cache sources (e.g., user/app:cache , type=local,src=path/to/dir ) |
|
--cache-to |
stringArray |
Cache export destinations (e.g., user/app:cache , type=local,dest=path/to/dir ) |
|
--cgroup-parent |
string |
Optional parent cgroup for the container | |
-f , --file |
string |
Name of the Dockerfile (default: PATH/Dockerfile ) |
|
--iidfile |
string |
Write the image ID to the file | |
--label |
stringArray |
Set metadata for an image | |
--load |
Shorthand for --output=type=docker |
||
--metadata-file |
string |
Write build result metadata to the file | |
--network |
string |
default |
Set the networking mode for the RUN instructions during build |
--no-cache |
Do not use cache when building the image | ||
--no-cache-filter |
stringArray |
Do not cache specified stages | |
-o , --output |
stringArray |
Output destination (format: type=local,dest=path ) |
|
--platform |
stringArray |
Set target platform for build | |
--progress |
string |
auto |
Set type of progress output (auto , plain , tty ). Use plain to show container output |
--pull |
Always attempt to pull a newer version of the image | ||
--push |
Shorthand for --output=type=registry |
||
-q , --quiet |
Suppress the build output and print image ID on success | ||
--secret |
stringArray |
Secret to expose to the build (format: id=mysecret[,src=/local/secret] ) |
|
--shm-size |
bytes |
0 |
Size of /dev/shm |
--ssh |
stringArray |
SSH agent socket or keys to expose to the build (format: default|<id>[=<socket>|<key>[,<key>]] ) |
|
-t , --tag |
stringArray |
Name and optionally a tag (format: name:tag ) |
|
--target |
string |
Set the target build stage to build | |
--ulimit |
ulimit |
Ulimit options |
The buildx build
command starts a build using BuildKit. This command is similar
to the UI of docker build
command and takes the same flags and arguments.
For documentation on most of these flags, refer to the docker build
documentation. In
here we’ll document a subset of the new flags.
BUILDKIT_INLINE_BUILDINFO_ATTRS=<bool>
inline build info attributes in image config or notBUILDKIT_INLINE_CACHE=<bool>
inline cache metadata to image config or notBUILDKIT_MULTI_PLATFORM=<bool>
opt into determnistic output regardless of multi-platform output or not
docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 .
Other useful built-in args can be found in dockerfile frontend docs.
--allow=ENTITLEMENT
Allow extra privileged entitlement. List of entitlements:
network.host
- Allows executions with host networking.security.insecure
- Allows executions without sandbox. See related Dockerfile extensions.
For entitlements to be enabled, the buildkitd
daemon also needs to allow them
with --allow-insecure-entitlement
(see create --buildkitd-flags
)
Examples
$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .
Same as docker build
command.
There are also useful built-in build args like:
BUILDKIT_CONTEXT_KEEP_GIT_DIR=<bool>
trigger git context to keep the.git
directoryBUILDKIT_INLINE_CACHE=<bool>
inline cache metadata to image config or notBUILDKIT_MULTI_PLATFORM=<bool>
opt into determnistic output regardless of multi-platform output or not
$ docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 .
More built-in build args can be found in dockerfile frontend docs.
--build-context=name=VALUE
Define additional build context with specified contents. In Dockerfile the context can be accessed when FROM name
or --from=name
is used.
When Dockerfile defines a stage with the same name it is overwritten.
The value can be a local source directory, container image (with docker-image:// prefix), Git or HTTP URL.
Replace alpine:latest
with a pinned one:
$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .
Expose a secondary local source directory:
$ docker buildx build --build-context project=path/to/project/source .
# docker buildx build --build-context project=https://github.com/myuser/project.git .
FROM alpine
COPY --from=project myfile /
Same as buildx --builder
.
--cache-from=[NAME|type=TYPE[,KEY=VALUE]]
Use an external cache source for a build. Supported types are registry
,
local
and gha
.
registry
source can import cache from a cache manifest or (special) image configuration on the registry.local
source can import cache from local files previously exported with--cache-to
.gha
source can import cache from a previously exported cache with--cache-to
in your GitHub repository
If no type is specified, registry
exporter is used with a specified reference.
docker
driver currently only supports importing build cache from the registry.
$ docker buildx build --cache-from=user/app:cache .
$ docker buildx build --cache-from=user/app .
$ docker buildx build --cache-from=type=registry,ref=user/app .
$ docker buildx build --cache-from=type=local,src=path/to/cache .
$ docker buildx build --cache-from=type=gha .
More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
--cache-to=[NAME|type=TYPE[,KEY=VALUE]]
Export build cache to an external cache destination. Supported types are
registry
, local
, inline
and gha
.
registry
type exports build cache to a cache manifest in the registry.local
type type exports cache to a local directory on the client.inline
type type writes the cache metadata into the image configuration.gha
type type exports cache through the Github Actions Cache service API.
docker
driver currently only supports exporting inline cache metadata to image
configuration. Alternatively, --build-arg BUILDKIT_INLINE_CACHE=1
can be used
to trigger inline cache exporter.
Attribute key:
mode
- Specifies how many layers are exported with the cache.min
on only exports layers already in the final build stage,max
exports layers for all stages. Metadata is always exported for the whole build.
$ docker buildx build --cache-to=user/app:cache .
$ docker buildx build --cache-to=type=inline .
$ docker buildx build --cache-to=type=registry,ref=user/app .
$ docker buildx build --cache-to=type=local,dest=path/to/cache .
$ docker buildx build --cache-to=type=gha .
More info about cache exporters and available attributes: https://github.com/moby/buildkit#export-cache
Shorthand for --output=type=docker
. Will automatically load the
single-platform build result to docker images
.
To output build metadata such as the image digest, pass the --metadata-file
flag.
The metadata will be written as a JSON object to the specified file. The
directory of the specified file must already exist and be writable.
$ docker buildx build --load --metadata-file metadata.json .
$ cat metadata.json
{
"containerimage.buildinfo": {
"frontend": "dockerfile.v0",
"attrs": {
"context": "https://github.com/crazy-max/buildkit-buildsources-test.git#master",
"filename": "Dockerfile",
"source": "docker/dockerfile:master"
},
"sources": [
{
"type": "docker-image",
"ref": "docker.io/docker/buildx-bin:0.6.1@sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0",
"pin": "sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0"
},
{
"type": "docker-image",
"ref": "docker.io/library/alpine:3.13",
"pin": "sha256:026f721af4cf2843e07bba648e158fb35ecc876d822130633cc49f707f0fc88c"
}
]
},
"containerimage.config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
"containerimage.descriptor": {
"annotations": {
"config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
"org.opencontainers.image.created": "2022-02-08T21:28:03Z"
},
"digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3",
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"size": 506
},
"containerimage.digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3"
}
-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]
Sets the export action for the build result. In docker build
all builds finish
by creating a container image and exporting it to docker images
. buildx
makes
this step configurable allowing results to be exported directly to the client,
oci image tarballs, registry etc.
Buildx with docker
driver currently only supports local, tarball exporter and
image exporter. docker-container
driver supports all the exporters.
If just the path is specified as a value, buildx
will use the local exporter
with this path as the destination. If the value is "-", buildx
will use tar
exporter and write to stdout
.
$ docker buildx build -o . .
$ docker buildx build -o outdir .
$ docker buildx build -o - - > out.tar
$ docker buildx build -o type=docker .
$ docker buildx build -o type=docker,dest=- . > myimage.tar
$ docker buildx build -t tonistiigi/foo -o type=registry
Supported exported types are:
The local
export type writes all result files to a directory on the client. The
new files will be owned by the current user. On multi-platform builds, all results
will be put in subdirectories by their platform.
Attribute key:
dest
- destination directory where files will be written
The tar
export type writes all result files as a single tarball on the client.
On multi-platform builds all results will be put in subdirectories by their platform.
Attribute key:
dest
- destination path where tarball will be written. “-” writes to stdout.
The oci
export type writes the result image or manifest list as an OCI image
layout
tarball on the client.
Attribute key:
dest
- destination path where tarball will be written. “-” writes to stdout.
The docker
export type writes the single-platform result image as a Docker image
specification
tarball on the client. Tarballs created by this exporter are also OCI compatible.
Currently, multi-platform images cannot be exported with the docker
export type.
The most common usecase for multi-platform images is to directly push to a registry
(see registry
).
Attribute keys:
dest
- destination path where tarball will be written. If not specified the tar will be loaded automatically to the current docker instance.context
- name for the docker context where to import the result
The image
exporter writes the build result as an image or a manifest list. When
using docker
driver the image will appear in docker images
. Optionally, image
can be automatically pushed to a registry by specifying attributes.
Attribute keys:
name
- name (references) for the new image.push
- boolean to automatically push the image.
The registry
exporter is a shortcut for type=image,push=true
.
--platform=value[,value]
Set the target platform for the build. All FROM
commands inside the Dockerfile
without their own --platform
flag will pull base images for this platform and
this value will also be the platform of the resulting image. The default value
will be the current platform of the buildkit daemon.
When using docker-container
driver with buildx
, this flag can accept multiple
values as an input separated by a comma. With multiple values the result will be
built for all of the specified platforms and joined together into a single manifest
list.
If the Dockerfile
needs to invoke the RUN
command, the builder needs runtime
support for the specified platform. In a clean setup, you can only execute RUN
commands for your system architecture.
If your kernel supports binfmt_misc
launchers for secondary architectures, buildx will pick them up automatically.
Docker desktop releases come with binfmt_misc
automatically configured for arm64
and arm
architectures. You can see what runtime platforms your current builder
instance supports by running docker buildx inspect --bootstrap
.
Inside a Dockerfile
, you can access the current platform value through
TARGETPLATFORM
build argument. Please refer to the docker build
documentation
for the full description of automatic platform argument variants .
The formatting for the platform specifier is defined in the containerd source code.
$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ docker buildx build --platform=darwin .
--progress=VALUE
Set type of progress output (auto, plain, tty). Use plain to show container output (default "auto").
You can also use the
BUILDKIT_PROGRESS
environment variable to set its value.
The following example uses plain
output during the build:
$ docker buildx build --load --progress=plain .
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 227B 0.0s done
#1 DONE 0.1s
#2 [internal] load .dockerignore
#2 transferring context: 129B 0.0s done
#2 DONE 0.0s
...
Shorthand for --output=type=registry
. Will automatically push the
build result to registry.
--secret=[type=TYPE[,KEY=VALUE]
Exposes secret to the build. The secret can be used by the build using
RUN --mount=type=secret
mount.
If type
is unset it will be detected. Supported types are:
Attribute keys:
id
- ID of the secret. Defaults to basename of thesrc
path.src
,source
- Secret filename.id
used if unset.
# syntax=docker/dockerfile:1.3
FROM python:3
RUN pip install awscli
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
aws s3 cp s3://... ...
$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .
Attribute keys:
id
- ID of the secret. Defaults toenv
name.env
- Secret environment variable.id
used if unset, otherwise will look forsrc
,source
ifid
unset.
# syntax=docker/dockerfile:1.3
FROM node:alpine
RUN --mount=type=bind,target=. \
--mount=type=secret,id=SECRET_TOKEN \
SECRET_TOKEN=$(cat /run/secrets/SECRET_TOKEN) yarn run test
$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .
The format is <number><unit>
. number
must be greater than 0
. Unit is
optional and can be b
(bytes), k
(kilobytes), m
(megabytes), or g
(gigabytes). If you omit the unit, the system uses bytes.
--ssh=default|<id>[=<socket>|<key>[,<key>]]
This can be useful when some commands in your Dockerfile need specific SSH authentication (e.g., cloning a private repository).
--ssh
exposes SSH agent socket or keys to the build and can be used with the
RUN --mount=type=ssh
mount.
Example to access Gitlab using an SSH agent socket:
# syntax=docker/dockerfile:1.3
FROM alpine
RUN apk add --no-cache openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh ssh -q -T git@gitlab.com 2>&1 | tee /hello
# "Welcome to GitLab, @GITLAB_USERNAME_ASSOCIATED_WITH_SSHKEY" should be printed here
# with the type of build progress is defined as `plain`.
$ eval $(ssh-agent)
$ ssh-add ~/.ssh/id_rsa
(Input your passphrase here)
$ docker buildx build --ssh default=$SSH_AUTH_SOCK .
--ulimit
is specified with a soft and hard limit as such:
<type>=<soft limit>[:<hard limit>]
, for example:
$ docker buildx build --ulimit nofile=1024:1024 .
Note
If you do not provide a
hard limit
, thesoft limit
is used for both values. If noulimits
are set, they are inherited from the defaultulimits
set on the daemon.