Image and registry exporters

The image exporter outputs the build result into a container image format. The registry exporter is identical, but it automatically pushes the result by setting push=true .

Synopsis

Build a container image using the image and registry exporters:

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

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

The following table describes the available parameters that you can pass to --output for type=image :

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 image or registry exporters, see the BuildKit README.

Exporters overview

Exporters save your build results to a specified output type. You specify the exporter to use with the --output CLI option. Buildx supports the following exporters:

• image : exports the build result to a container image.
• registry : exports the build result into a container image, and pushes it to the specified registry.
• local : exports the build root filesystem into a local directory.
• tar : packs the build root filesystem into a local tarball.
• oci : exports the build result to the local filesystem in the OCI image layout format.
• docker : exports the build result to the local filesystem in the Docker image format.
• cacheonly : doesn’t export a build output, but runs the build and creates a cache.

Using exporters

To specify an exporter, use the following command syntax:

$ docker buildx build --tag <registry>/<image> \
  --output type=<TYPE> .

Most common use cases doesn’t require you don’t need to specify which exporter to use explicitly. You only need to specify the exporter if you intend to customize the output somehow, or if you want to save it to disk. The --load and --push options allow Buildx to infer the exporter settings to use.

For example, if you use the --push option in combination with --tag , Buildx automatically uses the image exporter, and configures the exporter to push the results to the specified registry.

To get the full flexibility out of the various exporters BuildKit has to offer, you use the --output flag that lets you configure exporter options.

Use cases

Each exporter type is designed for different use cases. The following sections describe some common scenarios, and how you can use exporters to generate the output that you need.

Load to image store

Buildx is often used to build container images that can be loaded to an image store. That’s where the docker exporter comes in. The following example shows how to build an image using the docker exporter, and have that image loaded to the local image store, using the --output option:

$ docker buildx build \
  --output type=docker,name=<registry>/<image> .

Buildx CLI will automatically use the docker exporter and load it to the image store if you supply the --tag and --load options:

$ docker buildx build --tag <registry>/<image> --load .

Building images using the docker driver are automatically loaded to the local image store.

Images loaded to the image store are available to for docker run immediately after the build finishes, and you’ll see them in the list of images when you run the docker images command.

Push to registry

To push a built image to a container registry, you can use the registry or image exporters.

When you pass the --push option to the Buildx CLI, you instruct BuildKit to push the built image to the specified registry:

$ docker buildx build --tag <registry>/<image> --push .

Under the hood, this uses the image exporter, and sets the push parameter. It’s the same as using the following long-form command using the --output option:

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true .

You can also use the registry exporter, which does the same thing:

$ docker buildx build \
  --output type=registry,name=<registry>/<image> .

Export image layout to file

You can use either the oci or docker exporters to save the build results to image layout on your local filesystem. Both of these exporters generate a tar archive file containing the corresponding image layout. The dest parameter defines the target output path for the tarball.

$ docker buildx build --output type=oci,dest=./image.tar .
[+] Building 0.8s (7/7) FINISHED
 ...
 => exporting to oci image format                                                                     0.0s
 => exporting layers                                                                                  0.0s
 => exporting manifest sha256:c1ef01a0a0ef94a7064d5cbce408075730410060e253ff8525d1e5f7e27bc900        0.0s
 => exporting config sha256:eadab326c1866dd247efb52cb715ba742bd0f05b6a205439f107cf91b3abc853          0.0s
 => sending tarball                                                                                   0.0s
$ mkdir -p out && tar -C out -xf ./image.tar
$ tree out
out
├── blobs
│   └── sha256
│       ├── 9b18e9b68314027565b90ff6189d65942c0f7986da80df008b8431276885218e
│       ├── c78795f3c329dbbbfb14d0d32288dea25c3cd12f31bd0213be694332a70c7f13
│       ├── d1cf38078fa218d15715e2afcf71588ee482352d697532cf316626164699a0e2
│       ├── e84fa1df52d2abdfac52165755d5d1c7621d74eda8e12881f6b0d38a36e01775
│       └── fe9e23793a27fe30374308988283d40047628c73f91f577432a0d05ab0160de7
├── index.json
├── manifest.json
└── oci-layout

Export filesystem

If you don’t want to build an image from your build results, but instead export the filesystem that was built, you can use the local and tar exporters.

The local exporter unpacks the filesystem into a directory structure in the specified location. The tar exporter creates a tarball archive file.

$ docker buildx build --output type=tar,dest=<path/to/output> .

The local exporter is useful in multi-stage builds since it allows you to export only a minimal number of build artifacts. For example, self-contained binaries.

Cache-only export

The cacheonly exporter can be used if you just want to run a build, without exporting any output. This can be useful if, for example, you want to run a test build. Or, if you want to run the build first, and create exports using subsequent commands. The cacheonly exporter creates a build cache, so any successive builds are instant.

$ docker buildx build --output type=cacheonly

If you don’t specify an exporter, and you don’t provide short-hand options like --load that automatically selects the appropriate exporter, Buildx defaults to using the cacheonly exporter. Except if you build using the docker driver, in which case you use the docker exporter.

Buildx logs a warning message when using cacheonly as a default:

$ docker buildx build .
WARNING: No output specified with docker-container driver.
         Build result will only remain in the build cache.
         To push result image into registry use --push or
         to load image into docker use --load

Multiple exporters

You can only specify a single exporter for any given build (see this pull request for details){:target=”blank” rel=”noopener” class=”_”}. But you can perform multiple builds one after another to export the same content twice. BuildKit caches the build, so unless any of the layers change, all successive builds following the first are instant.

The following example shows how to run the same build twice, first using the image , followed by the local .

$ docker buildx build --output type=image,tag=<registry>/<image> .
$ docker buildx build --output type=local,dest=<path/to/output> .

Configuration options

This section describes some configuration options available for exporters.

The options described here are common for at least two or more exporter types. Additionally, the different exporters types support specific parameters as well. See the detailed page about each exporter for more information about which configuration parameters apply.

The common parameters described here are:

• Compression
• OCI media type

Compression

When you export a compressed output, you can configure the exact compression algorithm and level to use. While the default values provide a good out-of-the-box experience, you may wish to tweak the parameters to optimize for storage vs compute costs. Changing the compression parameters can reduce storage space required, and improve image download times, but will increase build times.

To select the compression algorithm, you can use the compression option. For example, to build an image with compression=zstd :

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true,compression=zstd .

Use the compression-level=<value> option alongside the compression parameter to choose a compression level for the algorithms which support it:

• 0-9 for gzip and estargz
• 0-22 for zstd

As a general rule, the higher the number, the smaller the resulting file will be, and the longer the compression will take to run.

Use the force-compression=true option to force re-compressing layers imported from a previous image, if the requested compression algorithm is different from the previous compression algorithm.

Note

The gzip and estargz compression methods use the compress/gzip package, while zstd uses the github.com/klauspost/compress/zstd package.

OCI media types

Exporters that output container images, support creating images with either Docker media types (the default) or with OCI media types. This is supported by the image , registry , oci and docker exporters.

To export images with OCI media types set, use the oci-mediatypes property. For example, with the image exporter:

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true,oci-mediatypes=true .

Build info

Exporters that output container images, allow embedding information about the build, including information on the original build request and sources used during the build. This is supported by the image , registry , oci and docker exporters.

This build info is attached to the image configuration:

{
  "moby.buildkit.buildinfo.v0": "<base64>"
}

By default, build dependencies are attached to the image configuration. You can turn off this behavior by setting buildinfo=false .

What’s next

Read about each of the exporters to learn about how they work and how to use them:

• Image and registry exporters
• OCI and Docker exporters.
• Local and tar exporters

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.