Corepack: Manage Yarn and pnpm Versions in Node.js
Corepack: Manage Yarn and pnpm Versions in Node.js
Corepack helps developers manage Yarn, npm, and pnpm versions per project. Achieve consistent installs, Docker-ready setups, and smooth package management effortlessly.
Corepack is a package manager version-management tool for Node.js that helps projects use their intended versions of Yarn and pnpm.
Instead of manually switching global package manager installations, Corepack can read your project’s configuration and launch the appropriate version when you run a supported command.
What Is Corepack?
Corepack is a Node.js tool that manages versions of supported JavaScript package managers.
It acts as an intermediary between a project and the package manager used to install its dependencies.
For example, a project may specify the following in package.json:
The packageManager field tells Corepack that the project expects Yarn 3.6.4.
When Corepack handles a Yarn command inside that project, it can select the specified version and download it if necessary.
This helps developers use consistent package manager versions without requiring the same global installation for every project.
Corepack primarily provides command shims for Yarn and pnpm. npm is normally distributed with Node.js and has its own installation and command behavior.
Why Is Corepack Useful?
Imagine you’re working on two applications.
The first project uses Yarn 2.4.3. The second requires Yarn 3.6.4.
Without appropriate version management, switching between the projects could require manually managing different installations.
With Corepack, each project can declare its required version.
This provides several practical benefits:
More consistent development
Team members can use the package manager version required by the repository.
Easier project switching
Different projects can use different Yarn or pnpm versions.
Simpler onboarding
Developers can check the required package manager in the project configuration.
Better CI consistency
Build environments can use the package manager version selected by the repository.
Fewer version-related surprises
Teams are less likely to accidentally use an incompatible package manager release.
Corepack doesn’t solve every dependency or deployment problem. Lockfiles, Node.js versions, operating systems, and project configuration also affect whether an application builds successfully.
How Corepack Works Internally
Corepack checks the current project to determine which supported package manager should run.
When its command shims are enabled, the process generally follows these steps:
- You run a package manager command. For example, yarn install.
- Corepack checks the project configuration. It looks for the expected package manager information.
- Corepack selects a version. It uses the declared version when applicable.
- Corepack locates or downloads the package manager. A download may be necessary if the version isn't cached.
- The package manager runs. Yarn or pnpm performs the requested operation.
For example, suppose your project contains:
With Corepack correctly configured, running:
allows Corepack to use the project’s selected pnpm version.
The pnpm command then installs the dependencies according to the project’s manifest, lockfile, and configuration.
What Happens When a Project Doesn't Specify a Version?
If a project doesn’t declare a supported package manager, Corepack may use a configured default known as a Known Good Release.
The specific behavior depends on the installed Corepack version and project metadata.
For predictable development, it’s better to explicitly define the required package manager version.
How to Install Corepack
First, check whether Node.js and npm are installed:
Then check Corepack:
If Corepack is available, the command displays its version.
If it isn’t installed, you can install a compatible release through npm:
Important Node.js Compatibility Information
Corepack was bundled with official Node.js releases starting with Node.js 14.19.0 and 16.9.0, continuing through the Node.js 24 release line.
Starting with Node.js 25, Corepack is no longer bundled with Node.js.
Corepack also has its own runtime requirements.
For example, Corepack 0.35.0 dropped support for Node.js 20 and Node.js 25.
Before installing or upgrading Corepack, verify that the selected release supports your Node.js version.
If an existing project requires an older Node.js runtime, you may need a compatible Corepack version rather than the latest release.
How to Enable Corepack
After confirming that Corepack is installed, run:
This creates command shims that allow Corepack to manage supported package manager commands.
Once enabled, you can check the available Yarn command:
You can also check pnpm:
Corepack may need to retrieve the selected package manager version if it isn’t already available locally.
Does corepack enable Install Yarn?
Not necessarily.
The corepack enable command sets up the command shims.
It doesn’t guarantee that every package manager version has already been downloaded.
To explicitly configure a default stable Yarn release with a current Corepack version, run:
For a project that already specifies its expected package manager, you can use:
This prepares the version configured for the current project without changing the global default.
Read our Corepack Enable Guide for detailed instructions and solutions to command shim or permission errors.
How to Use Corepack With Yarn
Yarn is a JavaScript package manager used to install dependencies, manage package versions, and run project scripts.
Corepack helps projects select their expected Yarn release.
For example, if a project requires Yarn 3.6.4, its package.json may contain:
When Corepack manages the Yarn command, running:
should show the project’s configured version.
You can then install dependencies:
The installation behavior depends on the Yarn release, lockfile, and project configuration.
If you’re setting up Yarn for the first time, follow our Install Yarn Guide.
For an explanation of dependency installation, lockfiles, and supported flags, visit Yarn Install.
Can Corepack Manage Yarn 2 and Yarn 3?
Yes.
Different projects can specify different Yarn versions.
For example, one repository may use Yarn 2.4.3 while another requires Yarn 3.6.4.
Corepack can select the appropriate version for each configured project.
For version-specific instructions, read our guides to Installing Yarn 2 and Installing Yarn 3.
How to Use Corepack With pnpm
pnpm is another JavaScript package manager supported by Corepack.
Like Yarn, pnpm can be configured at the project level.
For example:
After Corepack is configured, check the version:
Then install the project’s dependencies:
Corepack manages which pnpm version runs. pnpm itself handles dependency resolution and installation.
This distinction is important because Corepack isn’t responsible for every operation performed by the package manager.
Corepack vs. npm vs. Yarn vs. pnpm
These tools work together in the Node.js ecosystem, but they don’t all have the same purpose.
| Tool | Primary responsibility |
|---|---|
| Corepack | Selects and manages supported package manager versions |
| npm | Installs JavaScript packages and manages dependencies |
| Yarn | Installs dependencies, runs scripts, and manages JavaScript projects |
| pnpm | Manages JavaScript dependencies with an efficient package storage model |
The main difference is that Corepack manages package manager versions, while npm, Yarn, and pnpm manage project packages.
Corepack isn’t a direct replacement for npm, Yarn, or pnpm.
Also, enabling Corepack doesn’t normally replace the standard npm command distributed with Node.js.
Essential Corepack Commands
Here are some useful commands supported by current Corepack releases.
| Command | Description |
|---|---|
| corepack --version | Shows the installed Corepack version |
| corepack enable | Creates package manager command shims |
| corepack enable yarn | Enables the Yarn shim |
| corepack disable | Removes Corepack-managed command shims |
| corepack install | Prepares the project's configured package manager |
| corepack install -g yarn@stable | Configures a default stable Yarn release |
| corepack use yarn@stable | Selects a stable Yarn release for the project and runs installation |
| corepack up | Updates the project's package manager within the applicable release line |
| corepack cache clean | Clears Corepack's package manager download cache |
Command availability can differ across Corepack versions.
You can inspect the options supported by your installation using:
Before using unfamiliar commands in a production repository, review their effect on package.json, configuration files, and existing package manager versions.
Corepack and the packageManager Field
The packageManager field is one of the most important pieces of information Corepack uses.
It identifies the package manager and version expected by the project.
An example looks like this:
In this example, the project declares Yarn 3.6.4.
Developers working in the repository can use Corepack to run that version.
Why Should You Pin the Package Manager Version?
An exact version helps reduce differences between development environments.
For example, if one developer uses a newer Yarn major version while another uses an older version, their installation results or lockfile changes may differ.
Pinning the package manager helps prevent unintended version changes.
However, it doesn’t guarantee identical builds on its own.
The project should also maintain a consistent lockfile, suitable Node.js version, and appropriate environment configuration.
Corepack in CI/CD and Docker
Corepack can be useful in automated development environments, including continuous integration pipelines and Docker containers.
For example, a CI environment can enable Corepack and run the package manager specified by the repository.
A basic Yarn workflow may involve:
The –immutable option is supported by modern Yarn and prevents unexpected lockfile modifications.
For Yarn Classic, the appropriate lockfile-protection flag is different.
Similarly, container builds need a compatible Corepack and Node.js combination. Some Docker images may not contain Corepack by default.
Corepack can also support offline workflows when package manager releases have been prepared in advance.
For production workflows, use the official documentation to validate your selected runtime, package manager version, and caching approach.
Common Corepack Problems
If Corepack isn’t working as expected, identify the error before reinstalling software or deleting configuration files.
Corepack Command Not Found
If your terminal doesn’t recognize corepack, confirm Node.js and npm are available.
You may need to install Corepack separately:
Choose a compatible release for your Node.js version.
If the command is still unavailable, check your PATH configuration.
Yarn Command Not Found
If Corepack is installed but Yarn isn’t recognized, try:
Then check:
If the command still fails, inspect whether another installation or the command’s location is causing a conflict.
Permission Denied
Corepack may fail to create command shims when the installation directory is read-only or protected.
Review the directory permissions and your Node.js installation method.
A Node.js version manager or an appropriate custom shim directory may help in some environments.
Avoid changing system-wide permissions or disabling security controls without understanding the consequences.
Wrong Package Manager Version
If a project runs an unexpected Yarn or pnpm version, check its packageManager field.
Then inspect the active command and the project’s configuration.
You can prepare the configured version with:
This won’t automatically solve conflicting executable paths or an incorrect project configuration, so inspect those separately if necessary.
Best Practices for Using Corepack
A reliable Corepack workflow starts with clear project configuration.
Use compatible Node.js and Corepack version: Check their release requirements before upgrading.
Pin package manager version: Record the expected version in your project’s configuration.
Maintain your lockfile: Commit intentional yarn.lock or pnpm-lock.yaml changes alongside related dependency updates.
Avoid conflicting installations: Know whether your Yarn or pnpm commands are managed by Corepack, npm, Homebrew, or another tool.
Document the project setup: Include the expected runtime, package manager version, and installation commands in your README.
Test changes before deployment: A successful package manager setup doesn’t guarantee that an application will build or run correctly.
Frequently Asked Questions (FAQ's)
What is Corepack in Node.js?
Corepack is a version-management tool that helps projects use their configured JavaScript package manager versions.
It primarily manages Yarn and pnpm command shims.
Is Corepack included with Node.js?
Corepack was bundled with supported Node.js releases before version 25. Starting with Node.js 25, it is no longer included by default.
You can install it separately using npm when necessary.
Is Corepack the same as Yarn?
No. Corepack selects package manager versions, while Yarn installs and manages a project’s dependencies.
Do I need Corepack to use Yarn?
No. Yarn can be installed through other supported methods. Corepack is useful when projects need consistent, project-specific versions.
What does corepack enable do?
It creates command shims so Corepack can handle supported package manager commands.
Then enable it:
Does Corepack work on Windows, macOS, and Linux?
Yes. Corepack is cross-platform and works on all major operating systems supported by Node.js, including Windows, macOS, and Linux.
Can Corepack manage different Yarn versions?
Yes. Corepack can select different Yarn versions for different projects based on their configuration.
Does Corepack replace npm?
No. Corepack and npm serve different purposes. npm remains a package manager, while Corepack provides package manager version management.
What happens if Corepack cannot download Yarn?
Check network access, the configured package manager version, and any registry or proxy restrictions.
Offline workflows are possible when the required package manager releases have been prepared beforehand.