diff --git a/content/manuals/build/builders/_index.md b/content/manuals/build/builders/_index.md index e1a9334eab..c926822df0 100644 --- a/content/manuals/build/builders/_index.md +++ b/content/manuals/build/builders/_index.md @@ -65,6 +65,48 @@ To switch between builders, use the `docker buildx use ` 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 and 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, for ensuring 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, diff --git a/content/manuals/build/concepts/overview.md b/content/manuals/build/concepts/overview.md index 8b30d38540..e8a101e649 100644 --- a/content/manuals/build/concepts/overview.md +++ b/content/manuals/build/concepts/overview.md @@ -38,6 +38,11 @@ the CLI plugin from source, or grab a binary from the GitHub repository and install it manually. See [Buildx README](https://github.com/docker/buildx#manual-download) on GitHub for more information. +> [!NOTE] +> While `docker build` invokes Buildx under the hood, there are subtle +> differences between this command and the canonical `docker buildx build`. +> For details, see [Difference between `docker build` and `docker buildx build`](../builders/_index.md#difference-between-docker-build-and-docker-buildx-build). + ## BuildKit BuildKit is the daemon process that executes the build workloads.