pnpm run: Usage, Options & Common Errors

By Daniel Zoghalchali·Latchkey

Run scripts in one package or across the workspace.

pnpm run executes a named script from package.json. Add -r to run it across every workspace package, or --filter to target a subset.

What it does

Runs the named script with node_modules/.bin on PATH. -r (recursive) runs it in every workspace package that defines it, in topological order; --filter narrows to matching packages. Args after the script are passed through.

Common usage

Terminal

pnpm run build              # run build in this package
pnpm build                  # "run" is optional for non-builtins
pnpm -r run test            # run test in every workspace
pnpm --filter @acme/web run dev

Common CI error: recursive run fails on one package

pnpm -r run build aborts because one workspace package fails to build. By default pnpm stops on the first failure. Use --filter to isolate the failing package, or pass --no-bail to keep going and collect all failures in one CI run.

Terminal

pnpm -r --no-bail run build   # don't stop at the first failure

Using this in CI

Node tooling on a runner differs from your machine in three ways that matter: CI=true is set, there is no TTY, and the Node major may not be the one you develop on.

Pin the Node major with setup-node and in engines. Native modules resolve different prebuilt binaries per major.
CI=true changes behaviour in several tools, most often by promoting warnings to errors or disabling interactive prompts.
Commands that expect a TTY will hang. Pass the non-interactive or --yes flag explicitly.
Use npm exec or node_modules/.bin rather than assuming a globally installed binary is on PATH.

Frequently asked questions

pnpm run: Usage, Options & Common Errors?

pnpm run executes a named script from package.json. Add -r to run it across every workspace package, or --filter to target a subset.

What it does?

Common CI error: recursive run fails on one package?