Docker Config Reference (docker buildx)

Docker Buildx is distinct from the standard docker build command. While docker build utilizes the classic Docker builder for creating images from a Dockerfile, focusing on basic layer-by-layer construction with optional caching, docker buildx is an advanced CLI plugin that leverages the BuildKit backend. This enables enhanced capabilities such as multi-platform image builds (e.g., for ARM and AMD64 architectures simultaneously), improved caching mechanisms (including inline, registry, and local caches), parallel execution of build steps, and support for distributed builds across multiple nodes. Buildx also provides better performance, security features (e.g., secret management), and extensibility through custom builders. It is invoked via subcommands like docker buildx build, which mirrors docker build syntax but extends it with additional flags. Buildx must be enabled (often via docker buildx install or by setting DOCKER_CLI_EXPERIMENTAL=enabled), and it is particularly valuable in cross-platform or CI/CD environments.

Example 1

docker buildx build -t myapp:latest .

This command builds an image tagged "myapp:latest" using BuildKit, benefiting from its optimized caching and parallel processing for faster builds compared to standard docker build.

Example 2

docker buildx build -t crossplatform:1.0 --platform linux/amd64,linux/arm64 .

This constructs a multi-platform image "crossplatform:1.0" for both AMD64 and ARM64 architectures, a feature unique to Buildx for creating versatile images deployable on diverse hardware.

Example 3

docker buildx build -t cachedapp:dev --cache-to type=inline .

This builds "cachedapp:dev" and exports cache inline within the image layers, allowing subsequent builds to reuse cache more efficiently than traditional methods.

Example 4

docker buildx build -t secretbuild:secure --secret id=mysecret,src=.env .

This incorporates a secret file ".env" during the build of "secretbuild:secure", ensuring sensitive data is not baked into image layers, enhancing security over basic builds.

Example 5

docker buildx build -t sshgit:1.2 --ssh default .

This enables SSH agent forwarding for "sshgit:1.2", permitting secure git operations during builds, such as cloning private repositories, without exposing keys.

Example 6

docker buildx build -t exported:tar --output type=tar,dest=build.tar .

This exports the build result as a tar file "build.tar" for "exported:tar", useful for artifact distribution without creating a traditional Docker image.

Example 7

docker buildx build -t registrycached:stable --cache-to type=registry,ref=example.com/cache:buildcache .

This builds "registrycached:stable" and pushes cache to a registry for reuse in distributed CI/CD pipelines, leveraging remote caching.

Example 8

docker buildx build -t localcached:dev --cache-from type=local,src=/path/to/cache .

This utilizes a local cache directory for "localcached:dev", accelerating builds by importing prior cache, ideal for local development workflows.

Example 9

docker buildx build -t attested:1.0 --attest type=provenance,mode=max .

This adds provenance attestation to "attested:1.0", providing verifiable build metadata for supply chain security, a BuildKit-exclusive feature.

Example 10

docker buildx build -t sbomgen:secure --attest type=sbom .

This generates and attaches a Software Bill of Materials (SBOM) to "sbomgen:secure", aiding vulnerability scanning and compliance.

Example 11

docker buildx build -t parallel:optimized --load .

This builds "parallel:optimized" with parallel step execution enabled by BuildKit, and loads the image into the local Docker daemon.

Example 12

docker buildx build -t pushed:remote --push .

This builds and directly pushes "pushed:remote" to a registry, streamlining deployment without local storage.

Example 13

docker buildx build -t buildercreated:dev --builder mybuilder .

This uses a custom builder instance "mybuilder" for "buildercreated:dev", allowing specialized build environments.

Example 14

docker buildx create --name mybuilder --driver docker-container

This creates a new builder instance "mybuilder" using the docker-container driver, for isolated or remote builds.

Example 15

docker buildx use mybuilder

This switches the default builder to "mybuilder", directing subsequent builds to use its configuration.

Example 16

docker buildx inspect mybuilder

This inspects the "mybuilder" instance, displaying nodes, drivers, and capabilities for troubleshooting.

Example 17

docker buildx rm mybuilder

This removes the builder instance "mybuilder", cleaning up unused build environments.

Example 18

docker buildx ls

This lists all available builders, including their status and platforms, for management overview.

Example 19

docker buildx bake -f docker-compose.yml

This builds images defined in "docker-compose.yml" using Buildx, supporting Compose file builds with advanced features.

Example 20

docker buildx du

This displays disk usage for Buildx caches and builders, helping manage storage consumption.

Example 21

docker buildx prune --all

This prunes all unused Buildx data, including caches and builders, to reclaim disk space.

Example 22

docker buildx version

This outputs the Buildx version and BuildKit details, verifying installation and compatibility.

Example 23

docker buildx imagetools inspect myapp:latest

This inspects the multi-platform image "myapp:latest", showing manifests and configurations.

Example 24

docker buildx imagetools create -t combined:latest myapp:amd64 myapp:arm64

This creates a multi-platform index "combined:latest" from separate architecture images.

Example 25

docker buildx debug shell

This opens an interactive debug shell within BuildKit, for advanced troubleshooting.

Example 26

docker buildx build -t annotated:dev --annotation "org.opencontainers.image.description=My App" .

This adds annotations to "annotated:dev" for metadata like descriptions.

Example 27

docker buildx build -t exportedoci:1.0 --output type=oci,dest=oci.tar .

This exports to OCI format "oci.tar" for "exportedoci:1.0", compatible with other runtimes.

Example 28

docker buildx build -t frontend:spa --frontend dockerfile.v0 .

This specifies the Dockerfile frontend for "frontend:spa", using experimental syntax.

Example 29

docker buildx build -t baked:group --set *.platform=linux/amd64 .

This overrides platforms in a bake file for "baked:group".

Example 30

docker buildx stop mybuilder

This stops the "mybuilder" instance, halting active builds for maintenance.