How Docker BuildKit Cache Mounts Can Speed Up Your CI Builds

For solutions with multiple projects, copy all project files needed by the restore operation before running dotnet restore. Otherwise, the restore may fail or the dependency layer may be invalidated more often than necessary.

Step 3: Use Cache Mounts with Node.js

Node.js applications can also benefit from BuildKit cache mounts.

For example, npm stores downloaded package data in its local cache directory. You can mount that directory during dependency installation.

# syntax=docker/dockerfile:1

FROM node:22 AS build

WORKDIR /app

COPY package.json package-lock.json ./

RUN --mount=type=cache,target=/root/.npm \
    npm ci

COPY . .

RUN npm run build

The cache mount preserves npm's downloaded package data for later builds when the same BuildKit cache remains available.

The npm ci command still installs the dependencies specified by the lockfile. It does not simply skip installation because a cache exists. Instead, npm can reuse cached downloads when possible.

This is useful in CI pipelines where the dependency installation step frequently runs again.

For production applications, use a supported Node.js version and follow the project's established version policy.

Step 4: Use Cache Mounts for Python Packages

Python builds can use the same approach for pip's download cache.

# syntax=docker/dockerfile:1

FROM python:3.12-slim AS build

WORKDIR /app

COPY requirements.txt ./

RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --prefix=/install -r requirements.txt

COPY . .

FROM python:3.12-slim AS final

WORKDIR /app

COPY --from=build /install /usr/local
COPY . .

CMD ["python", "app.py"]

This example installs dependencies into a separate directory and copies them into the final stage.

The cache mount allows pip to reuse downloaded packages when available. It does not guarantee that every dependency installation can be skipped.

Native Python packages may require compilers or operating system libraries during installation. Make sure those build requirements are available in the build stage, and include the necessary runtime libraries in the final image.

Step 5: Make BuildKit Caches Available in GitHub Actions

Cache mounts are most useful when their contents survive between builds.

On a persistent self-hosted runner, BuildKit's cache may remain available across jobs, depending on how the builder is configured.

On GitHub-hosted runners, each job usually starts with a fresh machine. If you create a new builder for every job, its internal cache mounts may not survive the job.

This means a cache mount alone does not guarantee faster builds across separate GitHub-hosted runner jobs.

You need a caching strategy that preserves or restores the BuildKit cache between runs.

One option is to use BuildKit's external cache support through the GitHub Actions cache backend. Another is to use a registry-backed cache when that fits your workflow.

A typical docker/build-push-action configuration looks like this:

name: Build Container

on:
  push:
    branches:
      - main
  pull_request:

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build image
        uses: docker/build-push-action@v6
        with:
          context: .
          push: false
          tags: myapp:ci
          cache-from: type=gha,scope=myapp
          cache-to: type=gha,mode=max,scope=myapp

This example uses the GitHub Actions cache backend to export and import BuildKit build cache.

The mode=max setting can preserve cache for intermediate build stages as well as the final image, which is useful for multi-stage Dockerfiles.

However, external build-cache export and cache mounts are not exactly the same thing. Do not assume that every cache mount's mutable contents will be preserved by an external layer cache automatically.

If your workflow depends specifically on retaining cache-mount contents across fresh runners, verify the behavior supported by your BuildKit version and cache backend. BuildKit supports additional cache-mount persistence approaches, including using an external cache directory with the appropriate build configuration.

For simpler pipelines, the external layer cache may already provide a significant improvement by skipping unchanged dependency installation layers.

Step 6: Measure Whether the Cache Helps

Do not assume a cache mount has improved your build simply because the Dockerfile contains one.

Compare build times before and after introducing the cache.

For example, record:

• Total build duration.
• Dependency restore duration.
• Cache hit or reuse behavior.
• Time spent downloading packages.
• Cache size and storage overhead.

A first build may still be slow because the cache is empty. Later builds can improve as the cache becomes populated.

Changes to lockfiles, project files, base images, package versions, or build configuration may also require additional downloads or invalidate relevant layers.

Run several builds with representative changes to understand the real benefit.

Common Cache Mount Mistakes to Avoid

1. Assuming the Cache Always Survives CI Jobs

A cache mount is tied to the BuildKit builder's cache storage. If that storage disappears after a job, the next build may start with an empty cache.

Choose a persistent builder or a suitable external cache strategy.

2. Mounting the Wrong Directory

The cache mount must match the package manager's actual cache location.

For example, mounting /root/.npm will not help if npm runs under another user and stores its cache elsewhere.

Check the environment used by the build command.

3. Forgetting to Copy Dependency Files First

Copying all source files before dependency restoration can cause unnecessary layer invalidation.

Copy project files and lockfiles first, restore dependencies, and then copy the remaining source files when the application structure allows it.

4. Expecting Cache Mounts to Skip Installation Commands

A cache mount reuses cached files; it does not automatically skip dotnet restore, npm ci, or pip install.

Those commands still need to validate and install the required dependencies.

5. Using an Unbounded Cache Strategy

Caches consume storage and can become expensive to maintain. Review cache sizes, cleanup policies, and the number of separate cache IDs used by your builds.

6. Sharing Incompatible Cache Contents

Use appropriate cache IDs and isolation for different package managers, projects, or build environments.

Do not assume that caches can be safely shared across incompatible tool versions or environments.

Best Practices for Faster Docker Builds

• Combine layer caching with cache mounts: Each feature reduces different kinds of repeated work.
• Copy lockfiles before application source: Preserve dependency layers when source code changes.
• Use multi-stage builds: Keep build tools and unnecessary dependencies out of the final image.
• Choose stable cache IDs: Reuse the intended cache across compatible build steps.
• Plan for ephemeral CI runners: Configure persistent or external caching when necessary.
• Measure before and after: Use actual build timings rather than assumptions.
• Keep dependencies reproducible: Use lockfiles and controlled package versions so caching does not replace dependency management.

Conclusion

Docker BuildKit cache mounts can reduce CI build times by reusing downloaded packages and other build files. They are particularly useful for projects that repeatedly restore NuGet, npm, or Python dependencies.

The best results come from combining cache mounts with well-structured Docker layers and an external cache strategy that fits your CI environment.

Remember that a cache mount is an optimization, not a guarantee that a build command will be skipped or that cache contents will survive every runner restart. Configure the cache deliberately, measure its impact, and keep dependency management reproducible.