nix-community/Restore and save Nix Store
Restore and save Nix store using GitHub Actions cache to speed up workflows.
View on GitHubTrust Signals
- Scorecard Score
- not yet scored
- Maintenance Recency
- Activelast commit May 21, 2026
- License
- MIT
Pinned Snippet
uses: nix-community/cache-nix-action@7df957e333c1e5da7721f60227dbba6d06080569 # v7tags can be moved; commit SHAs can't. why a SHA?
Inputs
| name | description | required | default |
|---|---|---|---|
| primary-key | - When a non-empty string, the action uses this key for restoring and saving a cache. - Otherwise, the action fails. | yes | — |
| restore-prefixes-first-match | - When a newline-separated non-empty list of non-empty key prefixes, when there's a miss on the `primary-key`, the action searches in this list for the first prefix for which there exists a cache whose key has this prefix, and the action tries to restore that cache. - Otherwise, this input has no effect. | — | "" |
| restore-prefixes-all-matches | - When a newline-separated non-empty list of non-empty key prefixes, when there's a miss on the `primary-key`, the action tries to restore all caches whose keys have these prefixes. - Tries caches across all refs to make use of caches created on the current, base, and default branches (see [docs](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache)). - Otherwise, this input has no effect. | — | "" |
| lookup-only | - When `true`, when there's a hit on the `primary-key`, the action doesn't restore any cache. - Otherwise, the action can restore caches. - Doesn't change the behavior of cache saving in any case. | — | false |
| fail-on | - Input form: `<key type>.<result>`. - `<key type>` options: `primary-key`, `first-match`. - `<result>` options: `miss`, `not-restored`. - When the input satisfies the input form, when the event described in the input happens, the action fails. - Example: - Input: `primary-key.not-restored`. - Event: a cache could not be restored via the `primary-key`. - Otherwise, this input has no effect. | — | "" |
| nix | - Can have an effect only when the action runs on a `Linux` or a `macOS` runner. - When `true`, the action can do Nix-specific things. - Otherwise, the action doesn't do them. | — | true |
| save | - When `true`, the action can save a cache with the `primary-key`. - Otherwise, the action can't save a cache. | — | true |
| paths | - When `nix: true`, the action uses `["/nix"]` as default paths. - Otherwise, the action uses an empty list as default paths. - When a newline-separated non-empty list of non-empty path patterns (see [`@actions/glob`](https://github.com/actions/toolkit/tree/main/packages/glob) for supported patterns), the action appends it to default paths and uses the resulting list for restoring and saving caches. - Otherwise, the action uses default paths for restoring and saving caches. | — | "" |
| paths-macos | - Overrides `paths`. - Can have an effect only when the action runs on a `macOS` runner. | — | "" |
| paths-linux | - Overrides `paths`. - Can have an effect only when the action runs on a `Linux` runner. | — | "" |
| backend | Choose an implementation of the `cache` package. - When `actions`, use the [actions version](https://github.com/actions/toolkit/tree/main/packages/cache) from [here](https://github.com/nix-community/cache-nix-action/tree/actions-toolkit/packages/cache). - When `buildjet`, use the [BuildJet version](https://github.com/BuildJet/toolkit/tree/main/packages/cache-buildjet) from [here](https://github.com/nix-community/cache-nix-action/tree/buildjet-toolkit/packages/cache). | no | actions |
| gc-max-store-size | - Can have an effect only when `nix: true`, `save: true`. - The input has no effect if "primary-key" hit occurs when starting to save the new cache. - When a non-negative integer number (possibly with a suffix), the action collects garbage (via `nix store gc --max ...`) until the Nix store size (in bytes) is at most this number just before the action tries to save a new cache. - If you specify a suffix, it must be `K` (kibibytes, 2 ^ 10 bytes), `M` (mebibytes, 2 ^ 20 bytes) or `G` (gibibytes, 2 ^ 30 bytes), where `2 ^ N` means `2 to the power N`. Examples: `5G` (same as `5368709120`), `20M` (same as `20971520`). - Otherwise, this input has no effect. | — | "" |
| gc-max-store-size-macos | - Overrides `gc-max-store-size`. - Can have an effect only when the action runs on a `macOS` runner. | — | "" |
| gc-max-store-size-linux | - Overrides `gc-max-store-size`. - Can have an effect only when the action runs on a `Linux` runner. | — | "" |
| purge | - When `true`, the action purges (possibly zero) caches. - The action purges only caches scoped to the current [GITHUB_REF](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables). - Otherwise, this input has no effect. | — | false |
| purge-primary-key | - Can have an effect only when `purge: true`. - When `always`, the action always purges the cache with the `primary-key`. - When `never`, the action never purges the cache with the `primary-key`. - Otherwise, this input has no effect. | — | "" |
| purge-prefixes | - Can have an effect only when `purge: true`. - When a newline-separated non-empty list of non-empty cache key prefixes, the action selects for purging all caches whose keys match some of these prefixes. - Otherwise, this input has no effect. | — | "" |
| purge-last-accessed | - Can have an effect only when `purge: true`. - When a non-negative number or a string in the [ISO 8601 duration format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#iso_8601_duration_format), the action purges selected caches that were last accessed more than this number of seconds or this duration before the start of the `Post Restore` phase. Examples: `0` (0 seconds), `P1DT12H` (1 day and 12 hours). - Otherwise, this input has no effect. | — | "" |
| purge-created | - Can have an effect only when `purge: true`. - When a non-negative number or a string in the [ISO 8601 duration format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#iso_8601_duration_format), the action purges selected caches that were created more than this number of seconds or this duration before the start of the `Post Restore` phase. Examples: `0` (0 seconds), `P1DT12H` (1 day and 12 hours). - Otherwise, this input has no effect. | — | "" |
| upload-chunk-size | - When a non-negative number, the action uses it as the chunk size (in bytes) to split up large files during upload. - Otherwise, the action uses the default value `33554432` (32MB). | — | "" |
| token | - The action uses it to communicate with GitHub API. - If you use a personal access token, it must have the `repo` scope ([link](https://docs.github.com/en/rest/actions/cache?apiVersion=2022-11-28#delete-github-actions-caches-for-a-repository-using-a-cache-key)). | — | ${{ github.token }} |
Outputs
| name | description |
|---|---|
| primary-key | - A string. - The `primary-key`. |
| hit | - A boolean string. - `'true'` when `hit-primary-key` is `true` or `hit-first-match` is `true`. - `'false'` otherwise. |
| hit-primary-key | - A boolean string. - `'true'` when there was a hit on the `primary-key`. - `'false'` otherwise. |
| hit-first-match | - A boolean string. - `'true'` when there was a hit on a key matching `restore-prefixes-first-match`. - `'false'` otherwise. |
| restored-key | - A string. - The key of a cache restored via the `primary-key` or via the `restore-prefixes-first-match`. - An empty string otherwise. |
| restored-keys | - A possibly empty array of strings (JSON). - Keys of restored caches. - Example: `["key1", "key2"]`. |