pnpm 버전을 업데이트했는데도 pnpm -v를 찍어보면 예전 버전이 나오는 경우가 있다. 터미널을 껐다 켜도 동일한 이슈가 발생하는데 pnpm의 경우에는 내부 corepack과 시스템 설정 우선순위가 달라서 살펴볼 필요가 있다. 시스템에 pnpm이 여러 개 설치되어 있을 수 있고, Corepack을 사용 중이라면 실제로 실행되는 pnpm이 내가 생각한 것과 다를 수 있다.
정리용으로 남기는 글이다.
1. 먼저 현재 잡히는 pnpm 확인하기
가장 먼저 할 일은 현재 터미널에서 어떤 pnpm이 실행되는지 확인하는 것이다.
pnpm -v
현재 실행되는 pnpm 버전을 확인한다.
which pnpm
현재 pnpm 명령어가 어느 경로의 실행 파일을 보고 있는지 확인한다.
type -a pnpm
type -a pnpm은 현재 셸에서 찾을 수 있는 pnpm 후보들을 모두 보여준다.
예를 들면 아래처럼 여러 개가 나올 수 있다.
pnpm is /Users/me/.nvm/versions/node/v22.11.0/bin/pnpm
pnpm is /opt/homebrew/bin/pnpm
pnpm is /usr/local/bin/pnpm
여기서 중요한 점은 가장 첫 줄에 나오는 pnpm이 실제로 실행되는 pnpm이다.
즉, 어딘가에는 pnpm 11이 설치되어 있어도 현재 셸의 PATH 우선순위상 pnpm 10이 먼저 잡히고 있다면 pnpm -v는 계속 10으로 나올 수 있다.
2. 왜 pnpm이 여러 개 잡힐까?
pnpm을 설치하는 방법은 여러 가지가 있다.
대표적으로는 아래 방식들이 있다.
npm install -g pnpm
corepack enable pnpm
brew install pnpm
그리고 Node.js 버전 매니저를 쓰고 있다면 Node.js 버전마다 전역 패키지 위치가 달라질 수도 있다.
즉, 시스템에는 아래와 같은 pnpm들이 동시에 존재할 수 있다.
Corepack이 제공하는 pnpm
npm으로 전역 설치한 pnpm
Homebrew로 설치한 pnpm
Node.js 버전별 global bin에 설치된 pnpm
이 중 어떤 pnpm이 실행되는지는 결국 PATH 우선순위에 따라 결정된다.
그래서 pnpm을 업데이트했는데도 버전이 바뀌지 않는다면, 실제로는 내가 업데이트한 pnpm이 아니라 다른 위치의 pnpm을 계속 실행하고 있는 상황일 수 있다.
3. Corepack이란?
Corepack은 pnpm이나 Yarn 같은 패키지 매니저를 프로젝트별로 관리할 수 있게 해주는 Node.js 도구다.
정확히는 pnpm 자체라기보다는, pnpm 명령어 앞에 있는 프록시 역할을 한다.
pnpm 명령 실행
→ Corepack 프록시가 먼저 동작
→ 현재 프로젝트의 package.json 확인
→ 어떤 pnpm 버전을 써야 하는지 판단
→ 필요한 pnpm 버전을 다운로드하거나 캐시에서 찾아 실행
즉, Corepack의 pnpm 프록시는 pnpm 명령을 가로채서 “이 프로젝트에서는 어떤 pnpm 버전을 써야 하지?”를 판단한 뒤 알맞은 pnpm을 실행해주는 중간 실행기라고 보면 된다.
Node.js 16.13 이후 버전부터는 Corepack이 같이 제공되는 경우가 많다. 다만 Corepack이 포함되어 있다고 해서 항상 바로 활성화되어 있지는 않아서 아래 명령어로 활성화한다.
corepack enable pnpm
주의할 점은 Node.js 25부터는 Corepack이 Node.js 기본 배포판에 포함되지 않는 방향으로 바뀐다고 하니 앞으로의 환경에서는 Corepack을 별도로 설치해야 할 수도 있다.
npm install -g corepack@latest
4. Corepack 사용 여부 확인하기
Corepack을 쓰는 환경인지 확인하려면 아래 명령어를 사용한다.
corepack --version
which corepack
Corepack을 통해 실행되는 pnpm 버전은 아래처럼 확인할 수 있다.
corepack pnpm -v
다만 이 명령어는 단순히 “Corepack의 전역 기본 pnpm 버전”만 보여준다고 생각하면 헷갈릴 수 있다.
프로젝트 내부에서 실행하면 Corepack은 현재 디렉터리 기준으로 가장 가까운 package.json을 찾고, 그 안의 packageManager 값을 먼저 확인한다.
예를 들어 package.json에 아래처럼 적혀 있다면,
{
"packageManager": "pnpm@11.1.3"
}
Corepack은 해당 프로젝트에서 pnpm 11.1.3을 쓰려고 한다.
반대로 명시된 packageManager가 없다면 Corepack은 프로젝트에서 원하는 pnpm 버전을 알 수 없다. 이 경우 Corepack이 알고 있는 기본 버전이나, 이미 활성화된 pnpm 버전이 실행될 수 있다.
5. 프로젝트에서 pnpm 버전 고정하기
팀 프로젝트에서 pnpm 버전을 맞추고 싶다면 package.json의 packageManager 속성을 사용하는 것이 좋다.
예를 들어 현재 프로젝트에서 pnpm 11을 쓰고 싶다면 아래 명령어를 실행한다.
corepack use pnpm@latest-11
특정 버전을 정확히 지정할 수도 있다.
corepack use pnpm@11.1.3
이 명령어를 실행하면 현재 프로젝트의 package.json에 packageManager 속성이 추가되거나 갱신된다.
예시:
{
"packageManager": "pnpm@11.1.3"
}
이렇게 해두면 Corepack을 사용하는 팀원들은 해당 프로젝트에서 같은 pnpm 버전을 사용하게 된다.
핵심은 pnpm 버전도 의존성처럼 프로젝트에 명시해두는 것이다.
pnpm-lock.yaml만 맞춘다고 해서 항상 같은 결과가 나온다고 보기 어렵다. pnpm 자체의 버전이 다르면 lockfile 처리 방식이나 지원 기능이 달라질 수 있기 때문이다.
6. 프로젝트 밖에서 사용할 기본 pnpm 버전 설정하기
프로젝트 내부가 아니라, 프로젝트 밖에서 기본으로 사용할 pnpm 버전을 Corepack 기준으로 바꾸고 싶다면 아래 명령어를 사용할 수 있다.
corepack install --global pnpm@latest-11
또는 특정 버전을 지정할 수 있다.
corepack install --global pnpm@11.1.3
이 명령은 시스템에 직접 pnpm을 전역 설치하는 것과는 다르다.
정확히는 Corepack이 프로젝트 밖에서 pnpm을 실행할 때 사용할 기본 버전을 설정하는 것에 가깝다.
# 프로젝트의 package.json에 pnpm 버전 명시
corepack use pnpm@latest-11
# Corepack이 프로젝트 밖에서 사용할 기본 pnpm 버전 설정
corepack install --global pnpm@latest-11
정리하면 다음과 같다.
프로젝트별 pnpm 버전을 고정하고 싶다
→ corepack use pnpm@버전
프로젝트 밖에서 기본으로 쓸 Corepack pnpm 버전을 바꾸고 싶다
→ corepack install --global pnpm@버전
7. Corepack을 쓰지 않고 pnpm을 전역 설치하는 경우
Corepack을 쓰지 않고 pnpm을 직접 전역 설치할 수도 있다.
npm install -g pnpm@latest-11
이 경우 시스템 PATH 기준으로 pnpm 실행 파일이 잡힌다.
하지만 이미 Corepack이 활성화되어 있다면, 내가 npm으로 전역 설치한 pnpm보다 Corepack의 pnpm shim이 먼저 잡힐 수 있다.
그래서 전역 설치를 했는데도 버전이 바뀌지 않는다면 다시 아래를 확인해야 한다.
which pnpm
type -a pnpm
Corepack을 아예 사용하지 않을 생각이라면 비활성화할 수 있다.
corepack disable
또는 pnpm만 대상으로 비활성화할 수도 있다.
corepack disable pnpm
다만 팀 프로젝트에서 패키지 매니저 버전까지 맞추고 싶다면 Corepack을 끄는 것보다, Corepack을 활성화하고 프로젝트의 packageManager를 명시하는 쪽이 더 안정적이다.
개인 프로젝트라면 없어도 큰 문제가 없을 수 있지만 팀 프로젝트에서는 없는 것보다 있는 편이 좋다. packageManager가 없으면 각자 시스템에 설치된 pnpm 버전을 쓰게 될 수 있는데 어떤 사람은 pnpm 9, 어떤 사람은 pnpm 10, 어떤 사람은 pnpm 11을 쓰는 상황이 생긴다. 결과적으로 lockfile 변경이 불필요하게 생기거나, 특정 명령이 어떤 환경에서는 되고 어떤 환경에서는 안 되는 문제가 생길 수 있다.
8. 정리
pnpm을 업데이트했는데도 예전 버전이 나오는 이유는 보통 아래 중 하나다.
1. PATH 우선순위상 예전 pnpm이 먼저 잡히고 있다.
2. Corepack의 pnpm shim이 실행되고 있다.
3. 현재 프로젝트의 package.json에 packageManager가 예전 버전으로 고정되어 있다.
4. 프로젝트 밖에서 Corepack 기본 pnpm 버전이 예전 버전으로 설정되어 있다.
5. Node.js 버전이 pnpm 최신 버전을 지원하지 않는다.
핵심은 단순히 “pnpm을 설치했다”가 아니라, 현재 터미널에서 어떤 pnpm이 실행되고 있는지를 확인하는 것이다.
개인적으로는 팀 프로젝트에서는 Corepack을 활성화하고, 프로젝트마다 packageManager를 명시하는 방식이 가장 낫다고 생각한다.
{
"packageManager": "pnpm@11.1.3"
}
이렇게 해두면 프로젝트를 받은 사람이 별도로 pnpm 버전을 맞추지 않아도 Corepack이 해당 버전을 찾아 실행해준다.
즉, Corepack을 쓰면 pnpm을 단순히 전역 설치해서 쓰는 것이 아니라, 프로젝트별로 pnpm 버전까지 관리하는 구조가 된다.
결론:
전역 pnpm 하나로 모든 프로젝트를 처리하고 싶다
→ npm install -g pnpm
프로젝트별 pnpm 버전까지 재현성 있게 맞추고 싶다
→ corepack + packageManager
팀 프로젝트라면 후자가 더 안전하다.