pnpm run

Aliases: run-script

Exécute un script défini dans le fichier manifeste du projet. Without a script name, pnpm run lists the available scripts:

pnpm run

Exemples#

Let's say you have a watch script configured in your package.json, like so:

package.json
"scripts": {
    "watch": "webpack --watch"
}

Run it with pnpm run watch. pnpm watch is a shorthand for pnpm run watch. The shorthand works only for scripts whose name is not a pnpm command. A built-in command runs instead of a same-named script, except for the commands listed in pnpm pm, which run the script.

Exécuter plusieurs scripts#

Vous pouvez exécuter plusieurs scripts en même temps en utilisant une expression régulière au lieu du nom du script.

pnpm run "/<regex>/"

Run all scripts that start with watch::

pnpm run "/^watch:/"

The selector must be written as a regular expression literal (that is, wrapped in slashes) and quoted, so the shell does not mangle it. A plain string is always treated as a literal script name, and a script whose name matches the argument exactly takes precedence over regex matching.

The pattern uses JavaScript regular expression syntax, including lookahead and lookbehind. Run every hello: script except hello:b:

pnpm run "/^hello:(?!b$).*$/"

Matching is not anchored, so "/build:.*/" also matches prebuild:web. Anchor the pattern with ^ and $ when you need an exact prefix.

Matched scripts run in lexicographical order, so the selection is deterministic regardless of the order the scripts appear in package.json. Since v12.2.0 they run concurrently, up to --workspace-concurrency, with each script's output prefixed by its name. To run them strictly one at a time, add --sequential.

With --no-bail, a failing script does not stop the others: every matched script is allowed to finish, and the command then exits with ERR_PNPM_RUN_FAILED, listing the ones that failed in selection order.

Regular expression flags are not supported: pnpm run "/^build:.*/i" fails with ERR_PNPM_UNSUPPORTED_SCRIPT_COMMAND_FORMAT.

Détails#

In addition to the shell's pre-existing PATH, pnpm run includes node_modules/.bin in the PATH provided to scripts. Cela a pour conséquence que du moment où vous avez un package installé, vous pouvez l'utiliser dans un script comme une commande classique. For example, if you have eslint installed, you can write up a script like so:

package.json
"lint": "eslint src --fix"

And even though eslint is not installed globally in your shell, it will run.

For workspaces, <workspace root>/node_modules/.bin is also added to the PATH, so if a tool is installed in the workspace root, it may be called in any workspace package's scripts.

Environnent#

Pnpm crée automatiquement certaines variables d'environnement pour les scripts, lorsque ceux-ci sont exécutés. Ces variables d'environnement peuvent être utilisées pour obtenir des informations contextuelles sur le processus en cours.

Voici les variables d'environnement créées par pnpm :

  • npm_command - contains the name of the executed command. If the executed command is pnpm run, then the value of this variable will be "run-script".
  • npm_lifecycle_event - the name of the running script.
  • npm_lifecycle_script - the command of the running script.
  • npm_package_json - the path to the package's package.json.
  • npm_package_* - the name, version, config, engines, and bin fields of package.json, such as npm_package_name and npm_package_config_port.
  • npm_config_user_agent - the user agent of pnpm.
  • npm_execpath - the path to the pnpm executable.
  • npm_node_execpath and NODE - the path to the Node.js executable.
  • INIT_CWD - the directory pnpm was run from.
  • PNPM_SCRIPT_SRC_DIR - the directory of the package whose script runs.
  • FORCE_COLOR - set to 1 when pnpm prints the script's output itself and pnpm's own output is in color. pnpm prints the output itself with --stream or --parallel, or when several scripts run at once. A FORCE_COLOR that is already set is kept.

Options#

Any options for the run command should be listed before the script's name. Les options listées après le nom du script seront transmises au script exécuté.

All these will run pnpm CLI with the --silent option:

pnpm run --silent watch
pnpm --silent run watch
pnpm --silent watch

Tous les arguments situés après le nom de la commande sont ajoutés au script exécuté. So if watch runs webpack --watch, then this command:

pnpm run watch --no-color

exécutera :

webpack --watch --no-color

--recursive, -r#

Cette option permet exécuter une commande dans l'ensemble des package.json si la commande existe dans l'objet "scripts". Si un package.json n'a pas la commande alors il est ignoré. Si aucun des package.json existant n'a la commande demandée, la commande échoue.

By default, recursive runs use a dependency-aware task graph. Configure relationships between scripts with the tasks setting. --no-sort, and --parallel which implies it, remove that ordering and ignore the tasks declarations along with it.

--if-present#

You can use the --if-present flag to avoid exiting with a non-zero exit code when the script is undefined. Cela permet d'exécuter des scripts potentiellement indéfinis sans pour autant casser des chaînes d'exécution.

--no-bail#

Continue running the remaining matched scripts even if one of them fails. The command still exits with a non-zero exit code if any script failed.

--parallel#

Ignore complètement la concurrence et le tri topologique, exécutant un script donné immédiatement dans tous les packages correspondants avec un stream préfixé en sortie. C'est l'indicateur préféré pour les processus de longue durée sur de nombreux packages, par exemple, un long processus de génération.

--sequential, -s#

Run the selected scripts one by one. This forces --workspace-concurrency to 1, so scripts matched by a regex selector never overlap, neither across workspace packages nor within a single package.

pnpm run --sequential "/^build:.*/"

In a recursive run this serializes scripts across workspace projects as well as within each one. --sequential takes precedence over --parallel: concurrency is pinned to 1 whenever it is set, regardless of the order the two flags appear in.

note

For pnpm run, -s is the shorthand for --sequential. This includes the pnpm <script> shorthand, so pnpm -s watch means pnpm run --sequential watch. Everywhere else in the CLI, -s remains the shorthand for --reporter=silent. The long form --silent is unaffected in all commands.

On GitHub Actions, recursive runs with --sequential or --workspace-concurrency=1 group each script's output. Silent runs omit the group markers.

--workspace-concurrency#

Set the maximum number of workspace tasks to run simultaneously. See pnpm recursive --workspace-concurrency for defaults and how zero and negative values are interpreted.

--stream#

Diffuse la sortie des processus enfants de façon immédiate. Sortie qui est préfixée par le répertoire du package d'origine. Cela permet d'entrelacer la sortie de différents paquets.

--aggregate-output#

Regroupe la sortie des processus enfants exécutés en parallèle, et n'affiche la sortie qu'une fois le processus enfant terminé. It makes reading large logs after running pnpm -r <command> with --parallel or with --workspace-concurrency=<number> much easier (especially on CI). Only --reporter=append-only is supported.

--resume-from <package_name>#

Resume at the named package's requested task. pnpm skips the tasks a matching record of the previous run says already passed; without such a record it omits the task's transitive dependencies instead, treating them as completed. Either way it still runs the task itself, its dependents, and unrelated tasks in the selected graph. See Workspace task orchestration.

--dry-run#

Resolve a recursive run's task graph without running scripts. The plain output is one stable topological ordering, not a prediction of the order in which independent tasks will be dispatched.

pnpm -r run --dry-run build

--dry-run is only supported for recursive runs.

--json#

With --dry-run, print the resolved tasks and their dependency edges as JSON. See Inspect the task graph for the schema and an example.

--report-summary#

Record the result of the scripts executions into a pnpm-exec-summary.json file.

An example of a pnpm-exec-summary.json file:

pnpm-exec-summary.json
{
  "executionStatus": {
    "/Users/zoltan/src/pnpm/pnpm/cli/command": {
      "status": "passed",
      "duration": 1861.143042
    },
    "/Users/zoltan/src/pnpm/pnpm/cli/common-cli-options-help": {
      "status": "passed",
      "duration": 1865.914958
    }
  }
}

Possible values of status are passed, queued, running, skipped, and failure. A failed entry also has prefix and message fields. The key of a task other than the requested script is <dir>#<task>.

--reporter-hide-prefix#

Masque le préfixe du workspace dans la sortie des processus enfants exécutés en parallèle, pour afficher uniquement la sortie brute. This can be useful if you are running on CI and the output must be in a specific format without any prefixes (e.g. GitHub Actions annotations). Only --reporter=append-only is supported.

--sort, --reverse, --bail#

See --[no-]sort, --reverse, and --[no-]bail.

--filter <package_selector>#

Read more about filtering.

pnpm-workspace.yaml settings#

The tasks setting configures dependency relationships and per-task concurrency limits for recursive runs.

enablePrePostScripts#

  • Default: true
  • Type: Boolean

When true, pnpm will run any pre/post scripts automatically. So running pnpm foo will be like running pnpm prefoo && pnpm foo && pnpm postfoo.

scriptShell#

  • Default: null
  • Type: path

The shell to use for scripts run with the pnpm run command.

For instance, to force usage of Git Bash on Windows:

pnpm config set scriptShell "C:\Program Files\git\bin\bash.exe"

Since v12.4.0, a relative path in pnpm-workspace.yaml resolves from the workspace root, including for scripts that run in a nested package. A bare command name such as bash is still looked up on PATH.

shellEmulator#

  • Default: false
  • Type: Boolean

When true, pnpm will use its built-in cross-platform, bash-like shell to execute scripts.

This option simplifies cross-platform scripting. For instance, by default, the next script will fail on non-POSIX-compliant systems:

package.json
"scripts": {
  "test": "NODE_ENV=test node test.js"
}

But if the shellEmulator setting is set to true, it will work on all platforms.

Since v12.8.0, a configured non-empty scriptShell wins over shellEmulator for pnpm run and lifecycle scripts. The emulator runs only when scriptShell is unset or empty.

note

Node.js 22 or higher supports running scripts without pnpm's assistance. For the example above, you can run the test script with node --run test. However, the shellEmulator option has no effect on this. Scripts that depend on POSIX features are required to be run pnpm run instead of node --run to work in non-POSIX-compliant environments.