GitHub Actions cache restore is slow: how to speed up

TL;DR

Slow cache restores are usually a cache that is too big, a key that misses too often, or a cache stored far from the runner. Fix it by caching less (only dependencies, not build outputs), designing keys that hit (lockfile hash plus a stable prefix), and keeping cache size under a few hundred MB. A cache that restores slower than a fresh install is worse than no cache.

The query

GitHub Actions cache restore is slow: how to speed up

Use this when

• The cache restore step takes minutes
• Caches miss on most runs
• You are deciding what belongs in the cache
• Runners are far from cache storage (self-hosted, other regions)

Not for when

• Slow jobs with no cache involved
• Artifact upload/download speed (different mechanism)
• Choosing a CI provider

Steps

Step 1: Measure what the cache actually saves

Compare job duration with and without the cache step. If the restore plus save time is close to a fresh dependency install, the cache is not earning its keep. Get the number before optimizing. Expected output: a baseline: cache saves X minutes per run, or it does not.

Step 2: Shrink what you cache

Cache package manager directories only, not build outputs, node_modules with binaries for the wrong platform, or entire working directories. Exclude aggressively; every extra hundred MB is restore time on every run. Expected output: cache size drops substantially; restore time drops with it.

Step 3: Design keys that hit

Use a primary key with the lockfile hash and restore-keys with stable prefixes so partial matches still hit. A key that changes on every commit (branch name plus SHA) misses constantly and each miss writes a new multi-hundred-MB cache. Expected output: cache hit rate climbs; fewer new cache entries written per week.

Step 4: Split caches by job

One giant shared cache restored by every job is slower than small per-job caches. Split by ecosystem (npm cache, pip cache, cargo cache) so each job restores only what it needs. Expected output: each job's restore step touches a smaller, more relevant cache.

Step 5: Consider alternatives for huge dependencies

For very large toolchains (browsers, SDKs), a prebuilt runner image or a container with dependencies baked in beats cache restore. If the cache is over 1GB, it is probably the wrong tool. Expected output: jobs start with dependencies already present; cache steps removed entirely.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_eh4glJvQdX4WEw046D58vg