pnpm/action-setup: the step order setup-node needs, and one store cache

By Kaveh Alemi·Latchkey

pnpm/action-setup installs pnpm and puts it on PATH; it does not install Node.js, and since v4.3.0 it can cache the pnpm store itself. The order that works is checkout, then pnpm/action-setup, then actions/setup-node with cache: pnpm, because setup-node asks pnpm for its store path and fails if pnpm is not installed yet.

Most pnpm workflows have three setup steps and one install, and most of the failures come from the order of the first three or from two of them disagreeing about a version. The action reads package.json before it installs anything, setup-node runs pnpm store path before it restores anything, and both can cache the same store with different keys.

The version comes from one of two places, the version input or packageManager in package.json, and setting both to strings that differ fails the step even when they agree on semver. Set neither and you get no pnpm version is specified, which has its own page.

Seven inputs, and an undeclared cache-hit

Seven inputs and two declared outputs. The restore step also sets a third output, cache-hit, which action.yml does not declare; it is true only when the exact key matched.

Which pnpm version gets installed

With version empty, the action reads devEngines.packageManager first and packageManager second, stripping any +sha512 suffix. With version set and packageManager also present, it compares the two as plain strings and throws Multiple versions of pnpm specified: when they differ. That comparison is not semver: version: 12 against "packageManager": "pnpm@12.18.0" throws, even though 12.18.0 satisfies 12. Pick one source.

The install itself is a bootstrap pnpm from a lockfile committed in the action, followed by pnpm self-update to your version. For pnpm 11 and earlier, the action also checks the node on PATH and installs the standalone @pnpm/exe when that Node is older than 22.13, whatever standalone says. pnpm 12 ships a native executable and needs no Node at all.

      # package.json carries "packageManager": "pnpm@12.18.0"
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6.1.1
        # no version input: the manifest decides

The step order, and why it is fixed

Checkout comes first whenever the version lives in package.json, because the action reads the file from the workspace and a missing file is silently treated as no version at all. pnpm/action-setup comes before setup-node whenever setup-node has cache: pnpm: setup-node finds the store with pnpm store path --silent, and without pnpm on PATH it stops with Unable to locate executable file: pnpm. A setup-node maintainer closed the report of that error as expected behavior, since pnpm must be installed before the setup-node step.

Keep the install as its own step after setup-node rather than using run_install. run_install runs inside the pnpm/action-setup step, so it runs before any later setup-node and uses whichever Node happened to be on PATH at that moment.

steps:
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
  - uses: pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6.1.1
  - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
    with:
      node-version: 24
      cache: pnpm
  - run: pnpm install --frozen-lockfile
  - run: pnpm test

Two caches for one store: keep one

Both actions cache the directory pnpm store path prints, and both hash pnpm-lock.yaml by default. They differ in the fallback and in the cleanup. setup-node passes no restore keys, so a lockfile change restores nothing. pnpm/action-setup passes a prefix restore key, so a lockfile change restores the previous store and pnpm downloads only the difference.

The README says the post step prunes the store for you. In the source it runs pnpm store prune only when run_install was set; with a separate install step it logs Pruning is unnecessary. and saves the store unpruned. Turning both caches on uploads the same directory twice under two keys.

One more reason the version matters for caching: the store path contains the store layout version, and an earlier bootstrap pnpm reported a different path from the one your pnpm wrote to, which broke both caches on a cold run. The action now self-updates to your version before asking for the path, and its source names issue #233 as the reason.

run_install, when you do want it

It accepts true (a recursive install), one object, or a list of objects, each with recursive, cwd and args. It is a convenience: a separate step after setup-node does the same work with the Node you chose, and the action exports PNPM_HOME either way, so global installs work in both places.

  - uses: pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6.1.1
    with:
      run_install: |
        - recursive: true
          args: [--frozen-lockfile]
        - args: [--global, prettier]

From v2 to pnpm 12 support

v2 stopped working with newer Node.js versions, and the README tells anyone on it to upgrade. For pnpm 11 and later, the same maintainers also publish pnpm/setup, which installs pnpm and a JavaScript runtime in one step; pnpm/action-setup still supports pnpm 12 alongside setup-node.

Key takeaways

• Checkout, then pnpm/action-setup, then setup-node with cache: pnpm, then the install.
• Set the version in package.json or in version, not both: the two are compared as strings.
• The action's own cache falls back to the previous store; setup-node's does not.
• The post step prunes the store only when run_install was used.

Frequently asked questions

Related guides

References

• pnpm/action-setup README and action.yml at v6.1.1 (read 2026-11-12)
• pnpm/action-setup src/install-pnpm/run.ts: version resolution
• actions/setup-node advanced usage: caching pnpm
• actions/setup-node#530: Unable to locate executable file: pnpm
• pnpm/action-setup#105: comparison with corepack
• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation