actions/setup-node

Install a specific Node.js version and cache your npm, yarn, or pnpm dependencies.

Official actionCategory: Language & Toolchain SetupLatest v4View on GitHub

What it does

actions/setup-node installs a chosen Node.js version and puts it on PATH. Its cache input is the simplest way to cache dependency downloads without a separate actions/cache step.

Set node-version explicitly (or read it from a file) so builds are reproducible instead of tracking whatever the runner image ships.

Usage

workflow (.yml)

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: 20
      cache: 'npm'   # requires a committed package-lock.json
  - run: npm ci

Inputs

Input	Description	Default	Required
`node-version`	Version spec, e.g. 20, 20.x, or lts/*.	-	No
`node-version-file`	Read the version from a file such as .nvmrc or package.json.	-	No
`cache`	Package manager to cache: npm, yarn, or pnpm.	-	No
`cache-dependency-path`	Path(s) to the lockfile used for the cache key.	`auto`	No
`registry-url`	Registry to configure for publishing.	-	No
`check-latest`	Always resolve the latest matching version.	`false`	No

Outputs

Output	Description
`node-version`	The version that was installed.
`cache-hit`	true if an exact dependency cache was restored.

Notes

The cache input needs a lockfile to compute the cache key. Commit package-lock.json, yarn.lock, or pnpm-lock.yaml.

For pnpm, run pnpm/action-setup before setup-node so the pnpm binary exists when the cache is restored.

Common errors

Error: Dependencies lock file is not found means cache is set but no lockfile was found. Commit a lockfile or point cache-dependency-path at it.
A version like node-version: 20.11 that is not on the runner triggers a download; use a broad spec like 20 or lts/* to avoid brittle pins.

Security and pinning

Pin setup-node to a commit SHA. Tags like v4 are mutable.
When using registry-url to publish, pass the token via NODE_AUTH_TOKEN from a secret, never inline.

Frequently asked questions

Do I still need actions/cache with setup-node?

No. The cache input covers dependency caching for npm, yarn, and pnpm. Use actions/cache only for extra paths like build output.

How do I cache pnpm?

Run pnpm/action-setup first, then set cache: pnpm on setup-node so the pnpm store is cached.

References

GitHub Actions documentation