README should clarify DOCKER_BUILDKIT vs docker buildx vs BuildKit

[AkihiroSuda]

[rhyek]

This is confusing for sure. Can someone post a brief comparison here seeing as how this was the third search result for "DOCKER_BUILDKIT vs buildx". Thanks!

[chuckinho]

Hello. I'm working with a group of students from UT austin and we wanted to answer this question. Let us know if you'd like us to add this to the readme.md with a merge request.

Docker Buildx

• Docker Buildx is a CLI plugin that extends the docker build command with the full support of features provided by BuildKit. You can see more information in Docker's official documentation Buildx is not Buildkit! Rather Buildx uses Buildkit.

BuildKit

• Buildkit is a general artifact builder that can be used to build many other output formats (aside from just Dockerfiles). General information can be found in readme.md.

DOCKER_BUILDKIT

• DOCKER_BUILDKIT is an environment variable that tells docker to use BuildKit when building images. In contrast, Buildx builds using the BuildKit engine and does not require DOCKER_BUILDKIT=1 environment variable to start the builds. Details about DOCKER_BUILDKIT can be found in synxtax.md and this docker documentation.

[inostia]

Thanks @chuckinho. Got here from Google with "DOCKER_BUILDKIT=1 vs buildx" and your response helped me.

[neersighted]

Since @AkihiroSuda drew my attention to this issue, here's what I would consider an accurate summary as of 2023:

BuildKit

BuildKit is a toolkit for building container images from a low-level representation of a build (called LLB). BuildKit includes many features and enhancements such as remote cache, OCI mediaType outputs, highly parallel builds, and includes a frontend that translates Dockerfiles to LLB to make it drop-in to existing workflows.

The Dockerfile BuildKit frontend includes various new features and syntax extensions that are unsupported by the classic builder, and they either improve the ergonomics of writing a Dockerfile, or expose native BuildKit capabilities (e.g. mounts, secrets, etc.) to the Dockerfile syntax.

Since version 18.06 of the Docker Engine/CLI, BuildKit has been built-in and usable in place of the classic builder. Since version 23.0 of the Docker Engine/CLI, BuildKit is the default builder implementation and the default client uses the native BuildKit gRPC API (in the form of Buildx).

BuildKit is also usable outside the Docker Engine integration in a standalone form -- buildkitd; and there is a reference client (buildctl) available as well for usage without the Docker CLI.

Buildx

Buildx is a Docker CLI plugin that exposes the full power of the BuildKit API/integration in a way that is familiar to users of and integrated with the Docker CLI. Buildx has additional features, such as being able to create 'containerized builders' that run an updated copy of buildkitd in order to use newer features/features unsupported by the Engine's integrated BuildKit.

Current (23.0+) versions of the Docker CLI rely on Buildx as the default implementation of the docker build command; Buildx combines full support for modern BuildKit features with default values designed to make it a seamless replacement of the classic implementation.

DOCKER_BUILDKIT

DOCKER_BUILDKIT is an environment variable understood by the Docker CLI and used to opt into or out of usage of BuildKit as the builder implementation. As Buildx always uses BuildKit, this variable only controls the docker build command (and not the docker buildx build command), and the default value and behaviors have changed over time:

• From Engine/CLI 18.06 to 20.10, DOCKER_BUILDKIT=0 was the default value, meaning BuildKit was not in use by default. When DOCKER_BUILDKIT=1 was specified, BuildKit was used as the builder implementation on the daemon side (meaning that only options understood by the classic builder could be passed to the BuildKit backend).

• Post Engine/CLI 23.0, DOCKER_BUILDKIT=1 is the default value. When DOCKER_BUILDKIT=1, docker buildx build is used to replace the implementation of docker build in the CLI, and the client natively supports BuildKit's gRPC API, unlocking the full suite of current (and future) BuildKit capabilities/features. To use BuildKit with these CLI versions, a copy of the Buildx plugin is required. When DOCKER_BUILDKIT=0 the classic builder and docker build implementation built-in to the CLI are used.

It's worth noting that I've described the default value of DOCKER_BUILDKIT as 0 for historic versions above; however this is only true when using a matched CLI/daemon version. In truth, CLI versions 18.06 to 20.10 will determine usage of BuildKit when DOCKER_BUILDKIT is not set based on the daemon's preferences. This means that the classic docker build implementation in CLI 20.10 or older will use BuildKit without an explicit DOCKER_BUILDKIT=1 when used against Engine 23.0 or newer.

[AkihiroSuda]

Thank you @neersighted

'container builders'

Maybe s/container/containerized/

meaning that only options understood by the classic builder could be passed to the BuildKit backend

Doesn't seem true?

client natively supports BuildKit

s/client/docker buildx/ ?

[neersighted]

meaning that only options understood by the classic builder could be passed to the BuildKit backend

Doesn't seem true?

I don't think that advanced BuildKit features like multiple contexts ever worked through the CLI's docker build implementation and the REST API. You need a gRPC client (e.g. Buildx, buildctl) to support them.

client natively supports BuildKit

s/client/docker buildx/ ?

I think this is more accurate, but maybe we can tweak phrasing? What I'm trying to say is that docker buildx build implementing docker build has access to the full gRPC API and can take advantage of capabilities (e.g. multiple contexts, credentials on demand, etc.) that are impossible through the REST API.

[AkihiroSuda]

I don't think that advanced BuildKit features like multiple contexts ever worked through the CLI's docker build implementation and the REST API. You need a gRPC client (e.g. Buildx, buildctl) to support them.

Some of the advanced features, such as --secret and --ssh, have been exposed to DOCKER_BUILDKIT through the Session API

[neersighted]

Ah, fair point. It's still a bit bifurcated, though. Maybe I should say something more like "the full suite of advanced BuildKit features?" to make it clear that some but not all require the new client implementation?

[neersighted]

Try the phrasing I just edited in -- I think it addresses both of your points.