Fix: “DEPRECATED: The legacy builder is deprecated” in Docker

If you recently tried building a Docker image and saw this warning:

DEPRECATED: The legacy builder is deprecated and will be removed in a future release.
            Install the buildx component to build images with BuildKit:
            https://docs.docker.com/go/buildx/

Don’t worry — this isn’t a breaking error. It’s just Docker telling you that the old image builder is going away and you should start using BuildKit (docker buildx).

In this post, I’ll explain why you’re seeing this message and how to fix it step by step.

🔎 Why am I seeing this warning?

• Docker used to rely on the legacy builder for the docker build command.
• Now, Docker recommends using BuildKit (via docker buildx).
• BuildKit is faster, supports parallel builds, multi-platform images, and advanced caching.
• The legacy builder will soon be removed from Docker, so you should migrate to buildx.

🛠️ How to Resolve the Docker Legacy Builder Warning

Follow these steps to fix the issue and start using BuildKit.

Check if Buildx is Installed

docker buildx version

If you see a version number, Buildx is already available.

Install Buildx (if missing)

On most Docker versions, Buildx is bundled. But if not, you can install it manually:

mkdir -p ~/.docker/cli-plugins
curl -SL https://github.com/docker/buildx/releases/latest/download/buildx-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m) \
  -o ~/.docker/cli-plugins/docker-buildx
chmod +x ~/.docker/cli-plugins/docker-buildx

Enable BuildKit by Default

You can enable BuildKit globally so every docker build uses it.

Option A: Set environment variables temporarily

export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1

Option B: Add it permanently to ~/.bashrc

echo "export DOCKER_BUILDKIT=1" >> ~/.bashrc
echo "export COMPOSE_DOCKER_CLI_BUILD=1" >> ~/.bashrc
source ~/.bashrc

Now, every new terminal session will automatically enable BuildKit.

Option C: Configure Docker daemon

Edit /etc/docker/daemon.json and add:

{
  "features": { "buildkit": true }
}

Restart Docker after editing:

sudo systemctl restart docker

Build with Buildx

Now use Buildx instead of the legacy builder:

docker buildx build -t myimage:latest .

This will run with the modern BuildKit engine and remove the deprecation warning.

Conclusion

This warning is not an error but a heads-up from Docker. The legacy builder is going away, and switching to BuildKit (docker buildx) makes your builds faster and future-proof.

By enabling BuildKit now, you won’t run into issues when Docker finally removes the old builder.