기타 설정

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할 때 특정 버전을 지정하지 않으면, 이 설정의 태그로 등록된 버전의 패키지가 설치됩니다.

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을 실행하여 셸 설정을 업데이트하세요.

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
- On macOS and 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로 설정하세요.

The patches are applied from Yarn's @yarnpkg/extensions package, plus pnpm's own curated entries.

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이 설치됩니다.
Subdependencies will be resolved from versions that were published no later than one hour after the newest direct dependency. If none of those versions satisfies a subdependency's range, pnpm installs the lowest version that does.

If minimumReleaseAge is also set, pnpm resolves subdependencies against whichever of the two cutoffs is earlier. If no version published before that cutoff satisfies a subdependency's range, pnpm installs the lowest matching version that is older than the minimumReleaseAge cutoff. If every matching version is newer than the minimumReleaseAge cutoff, pnpm falls back to the lowest matching version, and minimumReleaseAgeStrict decides whether pnpm installs it or fails. Only the minimumReleaseAge cutoff decides which versions pnpm reports as too new. A version that is newer than the time-based cutoff but older than the minimumReleaseAge cutoff is installed without a warning or error.

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

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

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

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)는 바이너리 자체 위치가 아닌 현재 작업 디렉터리에서 모듈을 해석합니다. Since the working directory is the project root, not the package inside the virtual store, the standard node_modules resolution from the CWD won't find the binary's transitive dependencies.

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

The package's own dependencies directory (e.g., .pnpm/pkg@version/node_modules). This allows CWD-based resolution to find the correct versions of the package's sibling dependencies.
The hoisted node_modules directory (e.g., .pnpm/node_modules). This is the directory where hoisted packages are placed when hoistPattern is set. Node.js는 표준 해석 알고리즘으로 이 디렉터리를 찾을 수 없으므로 NODE_PATH를 통해 제공해야 합니다.

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

Since v11.28.0, when a project uses a custom modulesDir, NODE_PATH also includes that directory, so a tool installed there can load CommonJS plugins installed next to it, the way it would from node_modules. When executables are symlinks (with preferSymlinkedExecutables or the hoisted linker), this applies to pnpm run, pnpm exec, pnpm version hooks, and the lifecycle scripts a project runs during install, but not to a symlinked tool started directly from a shell. A path that contains the platform's path-list separator (: or ;) does not get this fallback.

비활성화해야 하는 경우#

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

deployAllFiles#

기본값: false
유형: Boolean

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

dedupeDirectDeps#

기본값: false
타입: Boolean

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

optimisticRepeatInstall#

버전 10.1.0에서 추가됨

기본값: true
타입: Boolean

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

When the check finds that nothing changed, pnpm skips the install, including the projects' own lifecycle scripts, such as prepare. Set this to false to run those scripts on every install.

requiredScripts#

Scripts listed in this array are required in each project selected by pnpm -r run <script name>. Otherwise, the run fails.

pnpm-workspace.yaml

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"

Since v11.26.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#

기본값: false
유형: Boolean

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

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

package.json

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

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

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

참고

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 (기본값) - 의존성을 카탈로그에 자동으로 추가하지 않습니다.

Since v11.26.0, a specifier that names a location rather than a version is never moved into a catalog: local paths, local tarballs, tarball URLs, and workspace:<path> ranges stay in the package.json that declares them. Such a specifier is resolved relative to its own project, so one catalog entry could not mean the same directory for every project that references it.

ci#