Глобальні пакунки

Глобальні пакунки — це інструменти та утиліти командного рядка, які встановлюються для всієї системи за допомогою команди pnpm add -g. В pnpm v11, управління лобальними пакунками було змінено для досягнення кращої ізоляції та надійності.

Втсановлення глобальних пакунків

pnpm add -g <pkg>

Наприклад:

pnpm add -g typescript prettier eslint

Ізольоване встановлення

Кожен глобально встановлений пакунок (або група пакунків, встановлених разом) отримує власну ізольовану теку зі своїми package.json, node_modules/ та файлом блокування. Це запобігає взаємному впливу глобальних пакунків через конфлікти залежностей між одноранговими компонентами, через підняття змін або зміни у визначенні версій.

Ізольовані встановлення зберігаються в {pnpmHomeDir}/global/v11/{hash}/, де hash формується від набору пакунків встановлених разом.

Наприклад, виконання цих команд:

pnpm add -g typescript
pnpm add -g prettier

призведе до створення двох ізольованих встановлень для пакунків typescript та prettier, кожен з яких отримує своє власне дерево node_modules, що не впливатиме на розвʼязання залежностей один одного та інших пакунків.

Installing multiple space-separated packages in a single command also creates a separate isolated install for each one:

pnpm add -g eslint prettier

eslint and prettier each get their own node_modules tree and lockfile and can be removed independently — pnpm remove -g eslint leaves prettier untouched.

To bundle multiple packages into the same isolated install — so they share a node_modules tree and lockfile, resolve peer dependencies against each other, and are removed together — pass them as a comma-separated list:

pnpm add -g eslint,prettier

Here eslint and prettier form a single install group. Removing either with pnpm remove -g removes the whole group.

The two forms can be mixed. Наприклад:

pnpm add -g eslint,prettier typescript

bundles eslint and prettier into one isolated install while installing typescript on its own.

Directory layout

The contents of {pnpmHomeDir}/global/v11/ look like:

{pnpmHomeDir}/global/v11/
├── {hash-A}              → symlink → ./{hash-A-target}/
├── {hash-A-target}/      ← isolated install dir
│   ├── package.json      ← lists the packages installed together
│   ├── pnpm-lock.yaml    ← lockfile for this install group
│   └── node_modules/
│       ├── <pkg>/        ← top-level dep, symlinked into the global virtual store
│       └── .pnpm/
├── {hash-B}              → symlink → ./{hash-B-target}/
├── {hash-B-target}/      ← another isolated install dir
└── store/                ← shared global virtual store
    └── ...

• The {hash} entries are symlinks; pnpm scans for them to enumerate active installs.
• The targets are real directories that act as ordinary pnpm projects — each has its own package.json and lockfile.
• The shared store/ directory holds the global virtual store. Each install group's direct dependencies — the entries at the root of its node_modules/ — are symlinks into that store, so the actual package contents are shared rather than copied per group.
• Bin shims live in {pnpmHomeDir}/bin/ and point through the appropriate install group's node_modules.

When a package is removed or its install group is replaced, the hash symlink is updated and orphaned target directories are eventually cleaned up by pnpm store prune.

Listing global packages

pnpm list -g
pnpm list -g --json        # machine-readable
pnpm list -g --parseable   # paths only

Because each install group has its own lockfile, listing across multiple groups can only reliably aggregate the top-level packages they were installed with — transitive dependency trees from different groups can't be coherently merged. As a result:

• pnpm list -g (default --depth=0) always works and shows every globally installed package.
• pnpm list -g --depth=<n> (with n > 0) shows the full dependency tree only when:
  • there is just one global install group, or
  • a positional argument narrows the request to a single install group, e.g. pnpm list -g eslint --depth=1.

If --depth>0 is requested but the request can't be narrowed to a single install group, pnpm errors with ERR_PNPM_GLOBAL_LS_DEPTH_NOT_SUPPORTED.

Управління глобальними пакунками

Команда	Опис
pnpm add -g <pkg>	Встановлює пакунок глобально
pnpm remove -g <pkg>	Remove a globally installed package (if it was bundled into an install group, the whole group is removed)
pnpm update -g [pkg]	Оновлює глобально встановлені пакунки (перевстановлює їх в ізольовані теки)
pnpm list -g	Виводить перелік глобально встановлених пакунків

нотатка

Команда pnpm install -g (без аргументів) не підтримується. Використовуйте pnpm add -g <pkg> для встановлення потрібних паккунків.

Розташування бінарних файлів

Глобально встановлені бінарні файли зберігаються у субтеці bin в PNPM_HOME (тобто в $PNPM_HOME/bin/). Це дозволяє теці PNPM_HOME залишатись охайною — внутрішні теки global/ та store/ не захаращують автодоповнення оболонки, коли тека PNPM_HOME є в змінній PATH.

Після оновлення до pnpm v11 виконайте pnpm setup для оновлення налаштувань вашої оболонки, щоб шлях $PNPM_HOME/bin був у вашому PATH.

Ви можете дізнатись шлях до глобальної теки bin наступним чином:

pnpm bin -g

Project-aware global bins

Added in: v12.0.0-rc.2 (pnpm v12 only)

Global commands can follow the project you are standing in. When you run a global command from inside a project that asks for a different version of the same tool, pnpm runs the version the project asks for.

The most useful case is Node.js itself. Given a project that pins its runtime:

package.json

{
  "devEngines": {
    "runtime": {
      "name": "node",
      "version": "^22.0.0",
      "onFail": "download"
    }
  }
}

a bare node inside that directory runs Node.js 22, even if your global Node.js is a different major:

cd ~/projects/legacy-app
node --version   # v22.x.x — the version the project pins
cd ~
node --version   # your globally installed version

No shell hooks, .bashrc edits, or use-style commands are involved — the shims pnpm writes into the global bin directory do the dispatch themselves.

How a version is chosen

pnpm walks up from the current working directory to the nearest project that provides the command, then:

• For the runtimes (node, deno, bun), only the manifest pin counts — devEngines.runtime, then engines.runtime. The pinned version is downloaded into the global virtual store on demand and executed directly. The project's node_modules/.bin is never consulted for a runtime, so a dependency cannot supply the node you run.
• For the package managers (npm, yarn, bun), added in v12.0.0-rc.6, the project's packageManager or devEngines.packageManager pin counts, and pnpm provisions that version on demand. The pin outranks a copy of that package manager installed globally, because it is the project's own statement of what installs it.
• For any other package, the project's node_modules/.bin/<name> is used.

Directories inside the pnpm home are skipped, since global installs are not projects.

If the project provides nothing, or the lookup is declined, the globally installed version runs — commands never fail merely because dispatch did not apply.

Trust

A project you cd into is not automatically allowed to run its own binaries in place of your global ones.

This section describes the default auto policy. Under auto:

• A stable Node.js release is verified against the Node.js release team's signatures before it runs, so it switches without asking. (On musl-based systems the matching builds are unsigned, so they fall under the prompt instead.)

• Everything else — Deno, Bun, Node.js prereleases, and any ordinary package you enable — asks once, per project and per candidate:

  The project at "/home/user/projects/app" provides its own "tsc", which will be used
  instead of the globally installed one.
  Do you trust this project? [y/N]

Answers are remembered in a machine-local registry, keyed to the project directory and to a fingerprint of the exact binary. If the binary or the providing package changes, pnpm asks again rather than reusing the old approval.

In CI and any non-interactive session, the question cannot be asked, so the global version runs and nothing is recorded.

The other two policies change which candidates reach that question. prompt sends every candidate through it, including a signature-verified stable Node.js release; answers are still remembered, so it asks once per project and candidate rather than on every run. always skips the question entirely and switches straight away — which is also what makes it usable in CI, where a prompt would otherwise fall back to the global version.

There is one more guard that applies regardless of policy: the project's command must come from the same package as the global one. A project that ships a lookalike tsc from some other package does not match, and your global tsc runs.

Which packages participate

Only the runtimes participate by default. Since v12.0.0-rc.6, installing a package manager globally (pnpm add -g yarn) also adds an entry for it, so it follows a project's pin the way a globally installed Node.js already follows devEngines.runtime. An entry you set yourself, including false, is left as you set it.

Enable others with globalShims, keyed by the providing package's name:

~/.config/pnpm/config.yaml

globalShims:
  typescript: true

Because pnpm decides at install time which bins to give dispatching shims, a package that is already installed globally needs to be reinstalled after you enable it:

pnpm add -g typescript

Turning a package off needs no reinstall — the setting is re-read on every dispatch. The same setting disables dispatch per package, or entirely with globalShims: false. For a single command, set PNPM_SHIM_BYPASS=1:

PNPM_SHIM_BYPASS=1 node --version

A package that is not installed globally at all can still get a dispatching command, with pnpm shim add — that is what makes yarn work inside a Yarn project on a machine that has only pnpm.

нотатка

globalShims is deliberately not read from a project's pnpm-workspace.yaml — only from the global configuration file, the pnpm home directory's own pnpm-workspace.yaml, and the environment. See the setting's documentation for details.

Глобальне віртуальне сховище

Глобальні встановлення використовуються глобальне віртуальне сховище. Пакунки зберігаються в {storeDir}/links та спільно використовуються поміж глобальними встановленнями. Це дозволяє уникнути зайвих завантажень, коли кілька глобальних пакунків залежать від одних і тих самих бібліотек.

Реєстрація локальних пакунків як глобальних

Щоб зробити бінарні файли локального пакунка доступними для всієї системи, виконайте команду pnpm add -g . в теці вашого пакунка:

cd ~/projects/my-tool
pnpm add -g .

Виконання команти призведе до реєстрації компонентів теки bin пакунка для виклику з будь-якого місця у системі. Див. pnpm link для отримання додаткової інформації.

Ухваленя скриптів збірки

Глобальні пакунки, що містять скрипти збірки (наприклад, postinstall), потребують ухвалення. Коли ви встановлюєте глобальний пакунок, який потребує запуску скриптів збірки, pnpm інтерактивно запропонує вам ухвалити або відхилити збірку.

Ви також можете попередньо ухвалити збірки, використовуючи прапорець --allow-build:

pnpm add -g --allow-build=esbuild esbuild