Corepack: Managing Package Managers in Node.js

Every Node.js project depends on a package manager, but teams often run into problems when developers use different versions of npm, Yarn, or pnpm. One developer installs with pnpm 8, another uses pnpm 9, and suddenly the lockfile has conflicts. Corepack solves this by shipping with Node.js and transparently managing package manager versions for you.

What is Corepack?

Corepack is a tool bundled with Node.js (since v16.9) that acts as a bridge between your project and its package manager. Instead of globally installing Yarn or pnpm, you declare which package manager and version your project uses in package.json, and Corepack ensures everyone uses exactly that version.

{
  "name": "my-project",
  "packageManager": "pnpm@9.4.0"
}

When anyone runs pnpm install in this project, Corepack intercepts the command, downloads pnpm 9.4.0 if needed, and runs it. If they try to use a different package manager, Corepack blocks it.

Enabling Corepack

Corepack ships with Node.js but is disabled by default. Enable it once:

corepack enable

This creates shim scripts for yarn and pnpm in your Node.js bin directory. From now on, when you run yarn or pnpm, Corepack intercepts the call.

To enable it only for specific package managers:

corepack enable pnpm
corepack enable yarn

Setting up your project

Add the packageManager field to your package.json:

# Automatically set to the latest stable version
corepack use pnpm@latest

# Or set a specific version
corepack use yarn@4.1.0

This updates package.json:

{
  "name": "my-api",
  "version": "1.0.0",
  "packageManager": "pnpm@9.4.0+sha512.f549b8228d235c3..."
}

The hash after the + is a SHA-512 integrity hash that ensures the exact binary is verified when downloaded. This prevents supply chain attacks where a compromised registry serves a tampered package manager.

How version enforcement works

Once packageManager is set, Corepack enforces it:

# Project uses pnpm@9.4.0
$ npm install
Usage Error: This project is configured to use pnpm

$ yarn install
Usage Error: This project is configured to use pnpm

$ pnpm install
# Works — uses exactly pnpm@9.4.0

If a developer has a different version of pnpm installed globally, Corepack ignores it and uses the version specified in package.json. This eliminates “works on my machine” issues caused by version mismatches.

Using Corepack with Yarn

Yarn benefits the most from Corepack because Yarn 2+ (Berry) is architecturally different from Yarn Classic (1.x). Without Corepack, switching between them is painful.

# Set up Yarn Berry
corepack use yarn@4.1.0

# Now yarn commands use Yarn 4
yarn install
yarn add express

Corepack handles downloading the right Yarn binary transparently. You do not need to run yarn set version or manage .yarnrc.yml for the version itself.

Using Corepack with pnpm

pnpm is the most common Corepack use case because pnpm is not bundled with Node.js like npm is:

# Before Corepack
npm install -g pnpm  # Different version per developer

# With Corepack
corepack use pnpm@9.4.0  # Same version for everyone

After setup, new developers only need to:

1. Clone the repository
2. Run corepack enable
3. Run pnpm install

Corepack downloads the correct pnpm version automatically on the first run.

CI/CD integration

GitHub Actions

name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: corepack enable

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Run tests
        run: pnpm test

The actions/setup-node action supports Corepack natively. It reads packageManager from package.json and sets up the correct version.

GitLab CI

build:
  image: node:22
  before_script:
    - corepack enable
  script:
    - pnpm install --frozen-lockfile
    - pnpm test

Docker

FROM node:22-slim

# Enable Corepack in the container
RUN corepack enable

WORKDIR /app
COPY package.json pnpm-lock.yaml ./

# Corepack reads packageManager and uses the right version
RUN pnpm install --frozen-lockfile

COPY . .
CMD ["pnpm", "start"]

Preparing packages for offline use

In environments without internet access (air-gapped systems, restricted CI), you can pre-download package manager binaries:

# Download and cache the package manager
corepack prepare pnpm@9.4.0 --activate

# Pack it for transfer
corepack pack pnpm@9.4.0 -o ./pnpm-9.4.0.tgz

On the offline machine:

corepack install -g ./pnpm-9.4.0.tgz

Managing multiple projects

If you work on multiple projects using different package managers, Corepack handles the switching automatically:

~/projects/
  api/          # packageManager: "pnpm@9.4.0"
  frontend/     # packageManager: "yarn@4.1.0"
  legacy/       # packageManager: "npm@10.2.0"

When you cd into each project and run the corresponding package manager, Corepack uses the correct version. No manual switching required.

Troubleshooting

“Corepack is not enabled”: Run corepack enable once. On some systems you may need sudo.

“This project is configured to use X”: You are running the wrong package manager. Check packageManager in package.json.

Version mismatch in CI: Make sure your CI setup runs corepack enable before any package manager commands. Some CI images have Corepack disabled by default.

Hash mismatch: If you see integrity errors, the cached binary may be corrupted. Clear the cache:

corepack clean
corepack use pnpm@9.4.0

Key takeaways

Corepack eliminates package manager version drift across teams and CI environments. Add the packageManager field to package.json, enable Corepack in your development setup and CI pipelines, and your entire team will use the exact same package manager version. The integrity hash ensures you are running a verified binary. For new projects, default to Corepack instead of global package manager installations.