🚀 npm에서 pnpm으로 갈아탄 이유와 전환 과정

최근에 프로젝트에서 기존 npm에서 pnpm으로 패키지 매니저를 전환했다.

이 글은 “왜 바꿨는지”, “어떻게 바꿨는지”, 그리고 “전환 후 어떤 점이 좋았는지”를

예시와 함께 단계별로 정리한 아티클이다.

✅ 왜 pnpm을 써야 할까?

기존 npm을 쓰면서 겪은 불편함은 다음과 같다:

• 디스크 낭비

→ 같은 패키지를 여러 프로젝트에서 쓸 때마다 매번 복사됨

• 설치 속도 느림

→ 특히 node_modules를 지우고 다시 설치할 때는 시간 소모 큼

• 의존성 충돌 문제

→ 서브 패키지 간 의존성 버전 충돌로 인해 디버깅 어려움

 

그리고 pnpm은 이런 문제들을 이렇게 해결한다:

npm의 문제점	pnpm의 해결 방식
디스크 낭비	캐시 + 하드 링크를 통해 하나의 패키지만 저장
설치 속도 느림	캐시된 패키지를 바로 링크하므로 빠름
의존성 충돌날 수 있음	의존성 hoisting을 제한해 각 패키지가 독립적으로 관리됨

 

pnpm 에서는 심볼릭 링크와 하드링크를 사용한다.

 

🔁 기존 npm → pnpm 전환 과정 (단계별)

1. pnpm 설치

👉 전역으로 설치해서 어디서든 pnpm 명령어를 사용할 수 있게 한다.
npm install -g pnpm

설치 후 확인
pnpm -v

 

2. 기존 설치 파일 정리

👉 pnpm은 node_modules 구조가 npm과 완전히 다르기 때문에,
기존 파일이 남아있으면 충돌할 수 있다.

rm -rf node_modules
rm package-lock.json

왜 node_modules 와 package-lock.json 을 꼭 제거해야할까?


1-1. 패키지 매니저 간의 충돌

npm과 pnpm은 서로 다른 방식으로 의존성을 관리함.
npm은 package-lock.json을 사용하고, pnpm은 pnpm-lock.yaml을 사용함.
두 lock 파일이 동시에 존재하면 의존성 충돌이 발생할 수 있음!

1-2. 실제 예시

# 문제가 될 수 있는 상황의 프로젝트 구조를 보여주겠음.

project/
├── node_modules/          # npm으로 설치된 의존성
├── package.json
├── package-lock.json     # npm 잠금 파일
└── pnpm-lock.yaml         # pnpm 잠금 파일


2. 의존성 트리 재구성

2-1. npm의 의존성 구조

npm은 node_modules에 모든 패키지를 평면적으로 저장함.
패키지 호이스팅을 통해 중복을 줄이려고 시도함.

npm의 node_modules 구조:
node_modules/
├── package-a/
├── package-b/
└── package-c/


2-2. pnpm의 의존성 구조

pnpm은 하드 링크와 심볼릭 링크를 사용함.
전역 저장소를 활용하여 중복을 방지함.

pnpm의 node_modules 구조:
node_modules/
└── .pnpm/ # 실제 패키지 저장소
├── package-a@1.0.0/
├── package-b@2.0.0/
└── package-c@3.0.0/


3. 안정성 보장

3-1. 깨끗한 시작
기존 의존성 파일을 제거함으로써 깨끗한 상태에서 시작할 수 있음.
이전 설치 과정에서 발생했을 수 있는 문제나 오류를 제거함.

3.2 의존성 버전 일관성
모든 팀원이 동일한 의존성 버전을 사용할 수 있게 보장해줌.
pnpm-lock.yaml을 통해 정확한 버전을 관리할 수 있음.


4. 실제 발생할 수 있는 문제 예시

4-1. 의존성 충돌
# 문제 상황
TypeError: Cannot read property 'map' of undefined
# 원인: 서로 다른 패키지 매니저로 인한 버전 불일치

4-2. 버전 불일치
# 문제 상황
TypeError: Cannot read property 'map' of undefined
# 원인: 서로 다른 패키지 매니저로 인한 버전 불일치


기존 의존성 파일을 제거하는 것은 단순한 정리 작업이 아닌,
새로운 패키지 매니저로의 안전한 전환을 위한 필수적인 단계이다.
이를 통해 의존성 충돌을 방지할 수 있다.

 

3. pnpm으로 패키지 재설치

pnpm install

👉 기존 package.json을 기반으로 .pnpm 내부에 실제 패키지를 설치하고,
루트 node_modules에는 링크만 생성된다.

 

💡 실제 예시

기존 프로젝트에 react, axios 등을 설치한 상태였고

npm install로는 약 900MB 정도의 node_modules가 생성되었다.

pnpm으로 전환 후, 동일한 패키지를 설치했지만 실제 디스크 사용량은 절반 수준으로 감소.

설치 속도도 체감상 2배 이상 빨랐다.

 

🤔 왜 바꿨을까? 전환 이유 정리

• 개발 속도 개선

→ 매번 느리게 돌아가는 설치 속도에 지침…

• 디스크 절약

→ 여러 프로젝트를 동시에 작업하면서 node_modules 용량이 너무 부담스러움

• 협업 대비

→ pnpm-lock.yaml을 통해 더 엄격한 버전 고정 가능

• 모노레포 환경 대비

→ 앞으로 pnpm workspace를 써서 여러 프로젝트를 하나로 묶고 싶었음

 

📌 마무리

pnpm은 단순히 “더 빠르고 가벼운 패키지 매니저”가 아니다.

패키지 관리의 철학 자체를 바꿔준다.

지금도 npm을 쓰고 있다면, 한 번쯤 전환을 고려해보는 걸 추천한다.

 

✅ 다음 아티클에서는 pnpm workspace와 모노레포 구조까지 확장해볼 예정.