Fix Docker error: buildx required — enable BuildKit or install buildx

What this error means

You ran a build that needs BuildKit features (for example, --platform, cache mounts, or new Dockerfile syntax) and Docker fell back to the legacy builder. The CLI tells you either to enable BuildKit (DOCKER_BUILDKIT=1) or to install the buildx plugin.

You can fix it in two ways:

• Enable BuildKit for docker build (temporary or default), or
• Use docker buildx (requires the buildx CLI plugin).

Quickstart: the fast fix

• One-off build with BuildKit (current shell only):

# Linux/macOS
export DOCKER_BUILDKIT=1
docker build -t myimg:latest .

# Windows PowerShell
$env:DOCKER_BUILDKIT = "1"
docker build -t myimg:latest .

• If you prefer buildx:

docker buildx version || echo "buildx not installed"
# Create and use a builder (first time only)
docker buildx create --name devbuilder --use
# Build using buildx
docker buildx build -t myimg:latest --load .

Minimal working example (uses a BuildKit feature)

Dockerfile:

# syntax=docker/dockerfile:1.6
FROM alpine:3.20
# BuildKit-only cache mount to speed up apk operations
RUN --mount=type=cache,target=/var/cache/apk apk add --no-cache curl
CMD ["sh", "-lc", "echo Hello from BuildKit"]

Build with classic docker + BuildKit enabled:

export DOCKER_BUILDKIT=1
docker build -t hello-bk:latest .

Or build with buildx and load the image into the local Docker image store:

docker buildx create --name devbuilder --use 2>/dev/null || docker buildx use devbuilder
docker buildx build -t hello-bk:latest --load .

Multi-platform (requires QEMU emulation or native nodes):

docker buildx build --platform linux/amd64,linux/arm64 -t youruser/hello-bk:latest --push .

Step-by-step fixes

1. Enable BuildKit for your current shell

• Linux/macOS:
  • export DOCKER_BUILDKIT=1
• Windows PowerShell:
  • $env:DOCKER_BUILDKIT = "1"
• Windows cmd:
  • set DOCKER_BUILDKIT=1

Verify: run docker build ... again.

1. Make BuildKit the default (persistent)

Edit the daemon config and restart Docker.

• Linux (root):

sudo mkdir -p /etc/docker
printf '{"features":{"buildkit":true}}' | sudo tee /etc/docker/daemon.json
sudo systemctl restart docker

• Windows (Docker Desktop/Engine):

# File: C:\ProgramData\Docker\config\daemon.json
# Content:
# {"features": {"buildkit": true}}
# Then restart Docker Desktop or the Docker service.

• macOS (Docker Desktop):
  • Preferences > Docker Engine > set {"features":{"buildkit":true}} and Apply & Restart.

Check that BuildKit is active:

docker info | grep -i buildkit || true

1. Install or update the buildx plugin (if you want docker buildx ...)

• Docker Desktop (macOS/Windows): buildx is included.
• Ubuntu/Debian (Docker CE repos):

sudo apt-get update
sudo apt-get install -y docker-buildx-plugin

• Fedora/CentOS/RHEL:

sudo dnf install -y docker-buildx-plugin || sudo yum install -y docker-buildx-plugin

• Arch Linux:

sudo pacman -S docker-buildx

• Homebrew (alternative on macOS/Linux):

brew install docker-buildx

• Manual plugin install (fallback): place the executable at:
  • Linux/macOS: ~/.docker/cli-plugins/docker-buildx
  • Windows: %USERPROFILE%.docker\cli-plugins\docker-buildx.exe
  • Ensure it is executable and in the correct path.

Verify:

docker buildx version

1. Compose specifics

• docker compose (V2): BuildKit is used when enabled by default or via DOCKER_BUILDKIT=1; buildx plugin unlocks advanced features and multi-platform.
• docker-compose (V1): set both variables in the shell before running compose builds:

export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1

Common causes and their fixes

• Older Docker Engine (< 19.03): upgrade Docker; BuildKit is not available.
• No buildx plugin found: install docker-buildx-plugin as shown above.
• Using --platform with docker build without BuildKit: enable DOCKER_BUILDKIT=1 or switch to docker buildx build.
• Environment variable not exported: remember exports apply only to the current shell/session.
• Corporate proxy/firewall: ensure registry access for pulling base images and QEMU setup steps.

Verification checklist

• docker version shows a recent Client/Server (20.x or newer recommended).
• docker info indicates BuildKit enabled (or builds succeed with BuildKit features).
• docker buildx version returns a version string, not an error.

Performance notes (why BuildKit is worth it)

• Parallel build graph execution and improved cache reuse.
• Inline cache to accelerate CI builds between runs:

docker buildx build \
  --cache-to=type=inline \
  --cache-from=type=registry,ref=youruser/yourimg:cache \
  -t youruser/yourimg:latest .

• Cache mounts (as shown in the Dockerfile example) reduce package manager downloads.
• Secrets and SSH mounts avoid baking credentials into layers.
• Prune unused build cache to reclaim space:

docker builder prune -f

Pitfalls and tips

• Mixed Compose versions: docker-compose (V1) needs COMPOSE_DOCKER_CLI_BUILD=1; docker compose (V2) does not.
• buildx needs a builder instance. Create it once: docker buildx create --use. Persisted across sessions.
• Multi-arch builds on a single host require emulation (binfmt/QEMU). On some distros you may need to install binfmt support before building.
• --load is only for single-platform builds; use --push for multi-platform outputs.
• When enabling BuildKit via daemon.json, ensure valid JSON; otherwise Docker fails to start.

Tiny FAQ

• Q: Do I need both DOCKER_BUILDKIT and buildx?

  • A: No. DOCKER_BUILDKIT=1 makes docker build use BuildKit. buildx is a separate CLI with extra features (multi-platform, advanced cache). Use either as needed.

• Q: Why does docker build --platform fail without BuildKit?

  • A: --platform is a BuildKit feature. Enable BuildKit or use docker buildx build.

• Q: Is BuildKit the default?

  • A: On modern Docker releases, yes, or you can force it with {"features":{"buildkit":true}} in daemon.json.

• Q: My CI still fails. What should I check?

  • A: Ensure the CI job exports DOCKER_BUILDKIT=1 (or uses docker buildx), and that the buildx plugin is available in the runner image.

• Q: How do I revert?

  • A: Remove the env var and set {"features":{"buildkit":false}} in daemon.json, then restart Docker.