Cache Nix Store

A GitHub Action to restore and save Nix store paths using GitHub Actions cache.

This action is based on actions/cache.

Additional actions

• Restore action
• Save action

Features

• Restore and save the Nix store on Linux and macOS runners.
• Restore and save other directories on Linux, macOS, and Windows runners.
• Collect garbage in the Nix store before saving a new cache.
• Merge caches produced by several jobs.
• Purge caches created or last accessed at least the given time ago.

A typical job

Note

Inputs are given for reference. All available inputs are specified below.

1. The nix-quick-install-action installs Nix in single-user mode.

2. Restore phase:

   Note

   For a cache to be restored in the current step, paths used to create that cache must be the same as the paths specified in the current step.

   1. The cache-nix-action tries to restore a cache whose key is the same as the specified one (inputs: primary-key, paths).

   2. When it can't restore, the cache-nix-action tries to restore a cache whose key matches a prefix in a given list of key prefixes (inputs: restore-prefixes-first-match, paths).

   3. The cache-nix-action restores all caches whose keys match some of the prefixes in another given list of key prefixes (inputs: restore-prefixes-all-matches, paths).

3. Other job steps run.

4. Post Restore phase:

   1. The cache-nix-action purges caches whose keys are the same as the primary key and that were created or last accessed more than a given time ago (inputs: purge, purge-created, purge-last-accessed, purge-primary-key).

   2. When there's no cache whose key is the same as the primary key, the cache-nix-action collects garbage in the Nix store and saves a new cache (inputs: save, gc-max-store-size, gc-max-store-size-linux, gc-max-store-size-macos).

   3. The cache-nix-action purges caches whose keys match some of the given prefixes in a given list of key prefixes and that were created or last accessed more than a given time ago relative to the start of the Post Restore phase (purge, purge-prefixes, purge-created, purge-last-accessed, purge-primary-key).

Limitations

• Uses experimental nix commands like nix store gc and nix path-info.
• By default, the action caches and restores only /nix, ~/.cache/nix, ~root/.cache/nix (see documentation for the paths input).
  • The action doesn't automatically cache stores specified via the --store flag (link).
  • When restoring a cache, the action doesn't extract from the cache the /nix/store paths that already exist on the runner.
  • Additionally, the action unarchives only the /nix/var/nix/db/db.sqlite and skips other cached /nix/var directories.
  • The action merges existing and new databases when restoring a cache.
• The action requires nix-quick-install-action.
• The action supports only Linux and macOS runners for Nix store caching.
• The action purges caches scoped to the current GITHUB_REF.
• The action purges caches by keys without considering cache versions (see Cache version).
• GitHub allows only 10GB of caches and then removes the least recently used entries (see its eviction policy). Workarounds:
  • Purge old caches
  • Merge caches
• The Nix store size is limited by a runner storage size (link). Workarounds:
  • Ubuntu, macOS, Windows:
    • hugoalh/disk-space-optimizer-ghaction
  • Ubuntu, macOS:
    • wimpysworld/nothing-but-nix
  • Ubuntu:
    • jlumbroso/free-disk-space
    • endersonmenezes/free-disk-space
    • easimon/maximize-build-space
    • AdityaGarg8/remove-unwanted-software,gmij/max-build-space
    • firus-v/free-disk-space
    • coder-xiaomo/free-disk-space
    • data-intuitive/reclaim-the-bytes
    • laverdet/remove-bloatware
    • xd009642/ci-hoover
    • justinthelaw/maximize-github-runner-space
  • macOS:
    • comment
• Caches are isolated for restoring between refs (link).
  • Workaround: provide caches for PRs on default or base branches.
• Garbage collection by default evicts flake inputs (issue).
  • Workaround: save the flake closure as an installable (link).

Comparison with alternative approaches

See Caching Approaches.

Examples

Single step for restore and save

Note

For purging, the workflow or the job must have the permission actions: write.

Note

If the paths input is specified, the action will be able to restore only caches created with the same paths.

- uses: nixbuild/nix-quick-install-action@v30
  with:
    nix_conf: |
      keep-env-derivations = true
      keep-outputs = true

- name: Restore and save Nix store
  uses: nix-community/cache-nix-action@v6
  with:
    # restore and save a cache using this key
    primary-key: nix-${{ runner.os }}-${{ hashFiles('**/*.nix', '**/flake.lock') }}
    # if there's no cache hit, restore a cache by this prefix
    restore-prefixes-first-match: nix-${{ runner.os }}-
    # collect garbage until the Nix store size (in bytes) is at most this number
    # before trying to save a new cache
    # 1G = 1073741824
    gc-max-store-size-linux: 1G
    # do purge caches
    purge: true
    # purge all versions of the cache
    purge-prefixes: nix-${{ runner.os }}-
    # created more than this number of seconds ago
    purge-created: 0
    # or, last accessed more than this number of seconds ago
    # relative to the start of the `Post Restore and save Nix store` phase
    purge-last-accessed: 0
    # except any version with the key that is the same as the `primary-key`
    purge-primary-key: never

• nix-quick-install-action writes the supplied nix_conf to nix.conf (see action.yml, script).
• nix-quick-install-action enables flakes and accepts nixConfig from flake.nix (see script).
• Due to gc-max-store-size-linux: 1G, on Linux runners, garbage in the Nix store is collected until the store size reaches 1GB or until there's no garbage to collect.
• Since gc-max-store-size-macos isn't set to a number, on macOS runners, no garbage is collected in the Nix store.
• At the end of the job, and before trying to save a new cache, the cache-nix-action purges caches:
  • (with the key prefix nix-${{ runner.os }}-) AND (created more than 0 seconds ago OR last accessed more than 0 seconds ago).

Separate steps for restore and save

See Always save cache.

Other examples

See Merge caches, Example cache workflow, Caching Strategies.

Example workflow

See ci.yaml and its runs.

Troubleshooting

• Use action-tmate to connect to the runner via SSH.
• Use action-debug-vscode to run a browser VSCode on the runner.

Configuration

See action.yml.

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.	true	""
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.	false	""
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). Otherwise, this input has no effect.	false	""
skip-restore-on-hit-primary-key	When true, when there's a hit on the primary-key, the action doesn't restore the found cache. Otherwise, the action restores the cache.	false	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.	false	""
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.	false	true
save	When true, the action can save a cache with the primary-key. Otherwise, the action can't save a cache.	false	true
paths	When nix: true, the action uses ["/nix", "~/.cache/nix", "~root/.cache/nix"] as default paths, as suggested here. 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 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.	false	""
paths-macos	Overrides paths. Can have an effect only when the action runs on a macOS runner.	false	""
paths-linux	Overrides paths. Can have an effect only when the action runs on a Linux runner.	false	""
backend	Choose an implementation of the cache package. When actions, use the actions version from here. When buildjet, use the BuildJet version from here.	false	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.	false	""
gc-max-store-size-macos	Overrides gc-max-store-size. Can have an effect only when the action runs on a macOS runner.	false	""
gc-max-store-size-linux	Overrides gc-max-store-size. Can have an effect only when the action runs on a Linux runner.	false	""
purge	When true, the action purges (possibly zero) caches. The action purges only caches scoped to the current GITHUB_REF. Otherwise, this input has no effect.	false	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.	false	""
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.	false	""
purge-last-accessed	Can have an effect only when purge: true. When a non-negative number, the action purges selected caches that were last accessed more than this number of seconds ago relative to the start of the Post Restore phase. Otherwise, this input has no effect.	false	""
purge-created	Can have an effect only when purge: true. When a non-negative number, the action purges selected caches that were created more than this number of seconds ago relative to the start of the Post Restore phase. Otherwise, this input has no effect.	false	""
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).	false	""
token	The action uses it to communicate with GitHub API. If you use a personal access token, it must have the repo scope (link).	false	${{ 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"].

Purge old caches

The cache-nix-action allows to delete old caches after saving a new cache (see purge-* inputs in Inputs and the compare-run-times job in the Example workflow).

The purge-cache action allows to remove caches based on their last accessed or created time without branch limitations.

Alternatively, you can use the GitHub Actions Cache API.

Merge caches

GitHub evicts the least recently used caches when their total size exceeds 10GB (see Limitations).

If you have multiple similar caches produced on runners with the same OS (Linux or macOS), you can merge them into a single cache and store just it to save space.

In short:

1. Matrix jobs produce similar individual caches.
2. The next job restores all of these individual caches, saves a common cache, and purges individual caches.
3. On subsequent runs, matrix jobs use the common cache.

See the make-similar-caches and merge-similar-caches jobs in the example workflow.

Pros: if N individual caches are very similar, a common cache will take approximately N times less space. Cons: if caches aren't very similar, the run time may increase due to a bigger common cache.

Garbage collection

When restoring a Nix store from a cache, the store may contain old unnecessary paths. These paths should be removed sometimes to limit cache size and ensure the fastest restore/save steps.

Garbage collection approach 1

Produce a cache once, use it multiple times. Don't collect garbage.

Advantages:

• Unnecessary paths are saved to a cache only during a new save.

Disadvantages:

• Unnecessary paths can accumulate between new saves.
  • A job at the firs run produces a path A and saves a cache.
  • The job at the second run restores the cache, produces a path B, and saves a cache. The cache has both A and B.
  • etc.

Garbage collection approach 2

Collect garbage before saving a cache.

Advantages:

• Automatically keep cache at a minimal/limited size

Disadvantages:

• No standard way to gc only old paths.

Garbage collection tools

• GC by atime: nix-heuristic-gc.
• GC via gc roots: nix-cache-cut.
• GC based on time: cache-gc.
• Visualize GC roots: nix-du.

Save Nix store paths from garbage collection

Issues

• issue
• issue

Sample flake

See examples/saveFromGC/flake.nix and saveFromGC.nix.

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    flake-utils = {
      url = "github:numtide/flake-utils";
      inputs.systems.follows = "systems";
    };
    cache-nix-action = {
      url = "github:nix-community/cache-nix-action";
      flake = false;
    };
    systems.url = "github:nix-systems/default";
  };
  outputs =
    inputs:
    inputs.flake-utils.lib.eachDefaultSystem (
      system:
      let
        pkgs = inputs.nixpkgs.legacyPackages.${system};

        packages = {
          hello = pkgs.hello;

          inherit
            (import "${inputs.cache-nix-action}/saveFromGC.nix" {
              inherit pkgs inputs;
              inputsExclude = [
                # the systems input will still be saved
                # because flake-utils needs it
                inputs.systems
              ];
              derivations = [
                packages.hello
                devShells.default
              ];
              paths = [ "${packages.hello}/bin/hello" ];
            })
            saveFromGC
            ;
        };

        devShells.default = pkgs.mkShell { buildInputs = [ pkgs.gcc ]; };
      in
      {
        inherit packages devShells;
      }
    );
}

nix profile install or nix build

Each profile is a garbage collection root.

Each nix build result symlink is a garbage collection root.

To save particular Nix store paths, create an installable that contains these paths and

• add it to a profile via nix profile install or
• nix build it

The saveFromGC attribute of the flake above is a script (an installable) that contains paths of elements of the flake closure (the flake itself, flake inputs, inputs of these inputs, etc.).

Enter the examples/saveFromGC directory.

cd examples/saveFromGC

Print the contents of saveFromGC.

cat $(nix build .#saveFromGC --no-link --print-out-paths)/bin/save-from-gc

closure
/nix/store/pj0rhk7zkfx82xsighf72v8x4rqldzgi-source
/nix/store/01x5k4nlxcpyd85nnr0b9gm89rm8ff4x-source
/nix/store/97hxap05brgklr57xh7qaab6s833rfg0-source
/nix/store/yj1wxm9hh8610iyzqnz75kvs6xl8j3my-source

derivations
/nix/store/p09fxxwkdj69hk4mgddk4r3nassiryzc-hello-2.12.1
/nix/store/54zp3xb1qgzy14pd7hi9spjxss437jwr-nix-shell

paths
/nix/store/p09fxxwkdj69hk4mgddk4r3nassiryzc-hello-2.12.1/bin/hello

Add the installable to the default profile.

nix profile remove examples/saveFromGC
nix profile install .#saveFromGC
nix profile list | grep save-from-gc

Store paths:        /nix/store/bgd1sgyc8wy1i3msh0p2g1yl0iywp7ys-save-from-gc

Or, build the installable and see the garbage collection roots that won't let it be garbage collected.

nix-store --query --roots $(nix build .#saveFromGC --print-out-paths)

nix-store --query --roots result

Output (edited):

...
<...>/.local/state/nix/profiles/profile-1-link -> /nix/store/pyvyymji6pvgify5gvnlvprlrxi42pdd-profile
<...>/cache-nix-action/examples/saveFromGC/result -> /nix/store/bgd1sgyc8wy1i3msh0p2g1yl0iywp7ys-save-from-gc

Other approaches

• Run direnv in background.

Caching approaches

Initially discussed here and here.

Caching approaches work at different "distances" from /nix/store of GitHub Actions runner. These distances affect the restore and save speed.

GitHub Actions

• DeterminateSystems/magic-nix-cache-action
• nix-community/cache-nix-action

cache-nix-action

Pros:

• Free.
• Easy to set up.
• Uses GitHub Actions Cache and works fast.
• Doesn't require repository secrets.
• Allows to save a store of at most a given size (see Inputs).
• Allows to save outputs from garbage collection (see Garbage collection).
• When there's a cache hit, restoring from a GitHub Actions cache can be faster than downloading multiple paths from binary caches.
  • You can compare run times of jobs with and without store caching in Actions.
    • Open a run and click on the time under Total duration.

Cons: see Limitations

magic-nix-cache-action

Pros (link):

• Free.
• Easy to set up.
• Uses GitHub Actions Cache and works fast.
• Restores and saves paths selectively.

Cons:

• Collects telemetry (link)
• May trigger rate limit errors (link).
• Follows the GitHub Actions Cache semantics (link).
  • Caches are isolated between branches (link).
• Saves a cache for each path in a store and quickly litters Caches.

FlakeHub Cache

Pros (link):

• Free for one month with a coupon code (link).
• Easy to set up.

Cons:

• Not free (link)

actions/cache

If used with nix-quick-install-action, it's similar to the cache-nix-action.

If used with install-nix-action and a chroot local store:

Pros:

• Quick restore and save /tmp/nix.

Cons:

• Slow nix copy from /tmp/nix to /nix/store.

If used with install-nix-action and this trick, it's similar to the cache-nix-action, but slower (link).

Hosted binary caches

See binary cache, HTTP Binary Cache Store.

• cachix
• attic

Pros:

• Restore and save paths selectively.
• Provide least recently used garbage collection strategies (cachix, attic).
• Don't cache paths available from the NixOS cache (cachix).
• Allow to share paths between projects (cachix).

Cons:

• Have limited free storage (cachix gives 5GB for open-source projects).
• Need good bandwidth for receiving and pushing paths over the Internet.
• Can be down.

Contribute

• Clone the repository.

  git clone --recurse-submodules https://github.com/nix-community/cache-nix-action
  

• Improve README.

• Report errors, suggest improvements in issues.

• Improve code.

  • Read about JavaScript actions
  • See main files:
    • restoreImpl.ts
    • saveImpl.ts

• Improve docs.

  • Edit action.nix.

  • Update action.yml-s and README.md-s:

    nix run .#write
    

• Update deps:

  • Update the actions-toolkit branch that contains a patched version of actions/toolkit.
  • Update the buildjet-toolkit branch that contains a patched version of BuildJet/toolkit synchronized with actions/toolkit.
  • Update submodules for the mentioned branches on the main branch.

Cache action (legacy description updated for the cache-nix-action)

This action allows caching dependencies and build outputs to improve workflow execution time.

Two other actions are available in addition to the primary cache action:

• Restore action
• Save action

Documentation

See "Caching dependencies to speed up workflows".

What's New

⚠️ Important changes

The cache backend service has been rewritten from the ground up for improved performance and reliability. actions/cache now integrates with the new cache service (v2) APIs.

The new service will gradually roll out as of February 1st, 2025. The legacy service will also be sunset on the same date. Changes in these release are fully backward compatible.

We are deprecating some versions of this action. We recommend upgrading to version v4 or v3 as soon as possible before February 1st, 2025. (Upgrade instructions below).

If you are using pinned SHAs, please use the SHAs of versions v4.2.0 or v3.4.0

If you do not upgrade, all workflow runs using any of the deprecated actions/cache will fail.

Upgrading to the recommended versions will not break your workflows.

Read more about the change & access the migration guide: reference to the announcement.

v4

• Integrated with the new cache service (v2) APIs.
• Updated to node 20

v3

• Integrated with the new cache service (v2) APIs.
• Added support for caching in GHES 3.5+.
• Fixed download issue for files > 2GB during restore.
• Updated the minimum runner version support from node 12 -> node 16.
• Fixed avoiding empty cache save when no files are available for caching.
• Fixed tar creation error while trying to create tar with path as ~/ home folder on ubuntu-latest.
• Fixed zstd failing on amazon linux 2.0 runners.
• Fixed cache not working with github workspace directory or current directory.
• Fixed the download stuck problem by introducing a timeout of 1 hour for cache downloads.
• Fix zstd not working for windows on gnu tar in issues.
• Allowing users to provide a custom timeout as input for aborting download of a cache segment using an environment variable SEGMENT_DOWNLOAD_TIMEOUT_MINS. Default is 10 minutes.
• New actions are available for granular control over caches - restore and save.
• Support cross-os caching as an opt-in feature. See Cross OS caching for more info.
• Added option to fail job on cache miss. See Exit workflow on cache miss for more info.
• Fix zstd not being used after zstd version upgrade to 1.5.4 on hosted runners
• Added option to lookup cache without downloading it.
• Reduced segment size to 128MB and segment timeout to 10 minutes to fail fast in case the cache download is stuck.

See the v2 README.md for older updates.

Usage

Pre-requisites

Create a workflow .yml file in your repository's .github/workflows directory. An example workflow is available below. For more information, see the GitHub Help Documentation for Creating a workflow file.

If you are using this inside a container, a POSIX-compliant tar needs to be included and accessible from the execution path.

If you are using a self-hosted Windows runner, GNU tar and zstd are required for Cross-OS caching to work. They are also recommended to be installed in general so the performance is on par with hosted Windows runners.

Environment Variables

• SEGMENT_DOWNLOAD_TIMEOUT_MINS - Segment download timeout (in minutes, default 10) to abort download of the segment if not completed in the defined number of minutes. Read more

Cache scopes

The cache is scoped to the key, version, and branch. The default branch cache is available to other branches.

See Matching a cache key for more info.

Example cache workflow

Restoring and saving cache using a single action

name: Caching Primes

on: push

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Cache Primes
        id: cache-primes
        uses: nix-community/cache-nix-action@v6
        with:
          primary-key: ${{ runner.os }}-primes
          paths: prime-numbers

      - name: Generate Prime Numbers
        if: steps.cache-primes.outputs.hit-primary-key != 'true'
        run: /generate-primes.sh -d prime-numbers

      - name: Use Prime Numbers
        run: /primes.sh -d prime-numbers

The cache-nix-action provides the hit-primary-key output which is set to 'true' when the cache is restored using the primary-key and 'false' otherwise.

Using a combination of restore and save actions

Note

The paths input in the cache-nix-action/restore and cache-nix-action/save must be the same.

name: Caching Primes

on: push

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Restore cached Primes
        id: cache-primes-restore
        uses: nix-community/cache-nix-action/restore@v6
        with:
          primary-key: ${{ runner.os }}-primes
          paths: |
            path/to/dependencies
            some/other/dependencies

      # other steps

      - name: Save Primes
        id: cache-primes-save
        uses: nix-community/cache-nix-action/save@v6
        with:
          primary-key: ${{ steps.cache-primes-restore.outputs.cache-primary-key }}
          paths: |
            path/to/dependencies
            some/other/dependencies

Note

You must use the cache or restore action in your workflow before you need to use the files that might be restored from the cache. If the provided primary-key matches an existing cache, a new cache is not created and if the provided primary-key doesn't match an existing cache, a new cache is automatically created provided the job completes successfully.

Caching Strategies

With the introduction of the restore and save actions, a lot of caching use cases can now be achieved. Please see the caching strategies document for understanding how you can use the actions strategically to achieve the desired goal.

Implementation Examples

Every programming language and framework has its own way of caching.

See Examples for a list of nix-community/cache-nix-action implementations for use with:

• Bun
• C# - NuGet
• Clojure - Lein Deps
• D - DUB
• Deno
• Elixir - Mix
• Go - Modules
• Haskell - Cabal
• Haskell - Stack
• Java - Gradle
• Java - Maven
• Node - npm
• Node - Lerna
• Node - Yarn
• OCaml/Reason - esy
• PHP - Composer
• Python - pip
• Python - pipenv
• R - renv
• Ruby - Bundler
• Rust - Cargo
• Scala - SBT
• Swift, Objective-C - Carthage
• Swift, Objective-C - CocoaPods
• Swift - Swift Package Manager
• Swift - Mint

Creating a cache key

A cache key can include any of the contexts, functions, literals, and operators supported by GitHub Actions.

For example, using the hashFiles function allows you to create a new cache when dependencies change.

- uses: nix-community/cache-nix-action@v6
  with:
    primary-key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
    paths: |
      path/to/dependencies
      some/other/dependencies

Additionally, you can use arbitrary command output in a cache key, such as a date or software version:

# http://man7.org/linux/man-pages/man1/date.1.html
- name: Get Date
  id: get-date
  run: echo "date=$(/bin/date -u "+%Y%m%d")" >> $GITHUB_OUTPUT
  shell: bash

- uses: nix-community/cache-nix-action@v6
  with:
    primary-key: ${{ runner.os }}-${{ steps.get-date.outputs.date }}-${{ hashFiles('**/lockfiles') }}
    paths: path/to/dependencies

See Using contexts to create cache keys

Cache Limits

A repository can have up to 10GB of caches. Once the 10GB limit is reached, older caches will be evicted based on when the cache was last accessed.

Caches that are not accessed within the last week will also be evicted.

Skipping steps based on hit-primary-key

Using the hit-primary-key output, subsequent steps (such as install or build) can be skipped when a cache hit occurs on the key.

It is recommended to install missing/updated dependencies in case of a partial key match when the key is dependent on the hash of the package file.

Example:

steps:
  - uses: actions/checkout@v4

  - uses: nix-community/cache-nix-action@v6
    id: cache
    with:
      primary-key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
      paths: path/to/dependencies

  - name: Install Dependencies
    if: steps.cache.outputs.hit-primary-key != 'true'
    run: /install.sh

Note

The id defined in nix-community/cache-nix-action must match the [id] in the if statement (i.e. steps.[id].outputs.hit-primary-key)

Cache Version

Cache version is a hash generated for a combination of compression tool used (Gzip, Zstd, etc. based on the runner OS) and the paths of directories being cached. If two caches have different versions, they are identified as unique caches while matching. This, for example, means that a cache created on a windows-latest runner can't be restored on ubuntu-latest as cache Versions are different.

Pro tip: The list caches API can be used to get the version of a cache. This can be helpful to troubleshoot cache miss due to version.

Example

The workflow will create 3 unique caches with same keys. Ubuntu and Windows runners will use different compression technique and hence create two different caches. And build-linux will create two different caches as the paths are different.

jobs:
  build-linux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Cache Primes
        id: cache-primes
        uses: nix-community/cache-nix-action@v6
        with:
          primary-key: primes
          paths: prime-numbers

      - name: Generate Prime Numbers
        if: steps.cache-primes.outputs.hit-primary-key != 'true'
        run: ./generate-primes.sh -d prime-numbers

      - name: Cache Numbers
        id: cache-numbers
        uses: nix-community/cache-nix-action@v6
        with:
          primary-key: primes
          paths: numbers

      - name: Generate Numbers
        if: steps.cache-numbers.outputs.hit-primary-key != 'true'
        run: ./generate-primes.sh -d numbers

  build-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4

      - name: Cache Primes
        id: cache-primes
        uses: nix-community/cache-nix-action@v6
        with:
          primary-key: primes
          paths: prime-numbers

      - name: Generate Prime Numbers
        if: steps.cache-primes.outputs.hit-primary-key != 'true'
        run: ./generate-primes -d prime-numbers

Known practices and workarounds

There are a number of community practices/workarounds to fulfill specific requirements. You may choose to use them if they suit your use case. Note these are not necessarily the only solution or even a recommended solution.

• Cache segment restore timeout
• Update a cache
• Use cache across feature branches
• Cross OS cache
• Force deletion of caches overriding default cache eviction policy

Windows environment variables

Please note that Windows environment variables (like %LocalAppData%) will NOT be expanded by this action. Instead, prefer using ~ in your paths which will expand to the HOME directory. For example, instead of %LocalAppData%, use ~\AppData\Local. For a list of supported default environment variables, see the Learn GitHub Actions: Variables page.

Contributing

We would love for you to contribute to nix-community/cache-nix-action. Pull requests are welcome! Please see the CONTRIBUTING.md for more information.

License

The scripts and documentation in this project are released under the MIT License