Pinning the Package Manager with Corepack

Corepack is the tool that turns the packageManager field in package.json from documentation into enforcement. With it enabled, typing pnpm or yarn in a repository runs exactly the version that repository declares — downloaded, verified and cached on first use — regardless of what is installed globally. This guide walks through enabling Corepack, pinning a version with an integrity hash, using it in CI and Docker, and what to do on Node.js versions that no longer bundle it.

The problem Corepack solves

Without a pinned package manager, the version that writes your lockfile is whatever each contributor happens to have installed. The symptoms are lockfile churn and CI failures unrelated to the change under review:

$ git diff --stat
 pnpm-lock.yaml | 1873 +++++++++++++++++-------------------
 1 file changed, 912 insertions(+), 961 deletions(-)
# ...the pull request only added one dependency

 ERR_PNPM_BAD_PM_VERSION  This project is configured to use v9.15.4 of pnpm. Your current pnpm is v10.4.1

The second message is actually good news — it is pnpm itself noticing the packageManager field and refusing to run the wrong version. Corepack goes one step further and simply runs the right one. The wider rationale is covered in Package Manager Version Management.

How Corepack works

Corepack installs small executables named pnpm, pnpx, yarn and yarnpkg (and optionally npm) into the same directory as node. When you run one, the shim looks for the nearest package.json with a packageManager field, resolves the named version, downloads it into ~/.cache/node/corepack if needed, verifies it, and executes it with your arguments.

If no packageManager field is found, Corepack falls back to a default "known good" version for that tool, which it may update over time. That fallback is convenient outside repositories but is exactly the drift you want to avoid inside one — so always declare the field.

Enabling Corepack and pinning a version

# Once per Node.js installation (repeat after installing a new Node.js version)
corepack enable

# Pin the version for this repository; writes packageManager with a sha512 hash
corepack use pnpm@9.15.4

# Or pin the latest release of a major
corepack use pnpm@9

The resulting field:

{
  "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
}

The +sha512. suffix is optional but recommended. With it, Corepack refuses any download whose hash differs — protection against a compromised mirror or a tampered cache. Without it, Corepack still verifies the npm registry signature of the tarball.

Useful companion commands:

corepack install          # pre-download the declared version (for offline or Docker layers)
corepack pack             # write the declared version to a tarball for air-gapped installs
corepack up               # move packageManager to the latest release of the same major
COREPACK_ENABLE_STRICT=0 pnpm --version   # allow running a different tool than declared

Using it in CI and Docker

Most CI setups can read the field directly, without Corepack:

- uses: pnpm/action-setup@v4        # no "version" input: reads packageManager
- uses: actions/setup-node@v4
  with:
    node-version-file: .nvmrc
    cache: pnpm
- run: pnpm install --frozen-lockfile

Where you prefer Corepack itself — for Yarn, or in a custom runner image:

- uses: actions/setup-node@v4
  with: { node-version-file: .nvmrc }
- run: corepack enable
- run: pnpm install --frozen-lockfile

In Docker, enable Corepack and pre-download the version in a layer that depends only on package.json, so it is cached across builds:

FROM node:22-slim
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
RUN corepack enable && corepack install
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm run build

Node.js 25 and later: Corepack is no longer bundled

Corepack shipped with Node.js from 14.19 and 16.9 through the 24.x line, disabled by default. The Node.js project decided to stop distributing it from Node.js 25 onward. The packageManager field and the Corepack tool continue to work; you install Corepack yourself:

npm install -g corepack@latest
corepack enable

In CI, add that step before corepack enable, or rely on setup actions that read packageManager directly. Nothing in your repository changes — which is the point of declaring the version in package.json rather than in machine setup.

Worked example: ending lockfile churn in a twelve-person team

A team sees pnpm-lock.yaml rewritten in roughly one pull request in five, always with hundreds of lines of changes unrelated to the pull request's purpose. pnpm --version across the team shows four different versions from 8.15 to 9.12. They run corepack use pnpm@9.12.3, commit the field, ask everyone to run corepack enable, and change CI to read the field instead of a hard-coded version: 8 input that had been left behind. One pull request regenerates the lockfile with the pinned version. Over the next month, lockfile diffs contain only the changes each pull request intended. Later upgrades go through Renovate, which bumps the field and regenerates the lockfile in a dedicated pull request.

Corepack's security model

Pinning the package manager is also a supply-chain control, and it is worth understanding what Corepack does and does not protect against. When Corepack downloads a package manager tarball from the npm registry, it verifies the registry's ECDSA signature using public keys bundled with Corepack itself. A tarball that was altered after publishing — on a mirror, a proxy or in a cache — fails that check. If the packageManager field includes a +sha512 hash, Corepack also compares the tarball's hash with the pinned value, which protects against a legitimately signed but different release being substituted: for example, if a version number were ever republished or a malicious release were signed with a stolen key.

What Corepack cannot do is judge whether the version you pinned is itself trustworthy. That decision belongs in review: upgrade the package manager through a pull request, read the release notes for majors, and prefer versions that have been public for a few days over brand-new releases. Together with lockfile integrity checks and install-script restrictions, a pinned and hashed package manager closes one of the few remaining paths by which unreviewed code runs on every developer machine and CI runner.

Monorepos and nested projects

Corepack looks for the nearest package.json with a packageManager field, walking up from the current directory. In a workspace, only the root should declare it, so running pnpm from inside packages/ui walks up to the root and gets the right version. Trouble appears when a nested folder that is not part of the workspace — an example project, a documentation site with its own install, a test fixture — declares a different package manager. Running commands inside it switches tools, which is correct for that folder but surprising if someone expected the root version. Keep such folders out of the workspace globs, give them their own explicit packageManager field, and document how they are installed.

The opposite problem occurs with fixture projects created on the fly, such as the temporary consumers used in tarball smoke tests. If they are created inside the repository, Corepack finds the root declaration and may refuse to run npm there under strict mode. Create fixtures outside the repository, or set COREPACK_ENABLE_STRICT=0 for those commands.

Troubleshooting

pnpm: command not found after enabling. The shims are installed next to node. If you use a version manager, enable Corepack for each Node.js version it manages, or let the manager handle shims.

A global pnpm still wins. If command -v pnpm points somewhere other than the Node.js bin directory, a global install earlier on PATH shadows the shim. Uninstall it or reorder PATH.

Signature verification errors. Older Corepack versions ship with the npm registry's old signing keys and fail after key rotations. Update Corepack; see Fixing Corepack Signature Verification Errors.

Behind a proxy or private registry. Set COREPACK_NPM_REGISTRY to your registry mirror so downloads go through it, and provide auth with COREPACK_NPM_TOKEN if needed.

Prevention and CI/CD guardrails

• Declare packageManager with a hash in every repository.
• Never hard-code package manager versions in CI files; read the declaration.
• Add engines.<pm> and engine-strict=true as a second line of defence for machines without Corepack.
• Upgrade via dedicated pull requests, ideally opened by your dependency bot.

Frequently Asked Questions

Does Corepack manage npm too? It can, but not by default: corepack enable npm installs an npm shim as well. Most teams let npm come with Node.js and use Corepack for pnpm and Yarn.

Is the packageManager field used by consumers of my library? No. It only affects commands run inside your repository. Published packages keep the field, but installs of your package ignore it.

Can I use Corepack with Yarn Berry's checked-in releases? Yes, and it replaces them: with packageManager set, the .yarn/releases file and yarnPath setting are unnecessary.

Related

• Package Manager Version Management explains the complete version-management setup.
• Fixing Corepack Signature Verification Errors covers the most common Corepack failure.
• Enforcing a Single Package Manager with only-allow blocks the wrong tool entirely.
• Fixing pnpm ERR_PNPM_OUTDATED_LOCKFILE in CI shows a failure that version pinning prevents.

← Package Manager Version Management