Skip to content

Home / Blog / Caching

When does a GitHub Actions cache cost more than it saves? Restore times, measured

Save and restore times for caches of 50 MB to 2 GB and 100 to 500,000 files on ubuntu-24.04, six real projects, and the hit rate at which a cache starts to pay.

A cache costs more than it saves when restoring it takes about as long as redoing the work. On GitHub-hosted ubuntu-24.04, restoring an entry of up to 161 MB took a median of 1.4 to 5.3 seconds, so an install that finishes in a second or two, such as pnpm at 0.9, is slower with a cache. For installs of 11 to 19 seconds, caching the installed tree paid back once 17 to 31 per cent of runs hit it. Our GitHub Actions cache guide has the full rules.

In short
  • Restoring an entry of up to 161 MB and 100,000 files took a median of 1.4 to 5.3 seconds; 500,000 files took 15.7.
  • A fresh pnpm install took 0.9 seconds and a restore 2.3, so no hit rate makes caching it pay.
  • Caching the installed tree paid back at hit rates of 17 to 31 per cent for installs of 11 to 19 seconds.
  • Restoring pip's download directory saved nothing, because the install from it still took 11.8 of the 13.4 seconds.
  • Do not cache an install that takes about 3 seconds or less, and prefer the installed tree to the package manager's directory.

What is the rule?

Per run, a cache gains the time of the fresh install less the time of the restore and of whatever work is left after it, and it loses the save and a failed restore when the key does not match. So it pays when the share of runs that hit is above (save + 0.4) / (gain + save + 0.4), where the gain is the fresh time less restore less what remains, and 0.4 seconds is what a restore that finds nothing took in our runs. Four rules follow from the measurements below.

The four rules

If a fresh install takes about 3 seconds or less, do not cache it: the restore alone costs that. Cache the installed tree, not the package manager’s directory, when you can skip the install on a hit. Watch the file count above 100,000: 500,000 files took 15.7 seconds to restore. For an install of 11 seconds or more, the installed tree paid back once 17 to 31 per cent of runs hit it.

How long do a save and a restore take?

Bar chart. Median time to restore a directory with actions/cache on GitHub-hosted ubuntu-24.04, by size and number of files, in seconds (5 runs a cell). 50 MB in 100 files 3.0 seconds, 50 MB in 10,000 files 1.4 seconds, 50 MB in 100,000 files 2.9 seconds, 500 MB in 100 files 2.5 seconds, 500 MB in 10,000 files 2.0 seconds, 500 MB in 100,000 files 5.3 seconds, 500 MB in 500,000 files 15.7 seconds, 2,000 MB in 100 files 11.3 seconds, 2,000 MB in 100,000 files 5.9 seconds.50 MB in 100 files3.050 MB in 10,000 files1.450 MB in 100,000 files2.9500 MB in 100 files2.5500 MB in 10,000 files2.0500 MB in 100,000 files5.3500 MB in 500,000 files15.72,000 MB in 100 files11.32,000 MB in 100,000 files5.9
Median time to restore a directory with actions/cache on GitHub-hosted ubuntu-24.04, by size and number of files, in seconds (5 runs a cell). Data: run 44069031081 of studies/C2-cache-vs-rebuild.
Directory, MBNumber of filesStored MBSave, secondsRestore, seconds
50100112.2 (2.1 to 2.2)3.0 (2.3 to 3.3)
5010,000131.0 (0.9 to 2.2)1.4 (1.2 to 3.6)
50100,000212.2 (1.7 to 5.6)2.9 (2.3 to 5.7)
5001001614.0 (3.3 to 34.5)2.5 (2.2 to 4.7)
50010,0001214.2 (3.5 to 9.3)2.0 (1.8 to 2.9)
500100,0001374.7 (3.2 to 5.3)5.3 (3.0 to 7.7)
500500,0001797.7 (6.0 to 11.2)15.7 (8.4 to 19.5)
2,00010064710.9 (8.9 to 11.9)11.3 (5.7 to 12.6)
2,000100,0004956.5 (6.2 to 8.7)5.9 (5.6 to 10.8)

Each cell is five runs of the same directory: a generated tree of text files, saved, deleted, and restored with the operating system’s page cache emptied in between. The first column is the size before compression, the third the stored size, and the fourth and fifth the median with the lowest and highest run in brackets. The stored entry is smaller than the directory, about a fifth to two-fifths of it in these cells, and the entry is what travels.

Two things show. A restore of anything up to 161 MB stored and 100,000 files took a median of 1.4 to 5.3 seconds, so there is a floor of a second or two however small the cache is. And at the top of the range the file count shows on its own: 500 MB as 100,000 files restored in a median of 5.3 seconds and as 500,000 in 15.7. Between 100 and 100,000 files the cells show no steady cost for each file, so we do not quote one. The wide ranges are real too. One 500 MB save took 34.5 seconds against a median of 4.0, and a cache step you time once may be that run. Bytes cost as well: 647 MB stored took 11.3 seconds.

What does it come to for real projects?

ProjectPackage manager's directoryInstalled treeFresh installDirectory: save + restore + installHit rate to payTree: save + restore + checkHit rate to pay
npm, 5 direct dependencies30 MB, 891 files131 MB, 10,148 files5.2 (4.5 to 10.7)1.3 + 1.2 + 2.961%1.6 + 1.7 + 0.440%
npm, 760 packages182 MB, 1,345 files836 MB, 68,490 files16.2 (10.6 to 18.1)3.7 + 3.3 + 9.757%4.6 + 4.7 + 0.531%
pnpm126 MB, 8,991 files133 MB, 9,568 files0.9 (0.9 to 1.3)2.3 + 2.4 + 0.5never2.0 + 2.3 + 0.5never
pip33 MB, 129 files187 MB, 7,410 files13.4 (10.7 to 14.3)1.6 + 1.6 + 11.899%2.2 + 1.7 + 0.719%
Cargo build11 MB, 85 files285 MB, 474 files18.9 (17.4 to 23.6)1.4 + 1.7 + 11.724%2.8 + 3.2 + 0.417%
Go build52 MB, 695 files113 MB, 1,353 files11.0 (9.2 to 12.4)1.6 + 1.7 + 5.937%2.0 + 1.9 + 0.321%

Each project ran in one job on one runner, five times. A fresh install came first. Then the package manager’s own directory was saved, and the installed tree was saved. Everything was wiped and the page cache emptied. The directory was restored and an install run from it, then everything was wiped again and the tree restored and checked. The check loads the main packages for npm and pip. For Cargo and Go it is a build with nothing left to compile, so those two figures are the best case: a real change to your own source recompiles that part. The Hit rate to pay columns apply the formula above to the medians.

pnpm shows the floor. A fresh install took 0.9 seconds, and a restore alone took 2.3, so no hit rate makes a cache pay. pip shows the other trap: restoring its download directory saved nothing, because the install from it still took 11.8 seconds of the 13.4. Only the trees of the four longer installs gained about 9 seconds a hit or more: 8.8 to 15.3.

Should I cache the package manager’s directory or the installed tree?

The tree, if your build lets you skip the install on a hit. In all five projects where a cache paid at all it gained more seconds than the directory, and at a lower break-even: for the 760-package npm project, 4.7 seconds restored 836 MB and 68,490 files against 16.2 for a fresh install. Time is not the objection to caching node_modules: the restore above was fast. The catch is that npm’s documentation says npm ci removes a node_modules that is already there, so a restored tree only helps if the install step is skipped when the cache hits. It also ties the cache to the tool and runtime version, so put both in the key. Our data supports the tree up to the largest we measured, 68,490 files. It does not say where it stops: the grid says only that 500,000 files took 15.7 seconds to restore.

- id: tree
  uses: actions/cache@v6
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
- if: steps.tree.outputs.cache-hit != 'true'
  run: npm ci

That is the shape the study ran, with the key and the runtime version left for you to choose. The workflow with every step and timer is in the ci-measurements repository. For the keys, paths and the reasons a restore misses, the actions/cache reference has a tested recipe for each of 12 package managers.

How do I measure my own?

Put a timer either side of the restore, the install and the save, write them to the job summary, and compare a run that hits with a run that misses. Do it for a week of real runs, because the hit rate in the formula is yours and not ours.

- run: echo "T=$(date +%s%3N)" >> "$GITHUB_ENV"
- id: c
  uses: actions/cache/restore@v6
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
- run: |
    echo "restore: $(( $(date +%s%3N) - T )) ms, hit='${{ steps.c.outputs.cache-hit }}'" >> "$GITHUB_STEP_SUMMARY"
    echo "T=$(date +%s%3N)" >> "$GITHUB_ENV"
- run: npm ci
- run: |
    echo "install: $(( $(date +%s%3N) - T )) ms" >> "$GITHUB_STEP_SUMMARY"

What does a cache step cost on the bill?

On GitHub-hosted runners, time is billed by the job, with minutes and partial minutes rounded up to a whole minute, so shaving three seconds off a job changes the bill only if it crosses a minute boundary. Storage is the other cost: each repository has 10 GB of cache included, usage above that is measured as the peak in each hour, and the rate beyond it is $0.07 a GB-month. The cache limit post has the eviction rules, and the 429 post covers the request limits a busy matrix can hit. On our runners the Actions cache is included and not metered, as the caching documentation says, and the calculator prices the minutes that remain. For the other levers on the same minutes, see how to make GitHub Actions faster. Our page on a Docker layer cache for GitHub Actions says what survives between jobs and how it is metered.

Sources

Frequently asked questions

Is caching dependencies in GitHub Actions always faster?

No. A restore took a median of 1.4 to 5.3 seconds for entries up to 161 MB in our runs, and a save 1.0 to 4.7. A pnpm install took 0.9 seconds fresh and 2.3 seconds to restore, so the cache was slower.

Should I cache node_modules or the npm cache?

In our runs the installed tree gained more: 11.1 seconds against 3.1 for a 760-package project. But npm ci deletes node_modules, so skip the install on a hit and put the runtime version in the key.

How many files is too many for actions/cache?

We measured up to 500,000. Restoring 500 MB as 500,000 files took a median of 15.7 seconds against 5.3 for 100,000. The largest real tree we cached had 68,490 files and restored in 4.7 seconds.

At what hit rate does a cache pay?

When it is above (save + 0.4) divided by (gain + save + 0.4), in seconds. For installs of 11 to 19 seconds, caching the installed tree paid at 17 to 31 per cent. Caching npm's directory for the 760-package project needed 57 per cent.

Move your CI onto our runners with one line

Change one line, watch your own build, then decide.

Connect GitHub

Card required. You pay only for the minutes your jobs run.

.github/workflows/ci.yml
jobs: test:removed: runs-on: ubuntu-latestadded: runs-on: runnersio-4vcpu-ubuntu-2604 steps: - uses: actions/checkout@v4 - run: make testadded: build:added: runs-on: runnersio-32vcpu-ubuntu-2604