pnpm: everyday commands | npm and pnpm

Once pnpm is installed, the daily command set is small.

The most important thing to learn first is the difference between pnpm install and pnpm add.

`pnpm install` installs what the project already declares

To install the dependencies that are already listed in a project:

pnpm install

This is the command to run after cloning a repository, switching branches, or pulling dependency changes from someone else.

This parallels npm install. In pnpm, though, install is mainly about bringing the project into the state it already declares.

`pnpm add` adds new packages to the project

To add a normal dependency:

pnpm add react

To add more than one package at once:

pnpm add react react-dom

To add a development dependency:

pnpm add -D typescript

To add several development dependencies in one step:

pnpm add -D typescript eslint prettier

To add an optional dependency:

pnpm add -O fsevents

Optional dependencies are packages that improve a project but are not critical. If they fail to install, pnpm continues instead of stopping.

To add a peer dependency:

pnpm add --save-peer react

Peer dependencies signal that your package expects another package to be provided by the consuming project.

This is one of the clearest differences from npm. In pnpm, add is the main verb for introducing new dependencies.

Removing a package

To remove a dependency:

pnpm remove react

This updates the project manifest, the lockfile, and the installed dependencies.

Global tools

See the global tools lesson for guidance on when to install packages globally vs locally.

Running scripts

If the project defines scripts in package.json, pnpm can run them directly.

Examples:

pnpm dev
pnpm build
pnpm test

The pnpm CLI docs describe pnpm <cmd> as the equivalent of npm run <cmd> for common script usage.

Running a locally installed tool

If a tool is already installed in the project, you can run its binary with:

pnpm exec eslint .

This is useful when you want to invoke the tool directly instead of going through a script.

It is the direct parallel to npm exec.

Running a tool one time

To run a package without saving it as a dependency, use:

pnpm dlx create-vite@latest my-app

This is useful for:

scaffolding a new project
trying a command once
avoiding a permanent dependency for a one-time task

It is the pnpm parallel to npx.

The lockfile matters in pnpm too

In a pnpm project, the lockfile is pnpm-lock.yaml.

As with npm, it should be committed. It is part of the dependency state of the project.

pnpm in CI

For CI, installs should be reproducible and should fail when the dependency state is out of sync.

A strict explicit command is:

pnpm install --frozen-lockfile

The pnpm install docs say that --frozen-lockfile defaults to true in CI environments when a lockfile is present. That means CI is expected to reject drift instead of silently rewriting the lockfile.