Boost Docker Build Speed with BuildKit’s RUN --mount Cache Feature

What is Docker BuildKit?

Docker BuildKit, introduced in Docker 18.09, replaces the classic builder with a faster, more flexible engine that supports parallel builds, fine‑grained cache control, inline build secrets, and richer diagnostics.

Enabling BuildKit

You can turn on BuildKit either by setting the environment variable DOCKER_BUILDKIT=1 before the docker build command or by adding a JSON configuration file /etc/docker/daemon.json with the following content:

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

After updating the daemon configuration, restart Docker with sudo systemctl restart docker.

Using RUN --mount for Cache

The RUN --mount instruction lets you mount caches, secrets, or other file systems during a build. The most common pattern for caching third‑party dependencies is RUN --mount=type=cache,target=<path> <command>. type=cache: specifies a cache mount. target=<path>: defines the directory inside the container where the cache is stored.

Practical Example: Caching npm Dependencies

Below is a Dockerfile that builds a Node.js project while caching the /root/.npm directory, dramatically reducing install time on subsequent builds.

# syntax=docker/dockerfile:1.3

# Stage 1: Install dependencies
FROM node:14 AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm install

# Stage 2: Build the application
COPY . .
RUN npm run build

# Stage 3: Create the runtime image
FROM node:14
WORKDIR /app
COPY --from=builder /app ./
CMD ["node", "dist/app.js"]

During the build, the RUN --mount=type=cache,target=/root/.npm line mounts a persistent cache directory, so npm packages are reused in later builds.

Other Advanced BuildKit Features

Inline Build Secrets : Use --mount=type=secret to inject sensitive data (e.g., API keys) at build time without leaving them in the final image.

Multi‑Stage Builds : Split the build into separate stages to keep the final image small and only contain runtime artifacts.

Parallel Builds : BuildKit automatically runs independent steps in parallel, shortening overall build time.

# syntax=docker/dockerfile:1.3

# Example of a secret mount
RUN --mount=type=secret,id=mysecret \
    sh -c 'echo "$(< /run/secrets/mysecret)" > /app/secret'

This snippet mounts a secret identified as mysecret into /run/secrets/mysecret and writes its content to /app/secret inside the container.

Conclusion

Docker BuildKit, combined with the RUN --mount cache and secret capabilities, provides a powerful toolkit for accelerating builds, securing sensitive data, and producing leaner images. Enabling BuildKit and leveraging these features can significantly improve development and deployment efficiency in real‑world projects.