Working with Docker Buildx

1. Installing Buildx

Buildx is included with Docker Desktop and can be installed as a standalone plugin for Docker Engine.

Installation Method	Description	Command
Docker Desktop	Buildx is included by default in Docker Desktop.	`docker buildx version`
Standalone Plugin	Install Buildx as a plugin for Docker Engine.	`docker plugin install --alias buildx docker/buildx:latest`

Example: Verify Buildx Installation

docker buildx version

Note: Ensure Docker Engine is installed before installing Buildx as a plugin.

2. Creating Builder Instance

Option	Description	Default
--name	Name of the builder instance	default
--driver	Driver to use for the builder (e.g., docker, docker-container)	docker
--use	Set the current builder instance as default	false

Example: Creating a new builder instance

docker buildx create --name mybuilder --use

Note: The --use flag sets the newly created builder as the default for subsequent builds.

3. Listing Builders

Command	Description	Notes
docker buildx ls	List all builders	Default builder is shown with `*`
docker buildx ls --format json	List builders in JSON format	Useful for scripting and automation
docker buildx ls --quiet	Only show builder names	Minimal output for quick reference

Example: Listing all Docker Buildx builders

$ docker buildx ls
NAME/NODE        DRIVER/ENDPOINT             STATUS  PLATFORMS
default *        docker
  default          npipe:////./pipe/docker_engine running windows/amd64, linux/amd64
mybuilder        docker
  mybuilder        npipe:////./pipe/docker_engine running windows/amd64, linux/amd64

4. Using Builder

Option	Values	Description
--builder	`default`	Name of the builder instance to use
--load	`false`	Load the built image into the local Docker image cache
--output	`type=docker`	Specify where to send the results (e.g., local, registry)
--platform	`linux/amd64`	Target platform for the build (e.g., linux/arm64)

Example: Building for Multiple Platforms

docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest .

Example: Load Image to Local Cache

docker buildx build --load -t myapp:latest .

Note: The --load flag is required to make the image available in the local Docker image cache.

Warning: Ensure that the builder instance is initialized before running build commands.

5. Inspecting Builder

Property	Description	Example
docker buildx inspect	Inspect the current builder instance and its configuration	`docker buildx inspect`
docker buildx inspect <builder-name>	Inspect a specific builder instance by name	`docker buildx inspect mybuilder`
--bootstrap	Bootstrap the builder instance if it does not exist	`docker buildx inspect --bootstrap`
--driver	Specify the driver to use for the builder	`docker buildx inspect --driver docker-container`

Example: Inspecting default builder

docker buildx inspect

Example: Inspecting a named builder

docker buildx inspect mybuilder

Note: The output includes details about the builder's driver, node configuration, and supported platforms.

6. Building Multi-Platform Images

Building multi-platform images allows you to create a single image that can run on different architectures (e.g., linux/amd64, linux/arm64) using Docker Buildx.

Option	Description	Example
--platform	Specifies the target platform for the image build.	`--platform linux/amd64,linux/arm64`
--output	Defines where to output the built image (e.g., local, registry).	`--output type=image,name=myapp:latest`
--build-arg	Passes build-time arguments to the Dockerfile.	`--build-arg VERSION=1.0`

Example: Building multi-platform image

docker buildx build --platform linux/amd64,linux/arm64 \
  --output type=image,name=myapp:latest \
  --build-arg VERSION=1.0 \
  -t myapp:latest .

Note: Ensure that your base image and dependencies support the target platforms.

Warning: Building multi-platform images can be slower due to cross-compilation.

7. Pushing Multi-Platform Images

Option	Values	Description
--platform	`linux/amd64,linux/arm64`	Target platforms for the image
--push	`true`	Push the image to a registry after building
--tag	`myapp:latest`	Name and tag for the image

Example: Pushing Multi-Platform Image

docker buildx build --platform linux/amd64,linux/arm64 --push -t myapp:latest .

Note: Ensure that the target registry supports multi-platform images.

8. Building with Cache Export

Option	Description	Usage
--cache-to	Specifies the cache destination for exporting build cache	`--cache-to=type=registry,ref=myapp/cache`
--cache-from	Specifies the cache source for importing build cache	`--cache-from=type=registry,ref=myapp/cache`

Example: Exporting and Importing Cache

docker buildx build --cache-to=type=registry,ref=myapp/cache --cache-from=type=registry,ref=myapp/cache -t myapp .

Note: Cache export/import is supported with type=registry or type=inline.

9. Building with Cache Import

Cache import allows you to reuse previously built layers to speed up subsequent builds.

Option	Description	Example
--cache-from	Specifies the cache source to import from	`--cache-from type=registry,ref=myapp:cache`
--cache-to	Specifies where to export the cache after build	`--cache-to type=registry,ref=myapp:cache`

Example: Importing cache from a registry

docker buildx build --cache-from type=registry,ref=myapp:cache -t myapp .

Example: Exporting cache to a registry

docker buildx build --cache-to type=registry,ref=myapp:cache -t myapp .

Note: Cache import/export works best with type=registry for shared builds.

10. Using Remote Build Contexts

Context Type	Description	Usage	Notes
docker buildx build --build-context	Specifies a remote context for the build	`docker buildx build --build-context <name>=<value>`	Supports local, Git, and HTTP contexts
local	Local directory as build context	`--build-context local=<path>`	Default behavior if not specified
git	Git repository as build context	`--build-context git=<repo>#<branch>`	Can specify branch, tag, or commit
http	Remote archive as build context	`--build-context http=<url>`	Supports tar.gz and zip archives

Example: Building from a Git Repository

docker buildx build --build-context git=https://github.com/example/repo.git#main -t myapp .

Note: Remote contexts are useful for building from sources outside the local filesystem, such as shared repositories or external archives.

11. Building with OCI Exporter

The OCI (Open Container Initiative) exporter allows you to export Docker builds as OCI-compliant images, which are compatible with various container runtimes and registries.

Option	Values	Description
--output type=oci	`type=oci`	Exports the build result as an OCI image format
--output name=<image-name>	`name=myapp:latest`	Name of the exported image
--output path=<path>	`path=/tmp/oci-image.tar`	Path to save the OCI image tarball

Example: Exporting an OCI Image

docker buildx build --output type=oci,name=myapp:latest,path=/tmp/myapp.tar -t myapp:latest .

Note: The OCI exporter supports exporting to local files or pushing directly to registries that support the OCI format.

12. Removing Builder

Command	Description	Notes
docker buildx rm <builder-name>	Remove a builder instance	Deletes the builder and its associated resources
docker buildx rm --force <builder-name>	Force remove a builder instance	Bypasses confirmation and removes builder immediately

Example: Remove a Builder

docker buildx rm mybuilder

Note: Ensure no active builds are using the builder before removal.