Skip to content

Home / Blog / Caching

GitHub Actions cache (actions/cache): inputs, keys for 12 ecosystems, why it missed

Every actions/cache, restore and save input and output, a cache key tested for 12 package managers on ubuntu-24.04, and a table of why a cache did not restore.

actions/cache saves the paths you name under a key and restores them when the key matches exactly, or by a prefix in restore-keys. The current release is v6.1.0, from 26 June 2026. We ran a key for each of 12 package managers on ubuntu-24.04: every one saved, hit exactly on its second run and fell back to its prefix when the lockfile changed. Four needed a key exclusion, because the install changed a file the key is hashed from. Our GitHub Actions cache guide has the full rules.

In short
  • actions/cache is at v6.1.0 (26 June 2026); restore and save are separate actions with smaller input sets of their own.
  • cache-hit is true on an exact match, false when a restore-keys prefix matched, and empty on a miss, so test for != 'true'.
  • We ran a key for 12 package managers on ubuntu-24.04: each missed, saved, hit exactly on its second run and fell back to its prefix after a lockfile change.
  • In Yarn, Gradle, Bundler and Composer the install changed a file the key is hashed from; excluding the install directories fixed it.
  • A table gives nine usual causes of a miss, and gh cache, the REST API or a workflow clears caches.

Which version of actions/cache is current?

v6, and its latest release is v6.1.0. GitHub’s README lists what changed in each major version: v4 integrated the action with the new cache service, v5 moved it to Node.js 24 and needs a runner of version 2.327.1 or later, and v6 updated the toolkit libraries and moved to ES modules. It lists no change to the inputs in any of them. The README also says the legacy cache service was sunset on 1 February 2025, recommends v4 or v3 as the versions to be on, and says that workflows using the deprecated versions fail.

One actions/cache step does two jobs. Its main step restores, and a post step saves when the job succeeds. Two more actions in the same repository split those jobs: actions/cache/restore only restores, and actions/cache/save only saves. The split is how you save from one job and restore in the others, and how you save a cache even when a later step fails.

What are the inputs and outputs?

InputWhich actionsDefaultWhat it does
keycache, restore, saverequiredThe key an entry is saved under and looked up by. Any mix of contexts, functions and literals; at most 512 characters, and a longer key fails the action.
pathcache, restore, saverequiredFiles, directories and glob patterns, one a line, absolute or relative to the workspace. It is part of the cache version, so a different list is a different cache.
restore-keyscache, restorenoneAn ordered list of key prefixes tried, in order, when key does not match. A prefix with several matches restores the most recently created.
enableCrossOsArchivecache, restore, savefalseLets a Windows runner save and restore caches that other operating systems can share.
fail-on-cache-misscache, restorefalseFails the step when no entry matches. Leave restore-keys empty to fail unless the primary key matched.
lookup-onlycache, restorefalseChecks that an entry exists and skips the download.
upload-chunk-sizecache, savenoneThe chunk size, in bytes, used to split large files on upload.
save-alwayscachefalseRuns the save even when an earlier step failed. Deprecated: the action says to use a separate restore step and a save step instead.

One environment variable matters when a restore hangs: SEGMENT_DOWNLOAD_TIMEOUT_MINS sets how long one segment of a download may take before the step gives up and the job carries on with a miss. It is 10 minutes unless you set it.

OutputWhich actionsValue
cache-hitcache, restoretrue on an exact match for the key; false when a restore-keys prefix matched; not set at all on a miss, so an empty string
cache-primary-keyrestoreThe key the restore step looked for, for the save step to reuse
cache-matched-keyrestoreThe key of the entry that was restored: the primary key, or the restore key's match

cache-hit has three values, and the README and the code disagree about the third. The restore README says it is false on a miss. The code does not set it on a miss at all, with a comment that this is deliberate, to keep existing behaviour. In our runs the output was empty on every miss, false when a restore-keys prefix matched, and true on an exact match. So test for != 'true' and never for == 'false'. A step guarded by the second would not run on a miss.

- uses: actions/cache@v6
  id: cache
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-
- run: npm ci
- if: steps.cache.outputs.cache-hit != 'true'
  run: echo "the cache was missing or only a prefix matched"

When should I use restore and save instead?

Use them when one job should write the cache and the rest only read it, or when the cache must be saved before a step that may fail. There is one trap. The single action remembers the key it looked up and saves under that key. The save action does not: it evaluates its key input when it runs, which is after your install. If the install changes a file the key is hashed from, the save lands under a different key from the one the next run looks for. GitHub’s README avoids this by saving under the restore step’s cache-primary-key output, and so should you.

- id: restore
  uses: actions/cache/restore@v6
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-
- run: npm ci
- if: steps.restore.outputs.cache-hit != 'true'
  uses: actions/cache/save@v6
  with:
    path: ~/.npm
    key: ${{ steps.restore.outputs.cache-primary-key }}

What is a cache key for each package manager?

Each row below was run, not copied. A first job on a fresh runner restored (a miss), installed and saved. A second job on another fresh runner restored with the same key, which had to be an exact hit or the job failed. A third changed the key’s input by one byte, and its restore had to find the first entry through restore-keys instead. Every row passed. The key in every row is ${{ runner.os }}-<name>-${{ hashFiles(<the files below>) }}, with the restore key ${{ runner.os }}-<name>-. The files are the project’s own lockfile. Several patterns in a cell are separate quoted arguments to hashFiles, as in hashFiles('**/yarn.lock', '!**/node_modules/**'), and the patterns that start with an exclamation mark are exclusions, explained in the next section under the second cause.

Package managerpathhashFiles patternsInstall step (simplified)
npm~/.npm**/package-lock.jsonnpm ci
pnpm~/.local/share/pnpm/store**/pnpm-lock.yamlpnpm install --frozen-lockfile
Yarn (classic)~/.cache/yarn**/yarn.lock, !**/node_modules/**yarn install --frozen-lockfile
pip~/.cache/pip**/requirements.txtpip install -r requirements.txt
Poetry~/.cache/pypoetry, ~/.cache/pip**/poetry.lockpoetry install --no-root
Gradle~/.gradle/caches, ~/.gradle/wrapper**/*.gradle*, **/gradle-wrapper.properties, !**/.gradle/**, !**/build/**./gradlew build
Maven~/.m2/repository**/pom.xmlmvn package
Cargo~/.cargo/registry/index/, ~/.cargo/registry/cache/, ~/.cargo/git/db/, target/**/Cargo.lockcargo build --locked
Go~/go/pkg/mod, ~/.cache/go-build**/go.sumgo build ./...
Bundlervendor/bundle**/Gemfile.lock, !vendor/**bundle install
NuGet~/.nuget/packages**/packages.lock.jsondotnet restore --locked-mode
Composer~/.cache/composer/files**/composer.lock, !vendor/**composer install

The restores were quick: 0.25 to 0.51 seconds on a miss, and 0.47 to 4.73 seconds on an exact hit for caches from 4 MB (Composer) to 320 MB (Cargo, with target/). The timings are single runs, in the repository’s results folder, and the break-even post has the repeated ones. For Bundler, GitHub’s own examples recommend the bundler-cache: true option of ruby/setup-ruby in preference to caching by hand; our row is the by-hand version, with vendor/bundle and Ruby installed by ruby/setup-ruby. Cargo’s row caches the build directory as well as the registry, and the sccache post measures what that is worth for a Rust workspace.

Why did my cache not restore?

Read the restore step’s log first. It prints a line that says what happened, and which line it is tells you which half of this section you are in. “Cache not found for input keys” lists the key and every restore key it tried: nothing matched, so the cause is the key or where the entry lives. “Cache restored from key” with a key that is not your primary key means a restore-keys prefix matched, and the cache is only the closest older one. Neither line means the step never reached the lookup: it was skipped, the event is not tied to a branch or tag, or the options changed what it prints, as lookup-only and fail-on-cache-miss do.

CauseWhat you seeWhat to change
The lockfile changedCache not found for input keys: followed by your key and each restore keyExpected. Add a restore-keys prefix so the most recent matching entry restores and the install only adds the difference; the restore then reports cache-hit as false.
The install changed a file the key is hashed fromA separate save step worked its key out after the install: Cache saved with key A, then on the next run Cache restored from key A with cache-hit false, or Cache not found for input keys B if there are no restore-keysLeave installed directories out of the pattern with an exclusion such as !**/node_modules/**, or save under the restore step's cache-primary-key output.
The pattern matches nothingA key that ends in a dash and never changeshashFiles returns an empty string when no file matches, so the key never changes, and an existing entry is never updated. Check the pattern against the real paths.
The path list or the operating system differsCache not found although the key is the sameThe cache version is a hash of the paths and the compression tool. Keep the path list identical in the saving and restoring steps, and note that a Windows entry is not a Linux entry.
Another branch saved itCache not found on a branch or pull request that ran after another's saveA run restores from its own branch and the default branch, and a pull request also from its base branch; never from a sibling. A pull request's entries are scoped to its merge ref. Save on the default branch.
The entry was evictedCache not found for a key that was savedAn entry not accessed for 7 days is removed, and over the repository limit the least recently accessed go first. See the cache limit post.
The cache service refused the requestCache service responded with 429, or a warning that you have hit a rate limitSave from one job and restore in the rest. See the 429 post.
The save never ranNo Cache saved line, or a warning containing cache write deniedThe post step runs only when the job succeeds, and a run from a fork pull request or another low-trust trigger has read-only access. Save with an explicit save step, and from a trusted trigger.
It hit, and the cache is out of dateCache hit occurred on the primary key, not saving cacheAn entry with an existing key is never updated. Use a key that changes every run with a restore-keys prefix, and watch the quota.

The second row is the one that is hard to see, because the cache is saved and the next run misses with nothing wrong in either log. The install writes into a directory under the workspace, such as node_modules, vendor or .gradle, and some of what it installs ships a lockfile of its own. A pattern such as **/yarn.lock then matches those files too, because hashFiles reads every match under the workspace. In our runs the hash was different after the install for Yarn, Gradle, Bundler and Composer, because node_modules, vendor or the .gradle directory the build writes into the project held a matching file. A single actions/cache step is safe, because, as its code shows, its save reads the key the restore looked up from the job’s state (our runs used the restore and save pair, not the single step). A separate save step that works the key out again is not: in the first version of our workflow (run 44064259012) the second job of those four recipes found no exact hit, and restored only through restore-keys. The recipe table above excludes the install directories in those four, and in the later run (run 44069031081) the hash was the same before and after the install in all 12.

How do I clear GitHub Actions caches?

There are four ways. In the web interface, which a person with write access to the repository can use, open the repository’s Actions tab, choose Caches under Management, and delete an entry with the button at the right of its row. From a terminal, gh cache lists and deletes by key, by ID or by ref. Through the REST API, which needs a token with the repo scope, one call deletes every entry that matches a complete key, and another deletes one by ID. Or a workflow does it for you, which is what stops pull requests from filling the 10 GB with entries only they can read.

# what is there, newest first, with its size
gh cache list --sort created_at --json id,key,ref,sizeInBytes

# one entry, by key or by ID
gh cache delete Linux-npm-3f8a…
gh cache delete 1234567

# everything saved for one pull request's merge ref
gh cache delete --all --ref refs/pull/123/merge

# everything whose key starts with a prefix
gh cache list --key Linux-npm- --limit 1000 --json id -q '.[].id' | xargs -n1 gh cache delete

# through the REST API: every entry with a complete key, and one entry by ID
gh api -X DELETE "repos/OWNER/REPO/actions/caches?key=Linux-npm-3f8a…"
gh api -X DELETE repos/OWNER/REPO/actions/caches/1234567

To delete a pull request’s caches when it closes, GitHub’s documentation gives a workflow that lists up to 100 caches on the pull request’s merge ref and deletes each. It needs the actions: write permission, and it runs on pull_request with the type closed.

name: Delete the caches of a closed pull request
on:
  pull_request:
    types: [closed]
jobs:
  cleanup:
    runs-on: ubuntu-latest
    permissions:
      actions: write
    steps:
      - name: Cleanup
        run: |
          ids=$(gh cache list --ref "$BRANCH" --limit 100 --json id --jq '.[].id')
          set +e
          for id in $ids; do gh cache delete "$id"; done
        env:
          GH_TOKEN: ${{ github.token }}
          GH_REPO: ${{ github.repository }}
          BRANCH: refs/pull/${{ github.event.pull_request.number }}/merge

Does this change on runners.io?

No workflow changes. actions/cache, the restore and save actions and the cache: input of the setup actions all work as written on our runners. See the Actions cache documentation for how a job reaches the cache and how an owner turns it off, and the post on how it works for the detail. Our page on a Docker layer cache for GitHub Actions says what survives between jobs and how it is metered.

Sources

Frequently asked questions

What is the latest version of actions/cache?

v6.1.0, released on 26 June 2026. GitHub's README lists v4 as integrating the new cache service, v5 as moving to Node.js 24 with a runner of 2.327.1 or later, and v6 as updating the toolkit libraries and moving to ES modules.

What does cache-hit return when there is no cache?

Nothing: the output is not set, so it is an empty string. It is true on an exact key match and false when a restore-keys prefix matched, so test for != 'true' and never for == 'false'.

How do I clear a GitHub Actions cache?

Delete it in the repository's Actions tab under Caches, with gh cache delete by key or ID, through the REST API, or from a workflow. The command gh cache delete --all --ref refs/pull/NUMBER/merge removes one pull request's caches.

Why does my cache save but never restore?

Check whether the key is worked out after the install. If a file that hashFiles reads, such as one inside node_modules, vendor or .gradle, changes during the install, the key differs by the next run. Exclude those directories, or save under the restore step's cache-primary-key.

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