Corepack is an experimental tool that helps you to manage your package managers. It ships with the official Node.js installer so you probably have it installed already.

Why do I need Corepack?

There are many different package managers for Node.js, the most notable being npm, yarn, and pnpm. Each has a similar feature set with different trade-offs. They all do the following:

  • Add/remove/update/dedupe dependencies
  • Run package.json scripts
  • Manage monorepos (via workspaces)
  • Reproducible installs (via lockfile)

While these features seem similar, they have different implementations. Specifically, "reproducible installs" is only guaranteed when you use the same package manager that knows how to read a given lockfile, such as:

  • package-lock.json
  • yarn.lock
  • pnpm-lock.yaml

Not to mention, lockfiles might change implementations between different versions of a package manager. For example, v2 lockfiles introduced in npm 7 are not compatible with earlier versions of npm.

Ok we established the package manager version is important, but how can we keep that version in sync?

Before Corepack existed, your probably used to do something manual like:

# Wrong
npm install --global pnpm@7.9.0

Using npm to install pnpm, is the equivalent of using Internet Explorer to install Chrome.

What is Corepack?

Corepack is an experimental tool that helps you to manage your package managers. Although you may have never heard of it, Corepack ships with Node.js 14.19.0 and newer. So you likely have it installed already!

Corepack transparently installs the correct package manager version based on the closest package.json file. For example, you can configure pnpm 6 with one project and pnpm 7 with another project, no need to run additional commands.

How do I use Corepack?

To get started, make sure you are using Node.js 14.19.0 or newer.

Then run corepack enable once per machine to install a shim that can handle any version.

Finally, update your project's package.json file with a packageManager property. This must be the exact version of the package manager (not a range).

{
  "packageManager": "pnpm@7.9.0"
}

Update 2023: Automatically edit package.json with corepack use pnpm@7.9.0

Now every time you run pnpm, the correct version will be selected. If that version has never been installed on the current machine, Corepack will install it transparently in the background before executing.

If you want to see if Corepack is using a cached version or installing from the network, set DEBUG=corepack environment variable to see verbose logs.

If no package.json is found, Corepack will use the global version. You can update the global version by running the following:

corepack prepare pnpm@7.9.0 --activate

Update 2023: Alias for corepack install --global pnpm@7.9.0

Who is Corepack for?

Everyone can benefit from Corepack, especially projects with multiple developers.

Corepack ensures that you, your collaborators, your CI, your deployment platform all use the same version of the same package manager.

When will Corepack become stable?

Corepack is considered experimental status but there is a discussion about going stable in the future.

Does Corepack support Bun?

No, not yet. See Issue 295.

Any other Corepack caveats?

The biggest caveat to watch out for is that Corepack can sometimes be too strict and cause Usage Error: This project is configured to use pkgmgr. However, you can skip this strict check by setting the COREPACK_ENABLE_STRICT=0 environment variable.

Another caveat to look for is ever increasing cache storage that you might want to manually delete every once in awhile to reclaim disk space (~/.cache/node/corepack).