npm install 권한 오류 해결기: EACCES, EEXIST, root-owned files 트러블슈팅

최근 TypeScript 프로젝트를 실행하기 위해 npm install을 진행했는데, 예상치 못한 권한 오류가 발생했다.
처음에는 단순한 설치 오류인 줄 알았지만, 확인해보니 프로젝트 자체 문제가 아니라 npm 캐시 폴더 권한 문제였다.

이번 글에서는 어떤 오류가 발생했는지, 원인이 무엇이었는지, 그리고 어떻게 해결했는지 정리해보려고 한다.

---

문제 상황

프로젝트 폴더에서 npm install을 실행했는데 다음과 같은 오류가 발생했다.

npm error code EEXIST
npm error syscall mkdir
npm error path /Users/imsungu/.npm/_cacache/content-v2/sha512/ee/b2
npm error errno -13
npm error EACCES: permission denied
npm error File exists

에러 메시지를 보면 핵심은 두 가지였다.

• EACCES: permission denied
• File exists

즉, npm이 필요한 캐시 디렉터리를 만들거나 수정하려고 했는데 권한이 없어서 실패한 상황이었다.

이후 추가 로그를 확인해보니 더 직접적인 원인이 나왔다.

Your cache folder contains root-owned files
To permanently fix this problem, please run:
sudo chown -R 501:20 "/Users/imsungu/.npm"

이 메시지를 보고 원인이 확실해졌다.
내 ~/.npm 폴더 안에 root 소유 파일이 남아 있었고, 그 때문에 일반 사용자 권한으로 npm install을 실행했을 때 충돌이 발생한 것이다.

---

원인 분석

이번 문제의 핵심 원인은 npm 캐시 폴더 권한 꼬임이었다.

npm은 설치 과정에서 캐시를 ~/.npm 경로 아래에 저장하는데, 이전에 어떤 이유로든 sudo를 사용해 npm 관련 명령을 실행하면 그 안에 일부 파일이 root 소유로 바뀔 수 있다.

그러면 이후 일반 사용자 계정으로 npm install을 실행했을 때 다음과 같은 문제가 생긴다.

• npm이 캐시 폴더를 생성하거나 수정하지 못함
• 기존 캐시를 삭제하지 못함
• 결국 EACCES, EEXIST 같은 오류가 발생함

즉, package.json 문제나 라이브러리 문제라기보다 내 Mac의 npm 캐시 권한 문제였다.

---

해결 시도

처음에는 아래 명령으로 해결해보려고 했다.

sudo chown -R $(whoami) ~/.npm
rm -rf ~/.npm/_cacache
npm cache verify
npm install

하지만 여기서 문제가 하나 더 있었다.
sudo 비밀번호 입력을 여러 번 틀려서, 소유권 변경 명령이 제대로 실행되지 않았다.

그 결과 rm -rf ~/.npm/_cacache를 실행할 때도 수많은 Permission denied가 발생했다.
즉, 권한 문제를 해결하지 않은 상태에서 캐시를 지우려고 해서 실패한 것이다.

---

최종 해결

이후 권한 문제를 정리한 뒤 다시 npm install을 실행했더니, 이번에는 정상적으로 설치가 완료되었다.

added 262 packages, and audited 263 packages in 6s

57 packages are looking for funding
  run `npm fund` for details

4 vulnerabilities (2 moderate, 2 high)

To address all issues, run:
  npm audit fix

이 문구가 떴다는 건 필요한 패키지들이 정상적으로 설치되었다는 뜻이다.

처음에 발생했던 에러는 프로젝트 문제 때문이 아니라, 사용자 홈 디렉터리의 npm 캐시 폴더 내부 권한이 꼬여 있었기 때문이었다.

---

이번 트러블슈팅에서 알게 된 점

이번 경험을 통해 느낀 점은, npm install 오류가 발생했다고 해서 무조건 프로젝트 파일이나 의존성 문제라고 생각하면 안 된다는 것이다.

특히 아래와 같은 키워드가 보이면 프로젝트보다 환경 문제를 먼저 의심해봐야 한다.

• EACCES
• permission denied
• root-owned files
• File exists
• ~/.npm/_cacache

즉, 설치 명령 자체보다 내 로컬 개발 환경의 권한 상태를 먼저 확인하는 것이 중요하다는 걸 배웠다.

---

재발 방지 방법

앞으로 같은 문제가 다시 생기지 않게 하기 위해서는 몇 가지를 주의해야 한다.

1. sudo npm install을 습관적으로 사용하지 않기

가장 중요한 부분이다.
sudo를 사용해서 npm 명령을 실행하면, 이후 캐시나 글로벌 패키지 경로에 root 소유 파일이 생길 수 있다.
그렇게 되면 나중에 일반 사용자 권한으로 작업할 때 다시 비슷한 문제가 발생할 수 있다.

2. 권한 오류가 나면 ~/.npm부터 의심하기

다음 경로는 npm 관련 권한 문제가 자주 발생하는 곳이다.

~/.npm
~/.npm/_cacache

설치 중 EACCES가 발생하면 이 경로의 권한 상태를 먼저 확인해보는 것이 좋다.

3. 설치 성공 후 보안 경고도 확인하기

설치는 성공했지만 아래와 같은 메시지도 함께 떴다.

4 vulnerabilities (2 moderate, 2 high)

이건 설치 실패는 아니지만, 의존성 패키지 중 취약점이 발견되었다는 의미다.
이 경우 아래 명령으로 점검할 수 있다.

npm audit
npm audit fix

즉, 설치가 끝났다고 해서 완전히 끝난 것이 아니라, 이후 보안 점검도 한 번 해보는 것이 좋다.

---

마무리

이번 오류는 처음엔 복잡해 보였지만, 결국 원인은 단순했다.

npm install이 실패한 이유는 프로젝트 문제가 아니라 ~/.npm 캐시 폴더 안에 root 권한 파일이 남아 있었기 때문이었다.
권한 문제가 정리된 뒤에는 같은 명령어가 정상적으로 실행되었다.

이번 일을 계기로, 앞으로 npm 오류가 발생하면 무조건 코드부터 의심하기보다 내 개발 환경의 권한과 캐시 상태도 함께 확인해야겠다는 걸 배웠다.

---

한 줄 요약하자면,
npm 설치 오류가 날 때는 프로젝트보다 먼저 내 로컬 환경의 권한 문제를 확인하자.