Exporters Use Cases: Registry, File Layout, Filesystem, and Cache

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: ```console $ 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: ```console $ docker buildx build \ --output type=image,name=<registry>/<image>,push=true . ``` You can also use the `registry` exporter, which does the same thing: ```console $ 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. ```console $ 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. ```console $ docker buildx build --output type=local,dest=<path/to/output> . ``` The `local` exporter is useful in [multi-stage builds](../building/multi-stage.md) since it allows you to export only a minimal number of build artifacts, such as 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. ```console $ 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.

The `registry` and `image` exporters push built images to a container registry using the `--push` option. The `oci` and `docker` exporters save build results to an image layout on the local filesystem as a tar archive, controlled by the `dest` parameter. The `local` and `tar` exporters export the built filesystem either as a directory structure or a tarball. The `cacheonly` exporter runs a build without exporting any output, creating a build cache for faster subsequent builds. If no exporter is specified, `cacheonly` is used by default, except with the `docker` driver, which uses the `docker` exporter.