pnpm Command: Install and Manage Node.js Packages

Large Node.js projects can consume a surprising amount of disk space when every project keeps its own copies of the same packages. pnpm addresses this by storing package files in a shared content-addressable store and linking them into each project. It uses the npm registry and works with the same package.json files while providing stricter dependency handling and built-in workspace support.

This guide explains how to install pnpm on Linux, macOS, and Windows, then use it to create projects, install and update packages, run scripts, migrate from npm, and work across a monorepo.

Syntax #

The general form of the command is:

pnpm <command> [options]

Most pnpm commands have direct npm equivalents. For example, pnpm install installs project dependencies, pnpm add records a new dependency, and pnpm run executes a script from package.json.

How pnpm Stores Packages #

pnpm keeps package files in a shared store on your machine. Projects link to those files instead of copying the same package contents into every node_modules directory. If ten projects use the same package version, pnpm stores its files once.

The resulting node_modules layout also prevents packages from importing dependencies they did not declare. This stricter behavior helps expose missing dependency declarations that npm’s flat dependency layout can sometimes hide.

You still commit package.json and the pnpm-lock.yaml lockfile to version control. The shared store and generated node_modules directory should not be committed.

Install pnpm #

pnpm 11 requires Node.js 22.13 or newer when you install it through npm or Corepack. Check your current version first:

node --version

If you need a newer release, follow our guide to install Node.js and npm on Ubuntu 26.04 , or use a Node.js version manager on other systems.

Install with Corepack #

Corepack manages package-manager versions and can select the pnpm release recorded in a project’s package.json. Update Corepack first to avoid outdated signature data:

npm install --global corepack@latest

Enable the pnpm shim:

corepack enable pnpm

Pin pnpm for the current project:

corepack use pnpm@latest-11

This adds a packageManager entry with an exact pnpm version to package.json, which helps contributors and CI jobs use the same release.

Install with npm #

If you prefer a regular global package, install the current pnpm 11 release with:

npm install --global pnpm@latest-11

This method requires a compatible Node.js version. It does not automatically enforce a project-specific pnpm version.

Install the Standalone Version #

The standalone installer does not require Node.js to be present. On Linux, macOS, and other POSIX systems, run:

curl -fsSL https://get.pnpm.io/install.sh | sh -

On Windows PowerShell, use:

Invoke-WebRequest https://get.pnpm.io/install.ps1 -UseBasicParsing | Invoke-Expression

Open a new terminal after the installer finishes, then verify the command:

pnpm --version

11.5.2

Initialize a Project #

Create a directory and initialize a package.json file:

mkdir example-app
cd example-app
pnpm init

pnpm prompts for package metadata and writes the result to package.json. If you already have a project created with npm, pnpm can use its existing package.json without any conversion.

Install Packages #

Add a runtime dependency with pnpm add:

pnpm add express

pnpm installs the package, records it under dependencies in package.json, and creates or updates pnpm-lock.yaml.

Add development tools with -D (short for --save-dev):

pnpm add -D eslint

To install a specific package version, append it after @:

pnpm add express@5.1.0

When you clone an existing pnpm project, install everything declared in its package files with:

pnpm install

For CI or another reproducible environment, prevent changes to the lockfile:

pnpm install --frozen-lockfile

The command fails when package.json and pnpm-lock.yaml do not agree instead of resolving a new dependency tree.

Install Global Packages #

Install a command-line tool globally with -g:

pnpm add -g http-server

If pnpm reports that it cannot find a global binary directory, run:

pnpm setup

Open a new terminal so the updated PATH takes effect, then repeat the global install. Keep application dependencies local to each project and reserve global installs for commands you need across projects.

Update and Inspect Packages #

Check which dependencies have newer versions available:

pnpm outdated

Update dependencies within the version ranges in package.json:

pnpm update

To update one package to its latest published release and change its declared range, run:

pnpm update express --latest

List the direct dependencies in the current project with:

pnpm list --depth 0

When you need to understand why a package is present, use:

pnpm why express

Remove Packages #

Remove a dependency from node_modules, package.json, and the lockfile with:

pnpm remove express

For a globally installed package, add -g:

pnpm remove -g http-server

Run Scripts and Package Binaries #

pnpm reads the scripts section of package.json just like npm. Given this file:

{
  "scripts": {
    "start": "node index.js",
    "lint": "eslint ."
  }
}

Run a named script with:

pnpm run lint

You can omit run when the script name does not conflict with a pnpm command:

pnpm start

Use pnpm exec to run a binary installed in the current project:

pnpm exec eslint .

For a one-off package that you do not want to add as a dependency, use pnpm dlx:

pnpm dlx create-vite@latest my-app

pnpm exec runs an existing local dependency, while pnpm dlx fetches a package temporarily and runs its command.

Migrate a Project from npm #

From a project containing package-lock.json, generate a pnpm lockfile with:

pnpm import

The command reads the npm lockfile and creates pnpm-lock.yaml. Install the imported dependency tree next:

pnpm install

Run the project’s tests and build before removing package-lock.json. Commit pnpm-lock.yaml, and update CI commands from npm ci to pnpm install --frozen-lockfile.

If the repository records its package manager, set the current pnpm version with:

corepack use pnpm@latest

Use pnpm Workspaces #

A pnpm workspace groups multiple packages in one repository. Define its package locations in pnpm-workspace.yaml at the repository root:

packages:
  - "apps/*"
  - "packages/*"

Install dependencies for every workspace package from the root:

pnpm install

Run a script recursively across all packages that define it:

pnpm --recursive run build

Use --filter when a command should target one package:

pnpm --filter web-app add zod
pnpm --filter web-app run test

Filters can select packages by name, directory, dependency relationship, or changed files, which makes them useful in larger monorepos and CI jobs.

Quick Reference #

Troubleshooting #

pnpm: command not found after installation
Open a new terminal so your shell reloads its PATH. For a standalone or global setup, run pnpm setup, restart the terminal, and check again with pnpm --version.

ERR_PNPM_UNSUPPORTED_ENGINE
The installed pnpm or one of the project packages requires a different Node.js version. pnpm 11 installed through npm or Corepack requires Node.js 22.13 or newer. Upgrade Node.js or use the standalone pnpm installer.

A package import worked with npm but fails with pnpm
The code may rely on a transitive dependency that is not declared in its own package.json. Add the missing package as a direct dependency instead of relying on npm’s flatter node_modules layout.

ERR_PNPM_OUTDATED_LOCKFILE in CI
The committed pnpm-lock.yaml does not match package.json. Run pnpm install locally, review and commit the updated lockfile, then rerun pnpm install --frozen-lockfile in CI.

Conclusion #

pnpm uses the familiar npm package ecosystem while reducing duplicate package storage and enforcing clearer dependency declarations. If you are comparing workflows, see the npm command guide for the equivalent npm commands and lockfile behavior.

About the authors

Dejan Panovski

Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 800+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.

View author page