---
title: "Cache dependencies in GitHub Actions, the right way"
description: "Stop reinstalling packages on every CI run. How to cache npm, pnpm, pip, cargo, Go, and Gradle dependencies in GitHub Actions, with copyable YAML."
url: https://starsling.dev/best-practices/github-actions/cache-dependencies
canonicalUrl: https://starsling.dev/best-practices/github-actions/cache-dependencies
---

# Cache dependencies in GitHub Actions

Best practice: Caching & Setup. Last updated: 2026-07-16

Cache your package manager's downloads so CI restores dependencies from a keyed cache instead of reinstalling them from scratch on every run.

## Table of contents

- [Do this](#do-this)
- [Avoid this](#avoid-this)
- [Seen in the wild](#seen-in-the-wild)
- [Shipped by StarSling](#shipped-by-starsling)
- [Why it matters](#why-it-matters)
- [When to use](#when-to-use)
- [Verify on your repo](#verify)
- [Sources](#sources)

<a id="do-this"></a>

## Do this

The setup action (or an explicit `actions/cache` step) restores the dependency store keyed on the lockfile. When the lockfile is unchanged, the install is a fast cache restore instead of a full network download and rebuild. Most ecosystems have a first-class hook: `cache:` on `actions/setup-node` (npm, pnpm, yarn), `actions/setup-python` (pip, pipenv, poetry), `actions/setup-go` (the module and build caches), and `actions/setup-java` (maven, gradle). Set that input explicitly rather than relying on a default: `actions/setup-node` v5 began auto-caching when it detected a package manager, and v6 narrowed that to npm only (and only when `package.json` names npm in `packageManager` or `devEngines.packageManager`), so a pnpm or yarn repo that never sets `cache:` gets no cache at all. Cargo has no built-in hook, so key an `actions/cache` step on `Cargo.lock` yourself.

_Cache keyed on the lockfile, per ecosystem_

```yaml
# Take the block for your ecosystem. Each one keys the cache on the lockfile,
# so an unchanged lockfile restores instead of reinstalling.
steps:
  - uses: actions/checkout@v7

  # Node (npm / pnpm / yarn): setup-node caches the package manager's store.
  # From setup-node v6, only npm is cached automatically (and only when
  # package.json names npm in "packageManager"). pnpm and yarn still need
  # this explicit cache: input.
  - uses: pnpm/action-setup@v6
    with:
      version: 10   # required unless package.json sets "packageManager"
  - uses: actions/setup-node@v6
    with:
      node-version: 22
      cache: pnpm                  # keyed on pnpm-lock.yaml
  - run: pnpm install --frozen-lockfile

  # Python: setup-python caches the pip download cache
  - uses: actions/setup-python@v6
    with:
      python-version: "3.13"
      cache: pip                   # keyed on requirements.txt

  # Go: setup-go caches the module + build cache, keyed on go.sum
  - uses: actions/setup-go@v6
    with:
      go-version: "1.24"
      cache: true

  # Java: setup-java caches the Gradle or Maven dependency store
  - uses: actions/setup-java@v5
    with:
      distribution: temurin
      java-version: "21"
      cache: gradle                # or: maven

  # Rust: no built-in hook. Cache the resolved registry and the build dir, keyed on
  # Cargo.lock. Copy actions/cache's Rust example and note the two traps.
  - uses: actions/cache@v6
    with:
      # Not the whole ~/.cargo/registry: registry/src and git/checkouts are unpacked
      # from the cached archives, so caching them stores the same bytes twice.
      path: |
        ~/.cargo/bin/
        ~/.cargo/registry/index/
        ~/.cargo/registry/cache/
        ~/.cargo/git/db/
        target/
      key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
      # NO restore-keys here, deliberately. A prefix fallback restores a target/ built
      # against a DIFFERENT Cargo.lock, then saves it again under the new key: the stale
      # artifacts never get evicted and the cache grows without bound. A cache miss on a
      # dependency change is the correct outcome.
```

<a id="avoid-this"></a>

## Avoid this

Every run pays the full install cost, and it multiplies across every matrix leg and shard.

_No cache: full install every run_

```yaml
steps:
  - uses: actions/checkout@v7
  - uses: pnpm/action-setup@v6
    with:
      version: 10   # required unless package.json sets "packageManager"
  - uses: actions/setup-node@v6
    with:
      node-version: 22       # no cache: key, and setup-node never auto-caches
                             # pnpm, so nothing is restored
  - run: pnpm install        # re-downloads every dependency, every run
```

<a id="seen-in-the-wild"></a>

## Seen in the wild

Django, Infisical, and Immich restore package-manager or browser caches before install and browser setup, so dependency downloads and Playwright installs are reused instead of repeated.

### Infisical/infisical - .github/workflows/validate-db-schemas.yml

```yaml
              with:
                  node-version: "22"
                  cache: "npm"
                  cache-dependency-path: backend/package-lock.json
```

Key lines: `cache: "npm"`, `cache-dependency-path: backend/package-lock.json`.

A monorepo wrinkle the clean example above leaves out: cache-dependency-path tells setup-node which lockfile to key the cache on.

Source: [Infisical/infisical `.github/workflows/validate-db-schemas.yml` lines 34-37](https://github.com/Infisical/infisical/blob/931fe8fe6892b79cfbec472c289da93355139048/.github/workflows/validate-db-schemas.yml#L34-L37) at commit `931fe8f`.

### django/django - .github/workflows/python_matrix.yml

```yaml
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'
```

Key line: `cache: 'pip'`.

The same single line in Python, on the job that fans setup-python out across every supported version.

Source: [django/django `.github/workflows/python_matrix.yml` lines 46-50](https://github.com/django/django/blob/b34b834378adc590a771cccd44b9fb0b953cdca2/.github/workflows/python_matrix.yml#L46-L50) at commit `b34b834`.

### immich-app/immich - .github/workflows/test.yml

```yaml
      - name: Setup Node
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version-file: '.nvmrc'
          cache: 'pnpm'
```

Key line: `cache: 'pnpm'`.

The pnpm store, restored by setup-node and keyed on the lockfile, on the test job of a self-hosted photo app.

Source: [immich-app/immich `.github/workflows/test.yml` lines 413-417](https://github.com/immich-app/immich/blob/19313e75fd1860f7da56fd23dc9f3dabfe9478b6/.github/workflows/test.yml#L413-L417) at commit `19313e7`.

<a id="shipped-by-starsling"></a>

## Shipped by StarSling

On Better Auth, a StarSling agent stopped Playwright browsers from reinstalling on every E2E run by moving that setup into a reusable cached action.

### better-auth/better-auth#8073: chore(ci): optimize Playwright browser installs in E2E

StarSling added a composite setup-playwright action so E2E jobs reuse the Playwright browser install work instead of repeating it on every run.

Diff: .github/actions/setup-playwright/action.yml caches Chromium and installs system dependencies in one reusable action.

Source: [better-auth/better-auth#8073](https://github.com/better-auth/better-auth/pull/8073), merged 2026-02-20.
Customer story: [Better Auth](https://starsling.dev/customers/better-auth).

<a id="why-it-matters"></a>

## Why it matters

Reinstalling dependencies from scratch wastes minutes on every job, and the waste multiplies across every matrix leg and shard. The one caveat to size honestly: caching only helps runs whose lockfile is unchanged (most PRs, re-runs, and dependabot bumps aside), so measure your real cache-hit rate rather than assuming every run benefits. Building Docker images in the same pipeline? Layer caching is the container-side analog, covered in [Docker builds in GitHub Actions](/ci/docker).

<a id="when-to-use"></a>

## When to use

**Use it when:** Any job that installs dependencies with a lockfile, which is almost every build and test job.

**Be careful when:** Skip a cache only when installs are already trivial (a handful of packages) or when the cache key would change on nearly every run, so the restore never hits.

<a id="verify"></a>

## Verify on your repo

Hand this prompt to your coding agent to audit and fix this practice in your own repo:

Inspect this repo's .github/workflows for dependency caching. For every job that installs packages (npm, pnpm, yarn, pip, cargo, go, gradle, maven), check whether a cache is configured: a `cache:` key on `actions/setup-node` / `setup-python` / `setup-go`, an explicit `actions/cache` step, or a language-specific cache action. Flag any install step (`pnpm install`, `pip install`, `cargo build`, etc.) that has no matching cache restoring its store, and confirm the cache key is derived from the lockfile so it actually hits. Add the right cache hook keyed on the lockfile, then show me the diff and open a PR rather than applying it blindly.

Ground these changes in the upstream docs before you edit: https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching, https://github.com/actions/cache. If you cannot fetch them, say so rather than guessing, and cite what you used in the PR description.

Prefer to check by hand:

- Search your workflows for a cache hook: `grep -rn 'cache' .github/workflows/`, look for `cache:` on a setup action, `actions/cache`, or a language-specific cache action.
- Confirm the install command is present but no matching cache exists (e.g. `pnpm install` / `pip install` / `cargo build` with nothing restoring its store).
- Read a job log: a warm run should show a cache-restore line and a much shorter install step than a cold run.

<a id="more-best-practices"></a>

## More best practices for GitHub Actions

- [Use a shallow checkout with fetch-depth in GitHub Actions](https://starsling.dev/best-practices/github-actions/shallow-checkout)
- [Shard tests across parallel jobs in GitHub Actions](https://starsling.dev/best-practices/github-actions/shard-tests)
- [All CI best practices](https://starsling.dev/best-practices/github-actions)

<a id="faq"></a>

## FAQ

### Does `actions/cache` or the setup action's `cache:` option work better?

For the common ecosystems, the built-in `cache:` on `actions/setup-node`, `setup-python`, and `setup-go` is simplest, it picks a sensible key from your lockfile automatically. Reach for an explicit `actions/cache` step when you need to cache something the setup action doesn't cover, like a build cache or a browser-binary download.

### Why is my cache not speeding anything up?

Usually the cache key changes too often (so every run is a miss), or the cached path isn't where the tool actually reads from. Check the restore/miss lines in the job log and confirm the key is derived from the lockfile, not from something that changes each run.

### How do I cache pnpm in a monorepo or workspace?

Point `actions/setup-node` at the lockfiles with `cache-dependency-path: '**/pnpm-lock.yaml'` (a multi-line list of explicit paths works too). On its own, `cache:` only looks for that package manager's lockfile in the working-directory root, so in a workspace whose lockfiles live in sub-projects the step does not quietly mis-key the cache: it fails the job outright with `Dependencies lock file is not found`. `cache-dependency-path` is what points it at the lockfiles you actually have, and makes the key cover every one of them.

<a id="sources"></a>

## Sources

1. [GitHub Docs - caching dependencies to speed up workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching)
2. [actions/setup-node - built-in dependency caching](https://github.com/actions/setup-node)
3. [actions/cache](https://github.com/actions/cache)