Published ยท Updated
Why Docker cache export can outlast the build
A fast Docker build can still spend minutes exporting cache. Learn what BuildKit is moving, which cache mode fits the job, and what to measure before changing backends.
Cache export continues after Dockerfile execution.
BuildKit can finish executing Dockerfile instructions and still have work left to do. An external cache export serializes cache records and transfers reusable layers to the selected backend so a future builder can import them.
That cost is easiest to notice on an ephemeral CI runner. The local BuildKit store disappears with the machine, so the export is what makes the work available to the next run. A short build with a large cache graph can therefore spend more time exporting than executing.
mode=min and mode=max export different sets of layers.
Use mode=min for final-image layers
It exports cache for layers that contribute to the final image. The result is usually smaller and quicker to move, but intermediate stages may need to run again.
Use mode=max for intermediate stages too
It includes intermediate stages as well as layers used by the final image. That can improve repeat builds with multi-stage Dockerfiles, at the cost of a larger export.
Start with the smallest cache that preserves the expensive work your next build actually needs. More exported data is only useful when later builds can reuse it.
Separate execution, import, and export time.
- 1. Record a cold run. Keep the repository, Dockerfile, runner size, region, and image output fixed.
- 2. Record a warm run. Confirm which stages report cache hits instead of treating total workflow time as a cache measurement.
- 3. Time the export. A large upload may point to cache depth, compression, network throughput, or repeated publication from too many jobs.
- 4. Change one variable. Compare cache modes or backends with the same workload. Keep image push, tests, and unrelated setup outside the number where possible.
Find which part of the build is slow.
| What the log shows | What to check next |
|---|---|
| Instructions are cached, but cache export takes minutes | What to check nextCompare the export duration and transferred bytes with the execution duration. Test mode=min against mode=max on a backend that supports both, keeping the Dockerfile and runner fixed. Check whether losing intermediate-stage reuse makes the next build slower. |
| A source change reruns an expensive install or compilation | What to check nextInspect which inputs invalidate the instruction. If the instruction must rerun, measure whether a persistent download mount or the tool's native cache avoids expensive work inside it. |
| The original runner hits cache but a fresh runner misses | What to check nextCheck that the first build published successfully and the second build can read the same cache scope. Compare Dockerfile inputs and target platform. Local reuse alone does not prove the remote cache is working. |
| Mount restore and save take longer than the command | What to check nextCompare a run without that mount. Keep persistence only when the avoided downloads or computation justify the transfer cost; a larger saved cache is not necessarily a faster build. |
Reuse layers and caches inside Docker instructions.
The BoringCache Docker adapter uses a native BuildKit backend to share layers across CI and local builds. BuildKit decides which instructions can be skipped. Optional persistent cache mounts and native tool caching preserve dependency and compiler results when instructions rerun. Compare total build time, including cache transfers, using the linked Docker benchmarks.
The GitHub Actions layer-cache backend does not preserve cache mounts by default. Docker documents a separate cache-dance workaround. BoringCache's Docker adapter can persist selected mounts alongside its layer cache; native tool caching is another option when the tool can reuse individual results.
Start with your repository
Run boringcache onboard once. BoringCache finds useful cache state, writes .boringcache.toml, and keeps the same cache names across local builds and CI.