기타 설정

savePrefix#

기본값: '^'
유형: '^', '~', '', '='

package.json 파일에 설치되는 패키지 버전에 붙는 접두사를 설정합니다.

예를 들어, 패키지 버전이 1.2.3이면 기본적으로 해당 패키지의 마이너 업그레이드를 허용하는 ^1.2.3으로 설정되지만, pnpm config set save-prefix='~'를 실행한 후에는 패치 업그레이드만 허용하는 ~1.2.3으로 설정됩니다.

버전 v11.19.0부터는 =도 허용됩니다: 새로 추가된 종속성은 명시적인 = 연산자(=1.2.3)와 함께 저장되어 정확한 버전으로 고정됩니다. pnpm update는 이렇게 고정된 버전을 업데이트할 때 = 연산자를 유지합니다.

추가하는 패키지에 버전 범위가 지정된 경우 이 설정은 무시됩니다. 예를 들어, pnpm add foo@2를 실행하면 foo의 버전이 package.json에서 2로 설정되며, 이는 savePrefix 값과 관계없습니다.

tag#

기본값: latest
유형: String

패키지를 pnpm add할 때 특정 버전을 지정하지 않으면, 이 설정의 태그로 등록된 버전의 패키지가 설치됩니다.

또한 명시적인 태그가 주어지지 않은 경우, 이 설정은 package@version에 pnpm tag 명령으로 추가되는 태그도 지정합니다.

globalDir#

기본값:
- 환경 변수 $XDG_DATA_HOME이 설정된 경우 $XDG_DATA_HOME/pnpm/global
- Windows에서: ~/AppData/Local/pnpm/global
- Apple macOS에서: ~/Library/pnpm/global
- Linux에서: ~/.local/share/pnpm/global
유형: path

전역 패키지를 저장할 사용자 지정 디렉터리를 지정합니다.

globalBinDir#

기본값:
- 환경 변수 $XDG_DATA_HOME이 설정된 경우 $XDG_DATA_HOME/pnpm/bin
- Windows에서: ~/AppData/Local/pnpm/bin
- Apple macOS에서: ~/Library/pnpm/bin
- Linux에서: ~/.local/share/pnpm/bin
유형: path

전역으로 설치된 패키지의 bin 파일이 위치할 대상 디렉터리를 설정할 수 있습니다.

팁

이제 pnpm v11에서는 전역으로 설치된 바이너리가 bin 하위 디렉터리에 저장되는데, 이 디렉터리는 PNPM_HOME 안에 있으며 바이너리가 PNPM_HOME에 직접 저장되지는 않습니다. 이렇게 하면 global/, store/ 같은 내부 디렉터리가 PNPM_HOME이 PATH에 있을 때 셸 자동 완성을 어지럽히는 것을 방지할 수 있습니다. 업그레이드한 후에는 pnpm setup을 실행하여 셸 설정을 업데이트하세요.

globalShims#

추가된 버전: v12.0.0-rc.2

기본값: { node: auto, deno: auto, bun: auto }
유형: Boolean, Object

어떤 전역 설치 패키지에 프로젝트 인식 shim을 제공할지 제어합니다 — 전역으로 설치된 버전 대신 현재 프로젝트가 요구하는 버전을 실행하는 전역 명령입니다.

이 설정은 패키지 이름을 정책에 매핑하는 맵입니다. 키는 명령 자체가 아니라 명령을 제공하는 패키지의 이름이므로, typescript 항목은 해당 패키지의 tsc bin에 적용됩니다.

globalShims:
  node: auto
  deno: false
  typescript: prompt

지원되는 정책은 다음과 같습니다:

값	동작
`auto`(또는 `true`)	후보가 게시자 서명으로 인증되면 자동으로 전환하고, 그렇지 않으면 한 번 확인을 요청합니다.
`prompt`	서명이 검증된 후보를 포함하여 모든 후보에 대해 확인 절차를 거칩니다. 응답은 여전히 기억되므로, 매 실행마다가 아니라 프로젝트와 후보별로 한 번만 묻습니다.
`always`	항상 전환하며, 묻지 않습니다. 프롬프트가 전역 버전으로 대체되는 CI에서 사용할 수 있습니다.
`false`	이 패키지에 대한 프로젝트 인식 shim을 비활성화합니다.

버전 v12.0.0-rc.6부터는 두 명령이 이곳에 항목을 자동으로 기록합니다: pnpm shim add <pkg>는 shim을 연결하는 패키지를 기록하고, 패키지 관리자를 전역으로 설치하면(pnpm add -g yarn) 해당 패키지 관리자가 프로젝트의 고정 버전을 따르도록 기록됩니다. 두 명령 모두 직접 설정한 항목은 덮어쓰지 않습니다 — false를 포함하여, 모든 shim을 끄는 globalShims: false도 마찬가지입니다.

각 레이어는 내장 기본값 위에 키 단위로 병합되므로, 하나의 항목만으로 나머지를 다시 지정하지 않고 한 패키지를 변경할 수 있습니다 — globalShims: { bun: false }는 node와 deno를 auto로 유지합니다.

스칼라 축약형은 병합하지 않고 전체 맵을 대체합니다: globalShims: false는 모든 프로젝트 인식 shim을 비활성화하고, globalShims: true는 기본값으로 재설정합니다.

경고

이 설정은 프로젝트가 쓸 수 없는 위치에서만 읽습니다: 전역 설정 파일, pnpm 홈 디렉터리 자체에 있는 pnpm-workspace.yaml, 그리고 PNPM_CONFIG_GLOBAL_SHIMS 환경 변수(JSON 값)이며, 이 순서대로 적용됩니다. 프로젝트 자체의 pnpm-workspace.yaml은 무시됩니다 — 그렇지 않으면 저장소가 전역 바이너리 대신 자체 바이너리를 실행할 권한을 스스로 부여할 수 있기 때문입니다.

패키지를 비활성화하거나 정책을 변경하면 바로 다음 명령부터 적용됩니다 — 설정은 디스패치할 때마다 다시 읽히므로 재설치할 필요가 없습니다.

패키지를 새로 활성화하는 경우는 예외입니다. pnpm은 설치 시점에 어떤 bin에 대해 디스패치 shim을 작성할지 결정하므로, 비활성화된 상태에서 이미 전역으로 설치된 패키지는 변경 사항을 반영하려면 다시 설치해야 합니다:

pnpm add -g typescript

한 번의 호출에 대해서만 디스패치를 우회하려면 PNPM_SHIM_BYPASS=1을 설정하세요:

PNPM_SHIM_BYPASS=1 node --version

참고

프로젝트 인식 shim은 pnpm v12 기능이며 v11에서는 사용할 수 없습니다.

npmrcAuthFile#

추가된 버전: v11.0.0

기본값: ~/.npmrc
유형: path

레지스트리 인증 토큰이 들어 있는 파일의 경로입니다. 기본적으로 pnpm은 레지스트리 인증의 대체 수단으로 ~/.npmrc에서 인증 토큰을 읽습니다. 다른 파일을 사용하려면 이 설정으로 지정하세요.

이 설정은 프로젝트 수준의 pnpm-workspace.yaml에서는 설정할 수 없습니다; 전역 설정 파일, --npmrc-auth-file CLI 옵션 또는 PNPM_CONFIG_NPMRC_AUTH_FILE 환경 변수를 통해 설정하세요(npm 스타일의 NPM_CONFIG_USERCONFIG도 대체 수단으로 인정됩니다). 상대 경로는 작업 디렉터리를 기준으로 해석됩니다.

stateDir#

기본값:
- 환경 변수 $XDG_STATE_HOME이 설정된 경우 $XDG_STATE_HOME/pnpm
- Windows에서: ~/AppData/Local/pnpm-state
- Apple macOS에서: ~/.pnpm-state
- Linux에서: ~/.local/state/pnpm
유형: path

현재 업데이트 확인 기능에서만 사용되는 pnpm-state.json 파일을 pnpm이 생성하는 디렉터리입니다.

cacheDir#

기본값:
- 환경 변수 $XDG_CACHE_HOME이 설정된 경우 $XDG_CACHE_HOME/pnpm
- Windows에서: ~/AppData/Local/pnpm-cache
- Apple macOS에서: ~/Library/Caches/pnpm
- Linux에서: ~/.cache/pnpm
유형: path

캐시의 위치입니다(패키지 메타데이터, dlx 캐시 및 일부 설치 검증 결과).

스토어와 마찬가지로, 캐시 디렉터리는 상호 신뢰하는 사용자, 작업, 프로세스 간에만 공유하도록 설계되었습니다. 공유 cacheDir를 구성하거나 복원하는 경우, 신뢰할 수 없는 사용자가 쓸 수 없도록 파일 시스템 권한으로 보호하세요.

useStderr#

기본값: false
타입: Boolean

값이 true이면 모든 출력이 stderr에 기록됩니다.

updateNotifier#

기본값: true
타입: Boolean

최신 버전보다 오래된 pnpm을 사용할 때 업데이트 알림을 표시하지 않으려면 false로 설정하세요.

preferSymlinkedExecutables#

기본값: true, 단 node-linker가 hoisted로 설정되어 있고 시스템이 POSIX인 경우
타입: Boolean

명령 shim 대신 node_modules/.bin에 실행 파일에 대한 심볼릭 링크를 생성합니다. 명령 shim만 작동하는 Windows에서는 이 설정이 무시됩니다.

ignoreCompatibilityDb#

기본값: false
타입: Boolean

설치 중에 일부 패키지의 종속성은 자동으로 패치됩니다. 이 기능을 비활성화하려면 이 설정을 true로 설정하세요.

패치는 Yarn의 @yarnpkg/extensions 패키지에서 적용됩니다.

resolutionMode#

기본값: highest (v8.0.0부터 v8.6.12까지는 lowest-direct)
유형: highest, time-based, lowest-direct

resolutionMode가 time-based로 설정되면 종속성은 다음과 같이 해석됩니다:

직접 종속성은 가장 낮은 버전으로 해석됩니다. 따라서 종속성에 foo@^1.1.0이 있으면 1.1.0이 설치됩니다.
하위 종속성은 마지막 직접 종속성이 게시되기 전에 게시된 버전 중에서 해석됩니다.

이 해석 모드를 사용하면 캐시가 준비된 상태에서의 설치가 더 빨라집니다. 또한 하위 종속성은 직접 종속성이 업데이트될 때만 업데이트되므로 하위 종속성 하이재킹 가능성도 줄어듭니다.

이 해석 모드는 npm의 full metadata에서만 작동합니다. 따라서 일부 상황에서는 더 느립니다. 하지만 Verdaccio v5.15.1 이상을 사용하는 경우 registrySupportsTimeField 설정을 true로 설정하면 매우 빨라집니다.

resolutionMode가 lowest-direct로 설정되면 직접 종속성은 가장 낮은 버전으로 해석됩니다.

여기서는 package.json에 선언된 종속성만 직접 종속성으로 간주됩니다. 피어 종속성 중 autoInstallPeers가 추가하는 것은 프로젝트가 선언한 것이 아니므로 하위 종속성처럼 해석됩니다: 피어 범위를 만족하는 가장 높은 버전으로, 또는 time-based에서는 게시 날짜 기준 내에서 가장 높은 버전으로 해석됩니다.

registrySupportsTimeField#

기본값: false
타입: Boolean

사용 중인 레지스트리가 축약된 메타데이터에서 "time" 필드를 반환하는 경우 이 값을 true로 설정하세요. Verdaccio는 v5.15.1부터 이를 지원하며, 일부 레지스트리 프록시도 지원합니다.

버전 v11.23.0부터는 레지스트리별로도 선언할 수 있으며, supportsTimeField 필드가 있는 레지스트리 선언을 통해 선언합니다. 레지스트리 자체의 선언이 우선하며, 이 설정은 프로젝트가 설명하지 않는 모든 레지스트리에 적용됩니다.

extendNodePath#

기본값: true
타입: Boolean

값이 true이면 pnpm은 NODE_PATH 환경 변수를 명령 shim(node_modules/.bin에 생성되는 래퍼 스크립트)에 설정합니다. 값이 false이면 NODE_PATH가 설정되지 않습니다.

필요한 이유#

pnpm의 isolated node_modules layout은 패키지가 자신이 선언한 종속성에만 접근할 수 있음을 의미합니다. 하지만 CLI 도구가 명령 shim을 통해 실행될 때, 일부 라이브러리(특히 jest, eslint 등에서 사용하는 import-local)는 바이너리 자체 위치가 아닌 현재 작업 디렉터리에서 모듈을 해석합니다. 작업 디렉터리는 프로젝트 루트이므로 — 가상 스토어 내부의 패키지가 아니라 — CWD에서 시작하는 표준 node_modules 해석으로는 바이너리의 전이 종속성을 찾을 수 없습니다.

이 차이를 메우기 위해 pnpm은 NODE_PATH에 두 가지 유형의 경로를 포함합니다:

패키지 자체의 종속성 디렉터리 (예를 들어, .pnpm/pkg@version/node_modules) — CWD 기반 해석이 패키지의 형제 종속성의 올바른 버전을 찾을 수 있게 합니다.
호이스팅된 node_modules 디렉터리 (예를 들어, .pnpm/node_modules) — hoistPattern이 설정되었을 때 호이스팅된 패키지가 배치되는 디렉터리입니다. Node.js는 표준 해석 알고리즘으로 이 디렉터리를 찾을 수 없으므로 NODE_PATH를 통해 제공해야 합니다.

NODE_PATH는 enableGlobalVirtualStore가 활성화된 경우에도 필수입니다. 전역 가상 스토어를 사용하면 패키지가 프로젝트 외부의 중앙 위치에서 심볼릭 링크되므로, 바이너리의 실제 경로에서 상위로 올라가는 Node.js의 표준 node_modules 탐색으로는 프로젝트 자체의 node_modules나 호이스팅된 종속성에 도달할 수 없습니다. 이 경우 올바른 해석을 위해 NODE_PATH에는 프로젝트의 루트 node_modules와 node_modules/.pnpm/node_modules에 있는 호이스팅 디렉터리가 모두 포함되어야 합니다.

비활성화해야 하는 경우#

프로젝트의 CLI 도구 중 작업 디렉터리에서 모듈을 해석하는 것이 하나도 없고 전역 가상 스토어를 사용하지 않는다고 확신한다면 이 값을 false로 설정해도 됩니다. 비활성화하면 명령 shim이 약간 더 단순해집니다.

deployAllFiles#

기본값: false
타입: Boolean

패키지를 배포하거나 로컬 패키지를 설치할 때 패키지의 모든 파일이 복사됩니다. 기본적으로 "files" 필드가 패키지의 package.json에 있으면, 나열된 파일과 디렉터리만 복사됩니다.

dedupeDirectDeps#

기본값: false
타입: Boolean

값을 true로 설정하면 워크스페이스의 루트 node_modules 디렉터리에 이미 심볼릭 링크된 종속성은 하위 프로젝트의 node_modules 디렉터리에 심볼릭 링크되지 않습니다.

optimisticRepeatInstall#

버전 10.1.0에서 추가됨

기본값: true
타입: Boolean

활성화하면 설치를 진행하기 전에 빠른 검사가 수행됩니다. 이렇게 하면 반복 설치나 모든 것이 최신 상태인 프로젝트에서의 설치가 훨씬 빨라집니다.

requiredScripts#

이 배열에 나열된 스크립트는 workspace의 각 프로젝트에 필요합니다. 그렇지 않으면 pnpm -r run <script name> 명령이 실패합니다.

requiredScripts:
- build

enablePrePostScripts#

기본값: true
유형: Boolean

true이면 pnpm은 모든 pre/post 스크립트를 자동으로 실행합니다. 따라서 pnpm foo를 실행하는 것은 pnpm prefoo && pnpm foo && pnpm postfoo를 실행하는 것과 같습니다.

scriptShell#

기본값: null
유형: path

pnpm run 명령으로 실행하는 스크립트에 사용할 셸입니다.

예를 들어, Windows에서 Git Bash를 사용하도록 강제하려면:

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

shellEmulator#

기본값: false
유형: Boolean

값이 true이면 pnpm은 bash-like shell의 JavaScript 구현을 사용하여 스크립트를 실행합니다.

이 옵션은 플랫폼 간 스크립팅을 단순화합니다. 예를 들어, 기본적으로 다음 스크립트는 POSIX 규격이 아닌 시스템에서 실패합니다.

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

하지만 shellEmulator 설정을 true로 지정하면 모든 플랫폼에서 동작합니다.

참고

Node.js 22 이상에서는 pnpm의 도움 없이 스크립트를 실행할 수 있습니다. 위 예시의 경우 test 스크립트를 node --run test로 실행할 수 있습니다. 하지만 shellEmulator 옵션은 이 경우에 아무런 영향을 주지 않습니다. POSIX 기능에 의존하는 스크립트를 POSIX 규격이 아닌 환경에서 동작시키려면 pnpm run으로 실행해야 하며, node --run으로는 실행할 수 없습니다.

catalogMode#

버전 10.12.1에서 추가됨

기본값: manual
유형: manual, strict, prefer

pnpm add를 실행할 때 종속성을 기본 카탈로그에 추가할지 여부와 추가 방식을 제어합니다. 세 가지 모드가 있습니다:

strict - 카탈로그의 종속성 버전만 허용합니다. 카탈로그의 버전 범위를 벗어난 종속성을 추가하면 오류가 발생합니다.
prefer - 카탈로그 버전을 우선하지만, 호환되는 버전을 찾지 못하면 직접 종속성으로 대체합니다.
manual (기본값) - 종속성을 카탈로그에 자동으로 추가하지 않습니다.

ci#