전역 패키지

전역 패키지는 pnpm add -g로 시스템 전체에 설치되는 CLI 도구와 유틸리티입니다. 새로운 pnpm v11에서는 더 나은 격리와 안정성을 위해 전역 패키지 관리가 새롭게 설계되었습니다.

전역 패키지 설치하기#

pnpm add -g <pkg>

예시:

pnpm add -g typescript prettier eslint

격리된 설치#

전역으로 설치된 각 패키지(또는 함께 설치된 패키지 그룹)는 자체 package.json, node_modules/, lockfile을 가진 격리된 설치 디렉터리를 갖습니다. 이를 통해 피어 종속성 충돌, 호이스팅 변경, 버전 해석 변화로 인해 전역 패키지끼리 서로 간섭하는 것을 방지합니다.

격리된 설치는 {pnpmHomeDir}/global/v11/{hash}/에 저장되며, 여기서 hash는 함께 설치된 패키지 집합에서 도출됩니다.

예를 들어, 다음 두 명령을 실행하면:

pnpm add -g typescript
pnpm add -g prettier

creates two separate isolated installations. typescript and prettier each get their own node_modules tree and cannot affect each other's dependency resolution.

한 명령에서 공백으로 구분된 여러 패키지를 설치해도 각 패키지마다 별도의 격리 설치가 생성됩니다:

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

여기서 eslint와 prettier는 하나의 설치 그룹을 이룹니다. 둘 중 하나를 pnpm remove -g로 제거하면 그룹 전체가 제거됩니다.

pnpm add -g <pkg> replaces every existing group that contains <pkg>. After pnpm add -g eslint, the eslint,prettier group is gone, and so are prettier and its bins. To keep the group, add it again as a whole (pnpm add -g eslint,prettier), or use pnpm update -g.

두 형식을 섞어 쓸 수도 있습니다. 예시:

pnpm add -g eslint,prettier typescript

위 명령은 eslint와 prettier를 하나의 격리 설치로 묶고, typescript는 따로 설치합니다.

디렉터리 구조#

디렉터리 {pnpmHomeDir}/global/v11/의 내용은 다음과 같습니다:

{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/        ← the group's install state
├── {hash-B}              → symlink → ./{hash-B-target}/
└── {hash-B-target}/      ← another isolated install dir

• 각 {hash} 항목은 심볼릭 링크이며, pnpm은 이를 스캔하여 활성 설치 목록을 만듭니다.
• The targets are real directories that act as ordinary pnpm projects. Each has its own package.json and lockfile.
• By default, the package contents live in the global virtual store at {storeDir}/links, outside this directory. Each install group's direct dependencies (the entries at the root of its node_modules/) are symlinks into that store, so install groups that depend on the same package share one copy. With virtualStoreType: project, each install group keeps its packages in its own node_modules/.pnpm.
• 실행 파일 shim은 {pnpmHomeDir}/bin/에 있으며 해당 설치 그룹의 node_modules를 거쳐 실행 파일을 가리킵니다.

When a package is removed or its install group is replaced, the hash symlink is updated. Orphaned target directories older than five minutes are removed at the start of the next pnpm add -g, pnpm update -g, or pnpm self-update.

전역 패키지 목록 보기#

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. 그 결과:

• pnpm list -g(기본값 --depth=0)는 항상 작동하며 전역으로 설치된 모든 패키지를 보여줍니다.
• pnpm list -g --depth=<n>(n > 0인 경우)는 다음 경우에만 전체 종속성 트리를 보여줍니다:
  • 전역 설치 그룹이 하나뿐인 경우, 또는
  • 위치 인수로 요청을 단일 설치 그룹으로 좁힌 경우. 예: pnpm list -g eslint --depth=1.

--depth>0을 요청했지만 단일 설치 그룹으로 좁힐 수 없으면 pnpm은 ERR_PNPM_GLOBAL_LS_DEPTH_NOT_SUPPORTED 오류를 발생시킵니다.

전역 패키지 관리하기#

바이너리 위치#

전역으로 설치된 바이너리는 PNPM_HOME의 bin 하위 디렉터리(즉, $PNPM_HOME/bin/)에 저장됩니다. This keeps the PNPM_HOME directory clean. Internal directories like global/ and store/ don't pollute shell autocompletion when PNPM_HOME is on PATH.

버전 v11로 pnpm을 업그레이드한 후에는 pnpm setup을 실행하여 $PNPM_HOME/bin이 PATH에 포함되도록 셸 설정을 업데이트하세요.

현재 전역 bin 디렉터리는 다음 명령으로 확인할 수 있습니다:

pnpm bin -g

전역 가상 스토어#

전역 설치는 전역 가상 스토어를 사용합니다. 패키지는 {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

Since v11.24.0, pnpm approve-builds --global lets you decide after the fact instead. It collects the packages awaiting approval from every install group, asks about them once, and writes one allowBuilds policy into the pnpm-workspace.yaml of the global packages directory, then rebuilds only the groups that contain something you approved:

pnpm approve-builds -g