BuildKit — Concurrent, Cache-Efficient OCI Image Builder

What it is

BuildKit is the modern container image builder that powers docker build and docker buildx. It replaces the legacy Docker builder with a concurrent DAG-based build engine that executes independent build steps in parallel. Features include cross-platform builds, remote caching (to registries, S3, or local directories), rootless operation, and efficient layer management.

This tool is for DevOps engineers and platform teams who need faster container builds, multi-architecture images, or advanced caching strategies in CI/CD pipelines.

How it saves time or tokens

BuildKit's concurrent execution builds independent stages simultaneously, reducing total build time. Layer caching avoids rebuilding unchanged layers. Remote caching shares cache across CI runners, so the first build on a fresh runner is still fast. Multi-stage builds with BuildKit are optimized to only execute stages that contribute to the final image.

How to use

1. Enable BuildKit in Docker or use it standalone.
2. Write multi-stage Dockerfiles.
3. Use cache mounts and remote caching.
4. Build multi-platform images.

# Enable BuildKit in Docker
export DOCKER_BUILDKIT=1

# Or use buildx (BuildKit is the default)
docker buildx build -t myapp:latest .

# Multi-platform build
docker buildx build --platform linux/amd64,linux/arm64 \
  -t myapp:latest --push .

# With remote cache
docker buildx build \
  --cache-from type=registry,ref=myregistry/myapp:cache \
  --cache-to type=registry,ref=myregistry/myapp:cache \
  -t myapp:latest .

Example

A Dockerfile optimized for BuildKit:

# syntax=docker/dockerfile:1

# Stage 1: Dependencies (cached separately)
FROM node:20-slim AS deps
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --production

# Stage 2: Build (runs in parallel with deps if independent)
FROM node:20-slim AS build
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
RUN npm run build

# Stage 3: Production image
FROM node:20-slim
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
CMD ["node", "dist/index.js"]

The --mount=type=cache directive caches npm packages across builds.

Related on TokRepo

• DevOps tools — Container and build tools
• Automation tools — CI/CD automation

Common pitfalls

• Cache mount targets are local to the builder. They do not automatically share across CI runners. Use remote caching for CI.
• Multi-platform builds require QEMU emulation for non-native architectures, which is slower. Native builders are faster.
• The # syntax=docker/dockerfile:1 header is required for advanced BuildKit features like cache mounts.
• BuildKit garbage collects old cache by default. Tune --max-old-age and --max-used-space for your needs.
• Rootless mode has limitations with certain network operations and volume mounts.