How do I cache dependencies in GitHub Actions to speed up builds?

Turn on the cache option in your setup action, or use actions/cache with a key built from your lockfile hash. Cache the package manager download store, not the installed dependency directory, and check the logs for real cache hits.

Last updated 2026-11-16

To cache dependencies in GitHub Actions, turn on the cache input of your language's setup action (actions/setup-node, actions/setup-python, actions/setup-java) or add actions/cache with a key built from hashFiles() on your lockfile. Cache the package manager's download store, such as ~/.npm, the pnpm store, ~/.cache/pip, ~/.m2/repository, or ~/.cargo/registry, then run your normal install command. When the lockfile doesn't change, the install reads packages from the restored cache instead of the network. When it changes, the key changes and a fresh cache is saved.

If your jobs run on Depot GitHub Actions runners, the same workflow steps automatically use Depot Cache as the cache backend. You don't change the YAML.

Use the cache option in setup actions first

Most setup actions can cache dependencies for you. They pick the right directory and build the key from your lockfile, so this is the least configuration you can write.

Node.js with npm, pnpm, or Yarn

name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7

      - uses: pnpm/action-setup@v6
        with:
          version: 10

      - uses: actions/setup-node@v7
        with:
          node-version-file: '.nvmrc'
          cache: 'pnpm'
          cache-dependency-path: 'pnpm-lock.yaml'

      - run: pnpm install --frozen-lockfile
      - run: pnpm test

Set cache to npm, pnpm, or yarn. For pnpm, install pnpm with pnpm/action-setup before actions/setup-node so the setup action can find the pnpm store. Use the install command that refuses to change the lockfile: npm ci, pnpm install --frozen-lockfile, or yarn install --immutable.

In a monorepo with several lockfiles, list every lockfile that should invalidate the cache in cache-dependency-path.

Python with pip

- uses: actions/setup-python@v7
  with:
    python-version: '3.12'
    cache: 'pip'
    cache-dependency-path: |
      requirements.txt
      requirements-dev.txt

- run: pip install -r requirements.txt -r requirements-dev.txt

By default, actions/setup-python keys the pip cache on requirements.txt or pyproject.toml. Set cache-dependency-path when your dependencies live in other files, such as requirements-dev.txt.

Go

- uses: actions/setup-go@v7
  with:
    go-version-file: 'go.mod'
    cache-dependency-path: 'go.sum'

- run: go test ./...

actions/setup-go caches the module cache and the build cache by default, keyed on go.mod. The example sets cache-dependency-path so the key follows go.sum, which changes whenever a dependency does. Set cache: false if you want to manage caching yourself.

Java with Maven or Gradle

For Maven, use the cache input of actions/setup-java:

- uses: actions/setup-java@v6
  with:
    distribution: 'temurin'
    java-version: '21'
    cache: 'maven'

- run: ./mvnw --batch-mode verify

For Gradle, actions/setup-java also accepts cache: 'gradle'. If you want more control over what's saved, use gradle/actions/setup-gradle instead. It caches Gradle's dependency and wrapper downloads without extra configuration:

- uses: actions/setup-java@v6
  with:
    distribution: 'temurin'
    java-version: '21'

- uses: gradle/actions/setup-gradle@v6

- run: ./gradlew build

Don't enable both cache: 'gradle' on actions/setup-java and gradle/actions/setup-gradle in the same job. Pick one so that only one action saves the Gradle cache.

Use actions/cache when you need control

Use actions/cache when your toolchain has no setup action with caching, or when you need a custom key or path. This example caches the Cargo registry and Git dependencies for a Rust project:

jobs:
  test:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7

      - uses: actions/cache@v6
        with:
          path: |
            ~/.cargo/registry/index
            ~/.cargo/registry/cache
            ~/.cargo/git/db
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: |
            ${{ runner.os }}-cargo-

      - run: cargo test --locked

How the key works:

  • key is an exact match. hashFiles('**/Cargo.lock') changes whenever any lockfile changes, so a dependency update creates a new cache entry instead of reusing a stale one.
  • Include runner.os and anything else that changes the cached files, such as the architecture, language version, or package manager version. A cache built on Linux is not useful on macOS.
  • restore-keys is a list of prefixes to fall back to when there's no exact match. The most recent entry that matches the prefix is restored, so the install only downloads what changed since then. After the job succeeds, actions/cache saves a new entry under the exact key.

When there's an exact hit, actions/cache doesn't save again, because an entry with that key already exists. Entries are immutable. To force a fresh cache, change the key, for example by adding a version string such as v2- to the prefix.

Restore in every job, save in one

When several jobs need the same dependencies, you can split restore and save with actions/cache/restore and actions/cache/save. This keeps pull request jobs from writing extra entries and makes one job responsible for updating the cache:

- uses: actions/cache/restore@v6
  id: deps
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

- run: npm ci

- if: github.ref == 'refs/heads/main' && steps.deps.outputs.cache-hit != 'true'
  uses: actions/cache/save@v6
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}

What to cache and what not to cache

Cache the package manager's download store. Avoid caching the installed dependency directory unless you've measured that it helps.

EcosystemCache thisUsually skip
npm~/.npmnode_modules
pnpmthe pnpm store (pnpm store path)node_modules
pip~/.cache/pipthe virtual environment
Maven~/.m2/repositorytarget/
Gradle~/.gradle/caches, ~/.gradle/wrapperbuild/
Gomodule cache and build cache (go env GOMODCACHE GOCACHE)
Cargo~/.cargo/registry, ~/.cargo/git/dbtarget/ in large projects

Why skip node_modules? It contains platform-specific binaries and post-install output that depend on the Node.js version and operating system. A restored node_modules that doesn't exactly match the lockfile can hide dependency problems, and npm ci deletes node_modules before installing anyway. A clean install from a warm download store skips the network for unchanged packages and always matches the lockfile.

Caching node_modules or a virtual environment can make sense when installs run heavy post-install scripts. If you do it, include the lockfile hash, the runtime version, and the operating system in the key, and don't use restore-keys for that path, so a partial match is never treated as a complete install.

Build output, such as compiled TypeScript, test results, or bundler output, is a different problem from dependencies. For that, use the build tool's own remote cache. See the best way to cache large TypeScript monorepo builds and remote caching for a polyglot monorepo. Docker layers have their own answer too: see sharing a Docker layer cache across GitHub Actions jobs.

Cache size, eviction, and new branches

GitHub limits the total cache size per repository and evicts entries that haven't been accessed recently. Check the current limits in GitHub's dependency caching reference. Large caches cost time twice: once to upload when saving, and again to download on every restore. Keep each entry to the directories that save install time.

GitHub also scopes caches by branch. A workflow run can restore caches created on its own branch and on the default branch, and a pull request can also restore caches from its base branch. It can't restore caches from sibling branches. So the first run on a new branch has no cache of its own and falls back to the default branch cache.

Two habits keep this predictable:

  • Run the workflow on pushes to the default branch, so there's always a recent cache that new branches can restore.
  • Check the setup action or actions/cache log for "Cache restored from key" on a warm run. If every run reports a miss, the key likely includes something that changes on every run, such as a timestamp or github.sha.

Use Depot Cache with Depot GitHub Actions runners

Depot GitHub Actions runners replace the machine your jobs run on. GitHub still schedules the workflow. Change the runner label:

 jobs:
   test:
-    runs-on: ubuntu-24.04
+    runs-on: depot-ubuntu-24.04

On these runners, any action that uses the GitHub Actions cache API automatically uses Depot Cache instead of the standard GitHub Actions cache. That includes actions/cache and the cache option in actions/setup-node, actions/setup-python, and actions/setup-java. Every workflow in this guide works unchanged.

A few behaviors differ from the standard GitHub Actions cache:

  • Depot Cache scopes entries by repository but doesn't isolate them by branch. A new branch can restore entries saved from any branch in the same repository, and your cache key decides how entries are shared.
  • Retention is set per organization: 7, 14, or 30 days, and a size limit from 25 GB to 500 GB, or no limit. The default is 14 days with no size limit.
  • Storage is billed per GB above the amount included in your plan. The Depot Cache pricing docs explain how usage is calculated.

The runners also come pre-configured to use Depot Cache as a remote cache for build tools. For example, Go builds use GOCACHEPROG, Gradle gets an init.gradle file with the connection details, and Turborepo gets a TURBO_API environment variable. See the Depot Cache integrations for Bazel, Maven, Nx, Pants, sccache, and others. A remote build cache skips repeated compile and test work, which dependency caching can't do.

Depot Cache in Depot CI

Depot CI is a separate product. It runs GitHub Actions YAML on Depot's own orchestration and compute instead of on GitHub Actions. Depot Cache is built in with no configuration required.

Depot CI also supports cache disks, currently in beta. A cache disk is a durable filesystem you mount into a job with the depot/cache-mount action. Package and build caches stay on the disk between runs, without the upload, download, and restore-key steps that actions/cache needs. A disk is shared by name across your Depot organization, not scoped to one repository, so don't store secrets or untrusted output on it.

If you're deciding between the two products, see Depot CI vs. Depot GitHub Actions runners.

A checklist

  1. Turn on the cache input of your setup action, or add actions/cache with a hashFiles() key on the lockfile.
  2. Cache the download store, not node_modules or a virtual environment, unless you've measured a benefit.
  3. Add restore-keys for download stores so a lockfile change restores most of the previous cache.
  4. Run the workflow on the default branch so new branches have a cache to fall back to.
  5. Confirm cache hits in the logs on a second run.
  6. For compile and test output, add a build tool remote cache.

For a full Node.js workflow that combines dependency caching with remote build caching, test sharding, and runner sizing, see how to speed up Node.js builds in GitHub Actions.

Start building with Depot
in minutes