Docker layer caching in CI, explained
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.
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
| Approach | How it works | Trade-offs |
|---|---|---|
| Registry cache | BuildKit 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 backend | BuildKit 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 cache | The 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
.dockerignoreso 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?
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?
Sources
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/