|$ curl https://forge-ai.dev/api/markdown?path=docs/npm/corepack
$cat docs/corepack.md
updated Today·18-24 min read·published
Corepack
Introduction
Corepack is a Node.js tool that manages package manager binaries for Yarn and pnpm (and historically other shims). Instead of asking every developer to npm i -g pnpm at a random version, the repo declares packageManager in package.json and Corepack downloads that exact release on first use.
That single field is the contract between local machines, Docker images, and CI. Pair it with manager choice and best practices.
📝
note
Corepack does not manage Bun or npm itself. npm still ships with Node; Bun is installed separately.
Why Teams Need It
| Problem without Corepack | With Corepack |
|---|---|
| Dev A on pnpm 8, Dev B on pnpm 9 → lockfile thrash | Everyone gets packageManager version |
| Global yarn still Classic v1 | Berry version pinned per project |
| CI image drifts from laptops | Same prepare/activate path |
| "Works on my machine" install scripts | Deterministic manager binary |
Enabling Corepack
Corepack ships with Node but is often disabled by default (depending on Node version and distro packaging). Enable it once per machine or image.
enable.sh
Bash
| 1 | # Requires a recent Node.js (16.10+ historically; use current LTS) |
| 2 | node -v |
| 3 | which corepack |
| 4 | |
| 5 | corepack enable |
| 6 | |
| 7 | # Optional: pre-download a manager without entering a project |
| 8 | corepack prepare pnpm@9.15.0 --activate |
| 9 | corepack prepare yarn@4.5.0 --activate |
| 10 | |
| 11 | pnpm --version |
| 12 | yarn --version |
⚠
warning
Some Linux distro Node packages strip Corepack. Prefer official Node binaries, fnm/nvm, or Docker node:22 images when Corepack is missing.
packageManager Field
The packageManager field is a string: name@version, optionally with a hash for integrity.
package.json
JSON
| 1 | { |
| 2 | "name": "acme", |
| 3 | "private": true, |
| 4 | "packageManager": "pnpm@9.15.0" |
| 5 | } |
package.json (with hash)
JSON
| 1 | { |
| 2 | "packageManager": "pnpm@9.15.0+sha512.AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" |
| 3 | } |
| Value example | Meaning |
|---|---|
| pnpm@9.15.0 | Use pnpm 9.15.0 via Corepack |
| yarn@4.5.0 | Use Yarn Berry 4.5.0 |
| npm@10.9.0 | Declared for tooling; npm still comes from Node |
set-field.sh
Bash
| 1 | # Yarn can write the field when setting version |
| 2 | yarn set version 4.5.0 |
| 3 | |
| 4 | # Or set manually / via npm pkg |
| 5 | npm pkg set packageManager=pnpm@9.15.0 |
| 6 | |
| 7 | # Verify Corepack respects it from project root |
| 8 | pnpm --version # should match packageManager |
✓
best practice
Pin an exact version (not a range). Ranges defeat the purpose — two machines could still diverge.
Pinning Workflow for Teams
- Choose pnpm or Yarn Berry (see compare guide).
- Pick a current stable exact version; record it in packageManager.
- Commit lockfile + field in the same PR.
- Document corepack enable in README / onboarding.
- Mirror the same enable + install steps in CI and Docker.
- Upgrade manager versions in deliberate PRs (changelog + reinstall).
upgrade-pnpm.sh
Bash
| 1 | # Bump pnpm for the whole team |
| 2 | npm pkg set packageManager=pnpm@9.15.4 |
| 3 | corepack prepare pnpm@9.15.4 --activate |
| 4 | pnpm install |
| 5 | git add package.json pnpm-lock.yaml |
| 6 | git commit -m "chore: bump pnpm to 9.15.4" |
CI Usage
Enable Corepack before any pnpm / yarninvocation. Cache the package store separately from Corepack's downloaded shims when possible.
.github/workflows/ci.yml
YAML
| 1 | name: ci |
| 2 | on: [push, pull_request] |
| 3 | jobs: |
| 4 | build: |
| 5 | runs-on: ubuntu-latest |
| 6 | steps: |
| 7 | - uses: actions/checkout@v4 |
| 8 | - uses: actions/setup-node@v4 |
| 9 | with: |
| 10 | node-version: 22 |
| 11 | cache: pnpm |
| 12 | - run: corepack enable |
| 13 | - run: corepack prepare --activate |
| 14 | # reads packageManager from package.json when supported |
| 15 | - run: pnpm install --frozen-lockfile |
| 16 | - run: pnpm test |
| 17 | - run: pnpm build |
Dockerfile
Dockerfile
| 1 | FROM node:22-bookworm-slim AS deps |
| 2 | WORKDIR /app |
| 3 | RUN corepack enable |
| 4 | COPY package.json pnpm-lock.yaml ./ |
| 5 | # packageManager field must be present in copied package.json |
| 6 | RUN corepack prepare --activate \ |
| 7 | && pnpm install --frozen-lockfile |
| 8 | |
| 9 | FROM node:22-bookworm-slim AS runner |
| 10 | WORKDIR /app |
| 11 | COPY --from=deps /app/node_modules ./node_modules |
| 12 | COPY . . |
| 13 | CMD ["node", "dist/server.js"] |
ℹ
info
If setup-node cache for pnpm fails before Corepack exists, enable Corepack first, then install, or use pnpm/action-setup with a version matching packageManager.
Corepack + Yarn Berry
Yarn Berry also commits a project-local binary under .yarn/releases. Corepack still helps bootstrap the correct Yarn to run that project. Keep packageManager aligned with the committed release.
yarn-corepack.sh
Bash
| 1 | corepack enable |
| 2 | yarn set version 4.5.0 |
| 3 | # updates packageManager + .yarn/releases |
| 4 | yarn install --immutable |
Deep dive: Yarn Classic vs Berry.
Corepack + pnpm
pnpm-corepack.sh
Bash
| 1 | corepack enable |
| 2 | # package.json already has "packageManager": "pnpm@9.15.0" |
| 3 | pnpm install --frozen-lockfile |
| 4 | pnpm --version |
Deep dive: pnpm.
Enforcing the Manager
Corepack pins versions; only-allow blocks the wrong tool entirely (e.g. someone running npm install in a pnpm repo).
package.json
JSON
| 1 | { |
| 2 | "packageManager": "pnpm@9.15.0", |
| 3 | "scripts": { |
| 4 | "preinstall": "npx only-allow pnpm" |
| 5 | } |
| 6 | } |
🔥
pro tip
Combine packageManager + only-allow + a single committed lockfile. That trio eliminates most multi-manager chaos.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| corepack: command not found | Distro Node without Corepack | Install official Node / use nvm |
| Wrong pnpm version | Global pnpm shadows Corepack | corepack enable; check PATH order |
| Network error downloading manager | Firewall / registry | prepare in build image; allow Node download hosts |
| CI cache miss every run | Cache key before enable | Enable Corepack, then cache store by lockfile |
| Hash mismatch on packageManager | Corrupted or wrong hash | Reset field to name@version and re-prepare |
debug.sh
Bash
| 1 | type pnpm |
| 2 | type yarn |
| 3 | corepack --version |
| 4 | node -p "process.versions" |
| 5 | cat package.json | grep packageManager |
| 6 | # On Unix: ensure Corepack shims win over ~/.local/bin globals |
| 7 | echo "$PATH" |
Security Notes
- Prefer packageManager with integrity hash when your toolchain supports generating it.
- Do not download Yarn/pnpm install scripts from random gists when Corepack can fetch signed releases.
- Keep Node LTS updated — Corepack bugs are fixed in Node releases.
- In air-gapped CI, vendor the manager tarball and point Corepack at an internal mirror if configured.
✕
danger
Disabling Corepack and installing random global majors is how lockfiles silently churn. Treat manager upgrades like dependency upgrades — PR + CI green.
Checklist
- corepack enable in onboarding + CI + Docker
- Exact packageManager in root package.json
- One lockfile matching that manager
- only-allow preinstall when enforcing
- Document Bun separately if used (no Corepack)
- Bump manager versions in dedicated commits
Community
Get help on Slack, Discord or VIP
Stuck on a guide? Join the community and ask.