docker buildx build

$ docker buildx build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 .

$ docker buildx build --add-host host.docker.internal=host-gateway .

$ docker buildx build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] .

--annotation="key=value"
--annotation="[type:]key=value"

$ docker buildx build -t TAG --annotation "foo=bar" --push .

$ docker buildx build -t TAG --annotation "index:foo=bar" --push .

$ docker buildx build -t TAG --annotation "index,manifest,manifest-descriptor:foo=bar" --push .

$ docker buildx build -t TAG --annotation "manifest[linux/amd64]:foo=bar" --push .

--attest=type=sbom,...
--attest=type=provenance,...

--allow=ENTITLEMENT

$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .

$ docker buildx build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 .

$ export HTTP_PROXY=http://10.20.30.2:1234
$ docker buildx build --build-arg HTTP_PROXY .

$ docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 .

--build-context=name=VALUE

$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .

$ docker buildx build --build-context project=path/to/project/source .
# docker buildx build --build-context project=https://github.com/myuser/project.git .

# syntax=docker/dockerfile:1
FROM alpine
COPY --from=project myfile /

$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout:<tag>
$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout@sha256:<digest>

# syntax=docker/dockerfile:1
FROM alpine
RUN apk add git
COPY --from=foo myfile /

FROM foo

--cache-from=[NAME|type=TYPE[,KEY=VALUE]]

$ 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 .
$ docker buildx build --cache-from=type=s3,region=eu-west-1,bucket=mybucket .

--call=[build|check|outline|targets]

$ docker buildx build -q --call=subrequests.describe .

NAME                 VERSION DESCRIPTION
outline              1.0.0   List all parameters current build target supports
targets              1.0.0   List all targets current build supports
subrequests.describe 1.0.0   List available subrequest types

# syntax=docker/dockerfile:1

# GO_VERSION sets the Go version for the build
ARG GO_VERSION=1.22

# base-builder is the base stage for building the project
FROM golang:${GO_VERSION} AS base-builder

$ docker buildx build -q --call=outline .

TARGET:      base-builder
DESCRIPTION: is the base stage for building the project

BUILD ARG    VALUE   DESCRIPTION
GO_VERSION   1.22    sets the Go version for the build

$ docker buildx build -q --check https://github.com/docker/docs.git

WARNING: InvalidBaseImagePlatform
Base image wjdp/htmltest:v0.17.0 was pulled with platform "linux/amd64", expected "linux/arm64" for current build
Dockerfile:43
--------------------
  41 |         "#content/desktop/previous-versions/*.md"
  42 |
  43 | >>> FROM wjdp/htmltest:v${HTMLTEST_VERSION} AS test
  44 |     WORKDIR /test
  45 |     COPY --from=build /out ./public
--------------------

$ docker buildx build -q --call=outline https://github.com/docker/docs.git

TARGET:      release
DESCRIPTION: is an empty scratch image with only compiled assets

BUILD ARG          VALUE     DESCRIPTION
GO_VERSION         1.22      sets the Go version for the base stage
HUGO_VERSION       0.127.0
HUGO_ENV                     sets the hugo.Environment (production, development, preview)
DOCS_URL                     sets the base URL for the site
PAGEFIND_VERSION   1.1.0

$ docker buildx build \
  --build-arg GO_VERSION=1.22 \
  --build-arg HUGO_VERSION=0.127.0 \
  --build-arg HUGO_ENV=production \
  --build-arg DOCS_URL=https://example.com \
  --build-arg PAGEFIND_VERSION=1.1.0 \
  --target release https://github.com/docker/docs.git

$ docker buildx build -q --call=targets https://github.com/docker/docs.git

TARGET            DESCRIPTION
base              is the base stage with build dependencies
node              installs Node.js dependencies
hugo              downloads and extracts the Hugo binary
build-base        is the base stage for building the site
dev               is for local development with Docker Compose
build             creates production builds with Hugo
lint              lints markdown files
test              validates HTML output and checks for broken links
update-modules    downloads and vendors Hugo modules
vendor            is an empty stage with only vendored Hugo modules
build-upstream    builds an upstream project with a replacement module
validate-upstream validates HTML output for upstream builds
unused-media      checks for unused graphics and other media
pagefind          installs the Pagefind runtime
index             generates a Pagefind index
test-go-redirects checks that the /go/ redirects are valid
release (default) is an empty scratch image with only compiled assets

--cache-to=[NAME|type=TYPE[,KEY=VALUE]]

$ 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 .
$ docker buildx build --cache-to=type=s3,region=eu-west-1,bucket=mybucket .

$ docker buildx build -f <filepath> .

$ cat Dockerfile | docker buildx build -f - .

$ docker buildx build --load --metadata-file metadata.json .
$ cat metadata.json

{
  "buildx.build.provenance": {},
  "buildx.build.ref": "mybuilder/mybuilder0/0fjb6ubs52xx3vygf6fgdl611",
  "buildx.build.warnings": {},
  "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"
}

$ docker buildx build --no-cache-filter stage1,stage2,stage3 .

# syntax=docker/dockerfile:1

FROM oven/bun:1 AS base
WORKDIR /app

FROM base AS install
WORKDIR /temp/dev
RUN --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=bun.lockb,target=bun.lockb \
    bun install --frozen-lockfile

FROM base AS test
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
RUN bun test

FROM base AS release
ENV NODE_ENV=production
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
ENTRYPOINT ["bun", "run", "index.js"]

$ docker buildx build --no-cache-filter install .

$ docker buildx build --no-cache-filter install,release .

-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]

$ 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

--platform=value[,value]

$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ docker buildx build --platform=darwin .

--progress=VALUE

$ 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
...

--secret=[type=TYPE[,KEY=VALUE]

$ docker buildx build --secret [type=file,]id=<ID>[,src=<FILEPATH>] .

$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .

# syntax=docker/dockerfile:1
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 [type=env,]id=<ID>[,env=<VARIABLE>] .

$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .

# syntax=docker/dockerfile:1
FROM node:alpine
RUN --mount=type=bind,target=. \
  --mount=type=secret,id=SECRET_TOKEN,env=SECRET_TOKEN \
  yarn run test

$ API_KEY=token docker buildx build --secret id=SECRET_TOKEN,env=API_KEY .

$ API_KEY=token docker buildx build --secret type=env,id=SECRET_TOKEN,src=API_KEY .

--ssh=default|<id>[=<socket>|<key>[,<key>]]

# syntax=docker/dockerfile:1
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 .

$ docker buildx build -t docker/apache:2.0 .

$ docker buildx build -t docker/fedora-jboss:latest -t docker/fedora-jboss:v2.1 .

FROM debian AS build-env
# ...

FROM alpine AS production-env
# ...

$ docker buildx build -t mybuildimage --target build-env .

$ docker buildx build --ulimit nofile=1024:1024 .