Introduction

BuildKit is Docker's newer build engine, and it changes how image builds handle caching, parallel steps, secrets, and advanced Dockerfile features. In practice, you usually enable or disable it in one of two ways: per command with an environment variable, or persistently through Docker's daemon or Docker Desktop configuration.

Enable or Disable BuildKit for One Build

The fastest way to control BuildKit is to set DOCKER_BUILDKIT for a single command.

Enable it:

DOCKER_BUILDKIT=1 docker build -t my-app .

Disable it:

DOCKER_BUILDKIT=0 docker build -t my-app .

This is useful when you want to compare build behavior, work around a temporary compatibility issue, or test whether a Dockerfile depends on BuildKit-only instructions.

If you use PowerShell on Windows, the syntax is different:

$env:DOCKER_BUILDKIT = "1"
docker build -t my-app .

That setting only affects commands run in that shell session unless you make it persistent.

Configure BuildKit Persistently

On Linux, a common persistent option is to enable the feature in Docker's daemon configuration:

1{
2  "features": {
3    "buildkit": true
4  }
5}

That file is typically /etc/docker/daemon.json. After editing it, restart Docker:

sudo systemctl restart docker

To disable BuildKit globally, switch the value to false and restart again.

In Docker Desktop, you normally change the same engine configuration through the settings UI rather than editing system files directly. The underlying idea is the same: the features.buildkit flag controls the default behavior for ordinary docker build commands.

BuildKit Changes What Your Dockerfile Can Do

Some Dockerfile features only work with BuildKit. One common example is RUN --mount, which lets you mount caches or secrets during a build step:

1# syntax=docker/dockerfile:1.7
2FROM python:3.12-slim
3WORKDIR /app
4
5COPY requirements.txt .
6RUN --mount=type=cache,target=/root/.cache/pip \
7    pip install -r requirements.txt

If you disable BuildKit and try to build this file, the build will fail because the classic builder does not understand that mount syntax.

That means the question is not only "how do I toggle BuildKit?" but also "does my current Dockerfile require it?"

docker build Versus docker buildx build

A common point of confusion is buildx. The docker buildx build command is built on BuildKit, so if you are using buildx, you are already in the BuildKit world. Toggling DOCKER_BUILDKIT=0 mainly affects the legacy docker build path, not the buildx workflow.

For example:

docker buildx build --platform linux/amd64,linux/arm64 -t my-app:latest .

This uses BuildKit features such as advanced builders and multi-platform output. If your team depends on buildx, disabling BuildKit is usually not a real option.

When You Might Disable It

Most modern setups leave BuildKit enabled. Temporary reasons to turn it off include:

• reproducing behavior from an older CI pipeline
• debugging a legacy Dockerfile
• confirming whether a third-party tool depends on the old builder

In most other cases, BuildKit is the better default because it usually builds faster and supports better caching behavior.

Common Pitfalls

• Setting DOCKER_BUILDKIT=1 in one shell and expecting other terminals or CI jobs to inherit it automatically.
• Disabling BuildKit while the Dockerfile uses BuildKit-only features such as RUN --mount.
• Editing daemon.json without restarting Docker, which leaves the old setting in effect.
• Assuming docker buildx build can be switched back to the classic builder with the same toggle.
• Confusing the Docker daemon setting with Docker Desktop UI settings when working across Linux, macOS, and Windows.

Summary

• Use DOCKER_BUILDKIT=1 or 0 to enable or disable BuildKit for one build command.
• Use Docker's engine configuration to make the setting persistent.
• BuildKit is required for modern Dockerfile features such as cache and secret mounts.
• 'docker buildx build already depends on BuildKit.'
• Leave BuildKit enabled unless you have a specific compatibility or debugging reason to turn it off.