Local and tar exporters

The local and tar exporters output the root filesystem of the build result into a local directory. They’re useful for producing artifacts that aren’t container images.

• local exports files and directories.
• tar exports the same, but bundles the export into a tarball.

Synopsis

Build a container image using the local exporter:

$ docker buildx build --output type=local[,parameters] .

$ docker buildx build --output type=tar[,parameters] .

The following table describes the available parameters:

Further reading

For more information on the local or tar exporters, see the BuildKit README.

OCI and Docker exporters

The oci exporter outputs the build result into an OCI image layout tarball. The docker exporter behaves the same way, except it exports a Docker image layout instead.

The docker driver doesn’t support these exporters. You must use docker-container or some other driver if you want to generate these outputs.

Synopsis

Build a container image using the oci and docker exporters:

$ docker buildx build --output type=oci[,parameters] .

$ docker buildx build --output type=docker[,parameters] .

The following table describes the available parameters:

Annotations

These exporters support adding OCI annotation using annotation.* dot notation parameter. The following example sets the org.opencontainers.image.title annotation for a build:

$ docker buildx build \
    --output "type=<type>,name=<registry>/<image>,annotation.org.opencontainers.image.title=<title>" .

For more information about annotations, see BuildKit documentation.

Further reading

For more information on the oci or docker exporters, see the BuildKit README.

Overview of Docker Build

Docker Build is one of Docker Engine’s most used features. Whenever you are creating an image you are using Docker Build. Build is a key part of your software development life cycle allowing you to package and bundle your code and ship it anywhere.

The Docker Engine uses a client-server architecture and is composed of multiple components and tools. The most common method of executing a build is by issuing a docker build command. The CLI sends the request to Docker Engine which, in turn, executes your build.

There are now two components in Engine that can be used to build an image. Starting with the 18.09 release, Engine is shipped with Moby BuildKit, the new component for executing your builds by default.

The new client Docker Buildx, is a CLI plugin that extends the docker command with the full support of the features provided by BuildKit builder toolkit. docker buildx build command provides the same user experience as docker build with many new features like creating scoped builder instances, building against multiple nodes concurrently, outputs configuration, inline build caching, and specifying target platform. In addition, Buildx also supports new features that aren’t yet available for regular docker build like building manifest lists, distributed caching, and exporting build results to OCI image tarballs.

Docker Build is more than a simple build command, and it’s not only about packaging your code. It’s a whole ecosystem of tools and features that support not only common workflow tasks but also provides support for more complex and advanced scenarios.

Packaging your software

Build and package your application to run it anywhere: locally or in the cloud.

Multi-stage builds

Keep your images small and secure with minimal dependencies.

Multi-platform images

Build, push, pull, and run images seamlessly on different computer architectures.

Build drivers

Configure where and how you run your builds.

Build caching

Avoid unnecessary repetitions of costly operations, such as package installs.

Continuous integration

Learn how to use Docker in your continuous integration pipelines.

Exporters

Export any artifact you like, not just Docker images.

Bake

Orchestrate your builds with Bake.

Dockerfile frontend

Learn about the Dockerfile frontend for BuildKit.

Configure BuildKit

Take a deep dive into the internals of BuildKit to get the most out of your builds.

Install Docker Buildx

Docker Desktop

Docker Buildx is included by default in Docker Desktop.

Docker Engine via package manager

Docker Linux packages also include Docker Buildx when installed using the .deb or .rpm packages.

Install using a Dockerfile

Here is how to install and use Buildx inside a Dockerfile through the docker/buildx-bin image:

# syntax=docker/dockerfile:1
FROM docker
COPY --from=docker/buildx-bin:latest /buildx /usr/libexec/docker/cli-plugins/docker-buildx
RUN docker buildx version

Download manually

Important

This section is for unattended installation of the Buildx component. These instructions are mostly suitable for testing purposes. We do not recommend installing Buildx using manual download in production environments as they will not be updated automatically with security updates.

On Windows, macOS, and Linux workstations we recommend that you install Docker Desktop instead. For Linux servers, we recommend that you follow the instructions specific for your distribution.

You can also download the latest binary from the releases page on GitHub.

Rename the relevant binary and copy it to the destination matching your OS:

Or copy it into one of these folders for installing it system-wide.

On Unix environments:

• /usr/local/lib/docker/cli-plugins OR /usr/local/libexec/docker/cli-plugins
• /usr/lib/docker/cli-plugins OR /usr/libexec/docker/cli-plugins

On Windows:

• C:\ProgramData\Docker\cli-plugins
• C:\Program Files\Docker\cli-plugins

Note

On Unix environments, it may also be necessary to make it executable with chmod +x :

$ chmod +x ~/.docker/cli-plugins/docker-buildx

Set Buildx as the default builder

Running the command docker buildx install sets up the docker build command as an alias to docker buildx . This results in the ability to have docker build use the current Buildx builder.

To remove this alias, run docker buildx uninstall .

Build release notes

This page contains information about the new features, improvements, and bug fixes in Docker Buildx.

0.9.1

2022-08-18

Bug fixes and enhancements

• The inspect command now displays the BuildKit version in use docker/buildx#1279
• Fixed a regression when building Compose files that contain services without a build block docker/buildx#1277

For more details, see the complete release notes in the Buildx GitHub repository.

0.9.0

2022-08-17

New

• Support for new driver remote that you can use to connect to any already running BuildKit instance docker/buildx#1078 docker/buildx#1093 docker/buildx#1094 docker/buildx#1103 docker/buildx#1134 docker/buildx#1204
• You can now load Dockerfile from standard input even when the build context is coming from external Git or HTTP URL docker/buildx#994
• Build commands now support new the build context type oci-layout:// for loading build context from local OCI layout directories. Note that this feature depends on an unreleased BuildKit feature and builder instance from moby/buildkit:master needs to be used until BuildKit v0.11 is released docker/buildx#1173
• You can now use the new --print flag to run helper functions supported by the BuildKit frontend performing the build and print their results. You can use this feature in Dockerfile to show the build arguments and secrets that the current build supports with --print=outline and list all available Dockerfile stages with --print=targets . This feature is experimental for gathering early feedback and requires enabling BUILDX_EXPERIMENTAL=1 environment variable. We plan to update/extend this feature in the future without keeping backward compatibility docker/buildx#1100 docker/buildx#1272
• You can now use the new --invoke flag to launch interactive containers from build results for an interactive debugging cycle. You can reload these containers with code changes or restore them to an initial state from the special monitor mode. This feature is experimental for gathering early feedback and requires enabling BUILDX_EXPERIMENTAL=1 environment variable. We plan to update/extend this feature in the future without enabling backward compatibility docker/buildx#1168 docker/buildx#1257 docker/buildx#1259
• Buildx now understands environment variable BUILDKIT_COLORS and NO_COLOR to customize/disable the colors of interactive build progressbar docker/buildx#1230 docker/buildx#1226
• buildx ls command now shows the current BuildKit version of each builder instance docker/buildx#998
• The bake command now loads .env file automatically when building Compose files for compatibility docker/buildx#1261
• Bake now supports Compose files with cache_to definition docker/buildx#1155
• Bake now supports new builtin function timestamp() to access current time docker/buildx#1214
• Bake now supports Compose build secrets definition docker/buildx#1069
• Additional build context configuration is now supported in Compose files via x-bake docker/buildx#1256
• Inspecting builder now shows current driver options configuration docker/buildx#1003 docker/buildx#1066

Updates

• Updated the Compose Specification to 1.4.0 docker/buildx#1246 docker/buildx#1251

Bug fixes and enhancements

• The buildx ls command output has been updated with better access to errors from different builders docker/buildx#1109
• The buildx create command now performs additional validation of builder parameters to avoid creating a builder instance with invalid configuration docker/buildx#1206
• The buildx imagetools create command can now create new multi-platform images even if the source subimages are located on different repositories or registries docker/buildx#1137
• You can now set the default builder config that is used when creating builder instances without passing custom --config value docker/buildx#1111
• Docker driver can now detect if dockerd instance supports initially disabled Buildkit features like multi-platform images docker/buildx#1260 docker/buildx#1262
• Compose files using targets with . in the name are now converted to use _ so the selector keys can still be used in such targets docker/buildx#1011
• Included an additional validation for checking valid driver configurations docker/buildx#1188 docker/buildx#1273
• The remove command now displays the removed builder and forbids removing context builders docker/buildx#1128
• Enable Azure authentication when using Kubernetes driver docker/buildx#974
• Add tolerations handling for kubernetes driver docker/buildx#1045 docker/buildx#1053
• Replace deprecated seccomp annotations with securityContext in kubernetes driver docker/buildx#1052
• Fix panic on handling manifests with nil platform docker/buildx#1144
• Fix using duration filter with prune command docker/buildx#1252
• Fix merging multiple JSON files on Bake definition docker/buildx#1025
• Fix issues with implicit builder created from Docker context had invalid configuration or dropped connection docker/buildx#1129
• Fix conditions for showing no-output warning when using named contexts docker/buildx#968
• Fix duplicating builders when builder instance and docker context have the same name docker/buildx#1131
• Fix printing unnecessary SSH warning logs docker/buildx#1085
• Fix possible panic when using an empty variable block with Bake JSON definition docker/buildx#1080
• Fix image tools commands not handling --builder flag correctly docker/buildx#1067
• Fix using custom image together with rootless option docker/buildx#1063

For more details, see the complete release notes in the Buildx GitHub repository.

0.8.2

2022-04-04

Updates

• Update Compose spec used by buildx bake to v1.2.1 to fix parsing ports definition docker/buildx#1033

Bug fixes and enhancements

• Fix possible crash on handling progress streams from BuildKit v0.10 docker/buildx#1042
• Fix parsing groups in buildx bake when already loaded by a parent group docker/buildx#1021

For more details, see the complete release notes in the Buildx GitHub repository.

0.8.1

2022-03-21

Bug fixes and enhancements

• Fix possible panic on handling build context scanning errors docker/buildx#1005
• Allow . on Compose target names in buildx bake for backward compatibility docker/buildx#1018

For more details, see the complete release notes in the Buildx GitHub repository.

0.8.0

2022-03-09

New

• Build command now accepts --build-context flag to define additional named build contexts for your builds docker/buildx#904
• Bake definitions now support defining dependencies between targets and using the result of one target in another build docker/buildx#928 docker/buildx#965 docker/buildx#963 docker/buildx#962 docker/buildx#981
• imagetools inspect now accepts --format flag allowing access to config and buildinfo for specific images docker/buildx#854 docker/buildx#972
• New flag --no-cache-filter allows configuring build, so it ignores cache only for specified Dockerfile stages docker/buildx#860
• Builds can now show a summary of warnings sets by the building frontend docker/buildx#892
• The new build argument BUILDKIT_INLINE_BUILDINFO_ATTRS allows opting-in to embed building attributes to resulting image docker/buildx#908
• The new flag --keep-buildkitd allows keeping BuildKit daemon running when removing a builder
  • docker/buildx#852

Bug fixes and enhancements

• --metadata-file output now supports embedded structure types docker/buildx#946
• buildx rm now accepts new flag --all-inactive for removing all builders that are not currently running docker/buildx#885
• Proxy config is now read from Docker configuration file and sent with build requests for backward compatibility docker/buildx#959
• Support host networking in Compose docker/buildx#905 docker/buildx#880
• Bake files can now be read from stdin with -f - docker/buildx#864
• --iidfile now always writes the image config digest independently of the driver being used (use --metadata-file for digest) docker/buildx#980
• Target names in Bake are now restricted to not use special characters docker/buildx#929
• Image manifest digest can be read from metadata when pushed with docker driver docker/buildx#989
• Fix environment file handling in Compose files docker/buildx#905
• Show last access time in du command docker/buildx#867
• Fix possible double output logs when multiple Bake targets run same build steps docker/buildx#977
• Fix possible errors on multi-node builder building multiple targets with mixed platform docker/buildx#985
• Fix some nested inheritance cases in Bake docker/buildx#914
• Fix printing default group on Bake files docker/buildx#884
• Fix UsernsMode when using rootless container docker/buildx#887

For more details, see the complete release notes in the Buildx GitHub repository.

0.7.1

2021-08-25

Fixes

• Fix issue with matching exclude rules in .dockerignore docker/buildx#858
• Fix bake --print JSON output for current group docker/buildx#857

For more details, see the complete release notes in the Buildx GitHub repository.

0.7.0

2021-11-10

New features

• TLS certificates from BuildKit configuration are now transferred to build container with docker-container and kubernetes drivers docker/buildx#787
• Builds support --ulimit flag for feature parity docker/buildx#800
• Builds support --shm-size flag for feature parity docker/buildx#790
• Builds support --quiet for feature parity docker/buildx#740
• Builds support --cgroup-parent flag for feature parity docker/buildx#814
• Bake supports builtin variable BAKE_LOCAL_PLATFORM docker/buildx#748
• Bake supports x-bake extension field in Compose files docker/buildx#721
• kubernetes driver now supports colon-separated KUBECONFIG docker/buildx#761
• kubernetes driver now supports setting Buildkit config file with --config docker/buildx#682
• kubernetes driver now supports installing QEMU emulators with driver-opt docker/buildx#682

Enhancements

• Allow using custom registry configuration for multi-node pushes from the client docker/buildx#825
• Allow using custom registry configuration for buildx imagetools command docker/buildx#825
• Allow booting builder after creating with buildx create --bootstrap docker/buildx#692
• Allow registry:insecure output option for multi-node pushes docker/buildx#825
• BuildKit config and TLS files are now kept in Buildx state directory and reused if BuildKit instance needs to be recreated docker/buildx#824
• Ensure different projects use separate destination directories for incremental context transfer for better performance docker/buildx#817
• Build containers are now placed on separate cgroup by default docker/buildx#782
• Bake now prints the default group with --print docker/buildx#720
• docker driver now dials build session over HTTP for better performance docker/buildx#804

Fixes

• Fix using --iidfile together with a multi-node push docker/buildx#826
• Using --push in Bake does not clear other image export options in the file docker/buildx#773
• Fix Git URL detection for buildx bake when https protocol was used docker/buildx#822
• Fix pushing image with multiple names on multi-node builds docker/buildx#815
• Avoid showing --builder flags for commands that don’t use it docker/buildx#818
• Unsupported build flags now show a warning docker/buildx#810
• Fix reporting error details in some OpenTelemetry traces docker/buildx#812

For more details, see the complete release notes in the Buildx GitHub repository.

0.6.3

2021-08-30

Fixes

• Fix BuildKit state volume location for Windows clients docker/buildx#751

For more details, see the complete release notes in the Buildx GitHub repository.

0.6.2

2021-08-21

For more details, see the complete release notes in the Buildx GitHub repository.

Fixes

• Fix connection error showing up in some SSH configurations docker/buildx#741

0.6.1

2021-07-30

Enhancements

• Set ConfigFile to parse compose files with Bake docker/buildx#704

Fixes

• Duplicate progress env var docker/buildx#693
• Should ignore nil client docker/buildx#686

For more details, see the complete release notes in the Buildx GitHub repository.

0.6.0

2021-07-16

New features

• Support for OpenTelemetry traces and forwarding Buildx client traces to BuildKit docker/buildx#635
• Experimental GitHub Actions remote cache backend with --cache-to type=gha and --cache-from type=gha docker/buildx#535
• New --metadata-file flag has been added to build and Bake command that allows saving build result metadata in JSON format docker/buildx#605
• This is the first release supporting Windows ARM64 docker/buildx#654
• This is the first release supporting Linux Risc-V docker/buildx#652
• Bake now supports building from remote definition with local files or another remote source as context docker/buildx#671
• Bake now allows variables to reference each other and using user functions in variables and vice-versa docker/buildx#575 docker/buildx#539 docker/buildx#532
• Bake allows defining attributes in the global scope docker/buildx#541
• Bake allows variables across multiple files docker/buildx#538
• New quiet mode has been added to progress printer docker/buildx#558
• kubernetes driver now supports defining resources/limits docker/buildx#618
• Buildx binaries can now be accessed through buildx-bin Docker image docker/buildx#656

Enhancements

• docker-container driver now keeps BuildKit state in volume. Enabling updates with keeping state docker/buildx#672
• Compose parser is now based on new compose-go parser fixing support for some newer syntax docker/buildx#669
• SSH socket is now automatically forwarded when building an ssh-based git URL docker/buildx#581
• Bake HCL parser has been rewritten docker/buildx#645
• Extend HCL support with more functions docker/buildx#491 docker/buildx#503
• Allow secrets from environment variables docker/buildx#488
• Builds with an unsupported multi-platform and load configuration now fail fast docker/buildx#582
• Store Kubernetes config file to make buildx builder switchable docker/buildx#497
• Kubernetes now lists all pods as nodes on inspection docker/buildx#477
• Default Rootless image has been set to moby/buildkit:buildx-stable-1-rootless docker/buildx#480

Fixes

• imagetools create command now correctly merges JSON descriptor with old one docker/buildx#592
• Fix building with --network=none not requiring extra security entitlements docker/buildx#531

For more details, see the complete release notes in the Buildx GitHub repository.

0.5.1

2020-12-15

Fixes

• Fix regression on setting --platform on buildx create outside kubernetes driver docker/buildx#475

For more details, see the complete release notes in the Buildx GitHub repository.

0.5.0

2020-12-15

New features

• The docker driver now supports the --push flag docker/buildx#442
• Bake supports inline Dockerfiles docker/buildx#398
• Bake supports building from remote URLs and Git repositories docker/buildx#398
• BUILDX_CONFIG env var allow users to have separate buildx state from Docker config docker/buildx#385
• BUILDKIT_MULTI_PLATFORM build arg allows to force building multi-platform return objects even if only one --platform specified docker/buildx#467

Enhancements

• Allow --append to be used with kubernetes driver docker/buildx#370
• Build errors show error location in source files and system stacktraces with --debug docker/buildx#389
• Bake formats HCL errors with source definition docker/buildx#391
• Bake allows empty string values in arrays that will be discarded docker/buildx#428
• You can now use the Kubernetes cluster config with the kubernetes driver docker/buildx#368 docker/buildx#460
• Creates a temporary token for pulling images instead of sharing credentials when possible docker/buildx#469
• Ensure credentials are passed when pulling BuildKit container image docker/buildx#441 docker/buildx#433
• Disable user namespace remapping in docker-container driver docker/buildx#462
• Allow --builder flag to switch to default instance docker/buildx#425
• Avoid warn on empty BUILDX_NO_DEFAULT_LOAD config value docker/buildx#390
• Replace error generated by quiet option by a warning docker/buildx#403
• CI has been switched to GitHub Actions docker/buildx#451 docker/buildx#463 docker/buildx#466 docker/buildx#468 docker/buildx#471

Fixes

• Handle lowercase Dockerfile name as a fallback for backward compatibility docker/buildx#444

For more details, see the complete release notes in the Buildx GitHub repository.

0.4.2

2020-08-22

New features

• Support cacheonly exporter docker/buildx#337

Enhancements

• Update go-cty to pull in more stdlib functions docker/buildx#277
• Improve error checking on load docker/buildx#281

Fixes

• Fix parsing json config with HCL docker/buildx#280
• Ensure --builder is wired from root options docker/buildx#321
• Remove warning for multi-platform iidfile docker/buildx#351

For more details, see the complete release notes in the Buildx GitHub repository.

0.4.1

2020-05-01

Fixes

• Fix regression on flag parsing docker/buildx#268
• Fix using pull and no-cache keys in HCL targets docker/buildx#268

For more details, see the complete release notes in the Buildx GitHub repository.

0.4.0

2020-04-30

New features

• Add kubernetes driver docker/buildx#167
• New global --builder flag to override builder instance for a single command docker/buildx#246
• New prune and du commands for managing local builder cache docker/buildx#249
• You can now set the new pull and no-cache options for HCL targets docker/buildx#165

Enhancements

• Upgrade Bake to HCL2 with support for variables and functions docker/buildx#192
• Bake now supports --load and --push docker/buildx#164
• Bake now supports wildcard overrides for multiple targets docker/buildx#164
• Container driver allows setting environment variables via driver-opt docker/buildx#170

For more details, see the complete release notes in the Buildx GitHub repository.

0.3.1

2019-09-27

Enhancements

• Handle copying unix sockets instead of erroring docker/buildx#155 moby/buildkit#1144

Fixes

• Running Bake with multiple Compose files now merges targets correctly docker/buildx#134
• Fix bug when building a Dockerfile from stdin ( build -f - ) docker/buildx#153

For more details, see the complete release notes in the Buildx GitHub repository.

0.3.0

2019-08-02

New features

• Custom buildkitd daemon flags docker/buildx#102
• Driver-specific options on create docker/buildx#122

Enhancements

• Environment variables are used in Compose files docker/buildx#117
• Bake now honors --no-cache and --pull docker/buildx#118
• Custom BuildKit config file docker/buildx#121
• Entitlements support with build --allow docker/buildx#104

Fixes

• Fix bug where --build-arg foo would not read foo from environment docker/buildx#116

For more details, see the complete release notes in the Buildx GitHub repository.

0.2.2

2019-05-30

Enhancements

• Change Compose file handling to require valid service specifications docker/buildx#87

For more details, see the complete release notes in the Buildx GitHub repository.

0.2.1

2019-05-25

New features

• Add BUILDKIT_PROGRESS env var docker/buildx#69
• Add local platform docker/buildx#70

Enhancements

• Keep arm variant if one is defined in the config docker/buildx#68
• Make dockerfile relative to context docker/buildx#83

Fixes

• Fix parsing target from compose files docker/buildx#53

For more details, see the complete release notes in the Buildx GitHub repository.

0.2.0

2019-04-25

New features

• First release

For more details, see the complete release notes in the Buildx GitHub repository.