Selecting and Using Different Docker Builders

- `docker`: uses the BuildKit library bundled into the Docker daemon. - `docker-container`: creates a dedicated BuildKit container using Docker. - `kubernetes`: creates BuildKit pods in a Kubernetes cluster. - `remote`: connects directly to a manually managed BuildKit daemon. ## Selected builder Selected builder refers to the builder that's used by default when you run build commands. When you run a build, or interact with builders in some way using the CLI, you can use the optional `--builder` flag, or the `BUILDX_BUILDER` [environment variable](../building/variables.md#buildx_builder), to specify a builder by name. If you don't specify a builder, the selected builder is used. Use the `docker buildx ls` command to see the available builder instances. The asterisk (`*`) next to a builder name indicates the selected builder. ```console $ docker buildx ls NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS default * docker default default running v0.11.6 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386 my_builder docker-container my_builder0 default running v0.11.6 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386 ``` ### Select a different builder To switch between builders, use the `docker buildx use <name>` command. After running this command, the builder you specify is automatically selected when you invoke builds. ### Difference between `docker build` and `docker buildx build` Even though `docker build` is an alias for `docker buildx build`, there are subtle differences between the two commands. With Buildx, the build client and the daemon (BuildKit) are decoupled. This means you can use multiple builders from a single client, even remote ones. The `docker build` command always defaults to using the default builder that comes bundled with the Docker Engine, to ensure backwards compatibility with older versions of the Docker CLI. The `docker buildx build` command, on the other hand, checks whether you've set a different builder as the default builder before it sends your build to BuildKit. To use the `docker build` command with a non-default builder, you must either: - Specify the builder explicitly, using the `--builder` flag or the `BUILDX_BUILDER` environment variable: ```console $ BUILDX_BUILDER=my_builder docker build . $ docker build --builder my_builder . ``` - Configure Buildx as the default client by running the following command: ```console $ docker buildx install ``` This updates your [Docker CLI configuration file](/reference/cli/docker/_index.md#configuration-files) to ensure all of your build-related commands are routed via Buildx. > [!TIP] > To undo this change, run `docker buildx uninstall`.  In general, we recommend that you use the `docker buildx build` command when you want to use custom builders. This ensures that your [selected builder](#selected-builder) configuration is interpreted correctly.  ## Additional information - For information about how to interact with and manage builders, see [Manage builders](./manage.md) - To learn about different types of builders, see [Build drivers](drivers/_index.md)

This section explains how to select and switch between different Docker builders using the `docker buildx use` command. It highlights the differences between `docker build` and `docker buildx build`, noting that `docker build` defaults to the Docker Engine's bundled builder for compatibility, while `docker buildx build` respects the selected builder. It provides methods for using `docker build` with non-default builders, including specifying the builder via flags or environment variables, and configuring Buildx as the default client. It recommends using `docker buildx build` for custom builders.