CI Runnerscirunners.org
Guide

Docker layer caching in CI, explained

Answer in brief

Docker builds are slow in CI because an ephemeral runner starts every job with an empty layer cache. You can export and import the cache through a registry or the CI cache, which costs a network transfer each way, or use a runner that keeps the build cache on a persistent disk, so unchanged layers are already present. Ordering the Dockerfile well and building each architecture natively help with either approach.

By the CI Runners editors · Updated

Why CI Docker builds start cold

Docker builds an image as a stack of layers and reuses any layer whose instruction and inputs are unchanged. On a laptop, yesterday’s layers are on disk, so a rebuild after a small code change takes seconds.

An ephemeral runner is a new machine for every job. Its Docker storage is empty, so the build pulls the base image and executes every instruction again, including the slow ones that install system packages and dependencies.

Three ways to get the cache back

ApproachHow it worksTrade-offs
Registry cacheBuildKit pushes cache layers to a container registry (type=registry) and pulls them on the next build.Works on any runner. Every build uploads and downloads cache over the network; large images lose much of the gain.
GitHub Actions cache backendBuildKit stores cache blobs in the Actions cache (type=gha).No registry needed. Subject to the repository’s cache size limit and eviction, and to transfer speed.
Persistent layer cacheThe runner provider attaches a disk that still holds the previous build’s layers, or runs the build on a long-lived builder.Fastest when it hits, since nothing is transferred. Depends on the provider; check how the cache is scoped and billed.

Make the Dockerfile cache-friendly

No cache backend helps a Dockerfile that invalidates its own layers. The basics:

  • Copy the dependency manifest and install dependencies before copying the source, so a code change does not reinstall everything.
  • Put rarely changing steps first and frequently changing steps last.
  • Use BuildKit cache mounts (RUN --mount=type=cache) for package-manager directories.
  • Use multi-stage builds so build tools do not end up in the final image.
  • Keep a .dockerignore so irrelevant files do not bust the cache.

Multi-architecture images

Building an arm64 image on an x64 runner uses QEMU emulation, which makes compilation many times slower. With arm64 runners you build each architecture natively in its own job and then merge the two into one multi-platform manifest. See ARM64 builds.

What to check in a runner

  • Is there a documented Docker layer caching feature, and does it need changes to the workflow?
  • Is the cache per repository, per branch or shared? Can pull requests from forks write to it?
  • How large can it grow, how is it evicted and is it billed as storage?
  • Does each job have its own Docker daemon? VM and microVM runners do; pod-based self-hosted runners need Docker-in-Docker or a rootless builder.

The Docker builds use case lists the runners that document layer caching.

Frequently asked questions

How do I cache Docker layers in GitHub Actions?
With docker/build-push-action, set cache-from and cache-to to a registry (type=registry) or to the Actions cache (type=gha). Both export and import the cache over the network. Alternatively use a runner provider with a persistent Docker layer cache, which keeps layers on a disk attached to the job.
Is a persistent layer cache safe?
It is shared state between jobs, so scope matters. Check which branches and repositories can write to the cache and whether pull requests from forks are excluded, as you would for any CI cache.

Sources

  1. docs.docker.com/build/cache/
  2. docs.docker.com/build/cache/backends/
  3. docs.docker.com/build/ci/github-actions/cache/
  4. docs.docker.com/build/building/multi-platform/

Check before you rely on it. Products change quickly, and this page reflects public documentation as of November 22, 2026. Confirm anything that matters in the provider’s own documentation.

Cite this page

CI Runners. (2026). Docker layer caching in CI, explained. cirunners.org. Last reviewed November 22, 2026. https://cirunners.org/guides/docker-layer-caching-in-ci/