Skip to main content
Earlier we walked through four common problems with the traditional Docker builder:
  • Packages are re-downloaded from scratch on every build.
  • Secrets can leak into image metadata despite workarounds.
  • Builds are locked to the architecture of the machine used for building.
  • Independent stages in multi-stage builds run sequentially instead of in parallel.
All four issues stem from the same root cause: the legacy Docker build engine was designed for a simpler era and lacks modern build features. Docker replaced that engine with BuildKit, and since Docker 23.0 (January 2023) BuildKit is the default builder — it’s enabled automatically. BuildKit is what docker build uses under the hood. The ”[+] Building 12.3s” style status lines you see are BuildKit’s output.
A clean infographic with the large title "BuildKit." It shows a timeline of Docker releases: Docker 1.13 (2017 announced), Docker 18.09 (2018 opt-in), and Docker 23.0 (Jan 2023 default).
What BuildKit gives you (short list)
  • Smarter caching: BuildKit hashes file contents used by a layer (not timestamps), so cache hits are more reliable.
  • Four modern features that directly address the four legacy problems:
    1. Cache mounts
    2. Secret mounts
    3. Multi-platform builds
    4. Parallel stage execution
Here’s a typical BuildKit-style build status you may encounter:
For advanced BuildKit features (secrets, cache mounts, multi-platform builds, etc.) use docker buildx build. For most simple builds docker build already uses BuildKit by default on modern Docker releases.
Below we walk through the four BuildKit features, with examples and CLI usage. Summary table — problems mapped to BuildKit features
  1. Cache mounts — avoid re-downloading packages
Use a cache mount to persist package manager caches (or other build caches) between builds. To enable the --mount syntax you must declare the modern Dockerfile frontend at the top of the Dockerfile:
The # syntax=... directive tells BuildKit to use the newer frontend; without it the --mount syntax won’t be available. First build downloads packages normally:
Subsequent builds restore the cache and avoid network downloads:
Cache mounts dramatically reduce build times for dependency-heavy steps.
  1. Secret mounts — avoid leaking secrets into images
Instead of passing secrets via build args or copying them into the image (which leaves traces), mount a secret for a single RUN step. Example pattern:
Build and pass the secret from your local filesystem:
Never bake secrets into image layers or pass them as plain build args. Use BuildKit secret mounts so secrets are available only during the RUN step and are not written to layers or image metadata.
You can verify the secret is not present in image history:
  1. Multi-platform builds — build for different architectures in one command
BuildKit (via Buildx) can produce images for multiple architectures in a single command. It builds each variant and pushes a manifest list to the registry so clients automatically pull the correct architecture. Example: build and push both amd64 and arm64 images:
When pushed as a multi-arch manifest, pulling on different machines pulls the correct variant transparently:
and on another machine (different architecture):
This workflow is why many Docker Hub images “just work” on Apple Silicon and other platforms.
  1. Parallel stage execution — speed up independent multi-stage builds
If stages in a multi-stage Dockerfile are independent (for example, separate frontend and backend builds), BuildKit analyzes the stage dependency graph (DAG) and runs independent stages in parallel. You do not need to change your Dockerfile — write the stages as usual and BuildKit parallelizes when possible. Example build that shows parallel stage execution:
Because frontend and backend stages ran concurrently, total build time is significantly lower than running them sequentially. Final notes and best practices
  • Dockerfile fundamentals remain the same: layers, FROM, RUN, COPY, ENTRYPOINT, etc., still apply.
  • BuildKit is a faster, smarter engine that preserves the same Dockerfile semantics while adding powerful features.
  • Use cache mounts for dependency-heavy steps, secret mounts to avoid leaking credentials, Buildx for multi-arch builds, and rely on BuildKit’s DAG analysis for parallelism.
  • For everyday builds docker build is sufficient; for advanced workflows use docker buildx build.
Links and references

Watch Video