buildx/docs/guides/exporters/index.md

Exporters overview

BuildKit exporters allow outputting the results of a build to different locations.

...

Buildx supports the following exporters:

• image / registry: exports the build result into a container image.
• 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 as a local OCI image layout.
• docker: exports the build result as a local Docker image specification.

Each exporter creates outputs designed for different use cases. To build container images ready to load or push to a registry, you can use the image exporter. Alternatively, you can use the oci or docker exporters to export the container image to disk directly, to import or post-process as you want. Finally, if you just want the output of the final root filesystem, you can use the local or tar exporters.

Command syntax

To use any of the exporters, you need to specify it by either using the available shorthands, or passing the exporter name and its parameters to the --output flag.

To get the full flexibility out of the various exporters buildkit has to offer, you'll need to use the full form of the --output flag. However, for ease-of-use, buildx also offers various familiar short-hands.

Pushing images

You may already be familiar with the following buildx command syntax using the -t/--tag and --push shorthands to push the resulting image to a registry:

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

You can replicate this command without the shorthands, using the full --output flag:

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

Loading images

Images built using the Docker "default" Buildx driver will be automatically loaded into the engine. This means you can run them immediately, and they'll be visible in the docker images view.

Images built using any of theh other drivers will not be automatically loaded, and instead require manually adding the --load flag:

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

Multiple exporters

While currently only a single exporter is supported, you can perform multiple builds one after another to export the same content twice - because of caching, as long as nothing changes inbetween, then all builds after the first should be instantaneous.

For example, using both the image exporter and the local exporter

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

Configuration options

This section describes some of the 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

For all exporters that compress their 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 or with OCI media types. By default, BuildKit exports images using Docker image types.

To export images with OCI mediatypes 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 build info is attached to the image configuration:

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

By default, the build dependencies are inlined in the image configuration. You can disable this behavior using the buildinfo attribute.

What's next

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

• image / registry
• local
• tar
• oci
• docker