npm 전역 설치 시 EACCES 권한 오류 — sudo 없이 해결 방법

검증 환경

본 절은 원문 사례·문서에 등장한 버전/도구를 정리한 것이다. 별도 실험실 재현이 명시되지 않은 항목은 일반화하지 않는다.

• OS/CI 세부 값은 프로젝트마다 다르므로, 적용 전 로컬에서 동일 오류 메시지를 재확인한다.

npm으로 패키지를 검색하거나 전역 설치할 때 EACCES 오류가 반복된다면, 권한 때문이다. 이 글은 이 에러의 원인을 파악하고 sudo를 쓰지 않고 안전하게 해결하는 방법을 분기 방식으로 정리한다.

1. 문제 정의

에러 원문: npm ERR! Error: EACCES, open '/Users/chietala/.npm/-/all/.cache.json' 출처: StackOverflow 16151018

npm 설치 후 npm search나 npm install -g 같은 명령을 실행하면 TypeError 없이 아래처럼 파일을 열 수 없는 권한 오류가 난다.

1
2
3
4
5

npm ERR! Error: EACCES, open '/Users/chietala/.npm/-/all/.cache.json'
npm ERR! { [Error: EACCES, open '/Users/chietala/.npm/-/all/.cache.json']
npm ERR!   errno: 3,
npm ERR!   code: 'EACCES',
npm ERR!   path: '/Users/chietala/.npm/-/all/.cache.json' }

핵심 요소는 다음과 같다.

일반적인 점검 기준: 이 글의 진단 명령은 OS/셸에 따라 출력이 달라질 수 있으며, 사용자 홈 디렉토리 구성은 환경마다 다를 수 있다.

2. 먼저 확인할 것

본격적인 해결 전에 다음 세 가지를 확인한다. 권한 오류는 원인이 몇 갈래로 갈리기 때문에 눈치로 넘어가지 말고 명령으로 확인하는 것이 빠르다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 1. npm이 지금 바라보는 전역 접두사 경로
npm config get prefix

# 2. 문제가 되는 디렉토리의 소유자/권한
ls -ld ~/.npm
ls -ld "$(npm config get prefix)"

# 3. npm 자체 버전 확인
npm -v
node -v

3. 원인(근본 원인) 분석

EACCES는 OS가 “이 경로는 쓰기 불가"라고 거부한 상태를 의미한다. npm이 패키지를 설치하려는 전역 경로에 쓰기 권한이 없기 때문에 발생한다.

표면 증상은 “npm이 에러를 낸다"지만, 근본 원인은 npm의 전역 설치 경로와 사용자의 쓰기 권한 경로가 일치하지 않는 것이다. 명령어가 Admin 권한이라도 사용자 계정의 홈 디렉토리를 벗어난 시스템 경로는 쓰기 권한이 거부된다.

다른 에러(ENOENT, EPERM)와는 다르게 EACCES는 파일이 없는 것이 아니라 권한만 거부된 것이므로, 문제는 비교적 명확하다.

원인 후보(매트릭스)

이 구조를 미리 알면 어떤 상황에서도 다음 4단계 분기에 그대로 적용할 수 있다.

4. 코드 해결책 (원인별 분기)

분기 1: prefix가 /usr 인가? → 전역 경로를 홈으로 옮기기 (권장, 안전)

먼저 npm config get prefix에서 /usr가 나오면 chown/chmod 대신 전역 경로를 사용자 홈으로 옮기는 것이 안전하다. 이 방식은 시스템 디렉토리를 손대지 않으므로 보안 위험이 없다.

1
2
3
4
5
6
7
8

# 1) 전역 설치용 홈 디렉토리 생성
mkdir ~/.npm-global

# 2) npm 전역 경로를 홈 디렉토리로 지정
export NPM_CONFIG_PREFIX=~/.npm-global

# 3) 실행 바이너리가 들어 있도록 PATH에 추가
export PATH=$PATH:~/.npm-global/bin

이 변경을 영구적으로 유지하려면 .bashrc에 추가한다.

1
2
3
4

echo -e "export NPM_CONFIG_PREFIX=~/.npm-global\nexport PATH=\$PATH:~/.npm-global/bin" >> ~/.bashrc

# 현재 셸에도 적용
source ~/.bashrc

이제 다시 전역 설치를 시도한다.

1

npm install -g <package-name>

분기 2: 홈 아래 ~/.npm 소유권이 깨진 경우

~/.npm 아래 캐시 디렉토리가 다른 사용자 소유로 되어있으면 해당 디렉토리만 소유권을 되돌린다. macOS/Linux에서 일반적으로 chown을 사용하되 시스템 경로가 아닌 홈 안의 사용자 폴더에만 적용한다.

1
2
3
4

# 홈 디렉토리 안 캐시 폴더 소유권 되돌리기 (가장 안전)
sudo chown -R "$(whoami)" ~/.npm
# 재귀 소유권 후 경로 권한 점검
ls -ld ~/.npm

분기 3: 시스템 경로 전역 설치가 필요한 프로젝트 예외

일부 레거시 도구가 /usr/local/lib/node_modules를 고정으로 참조한다면, 임베딩 전역 경로가 아닌 프로젝트 단위 설치를 권장한다.

1
2

npm install --save-dev <package>
npx <package>   # 전역 설치 없이 실행

5. 검증 명령

해결 후 같은 에러가 사라지고 전역 패키지가 실제로 동작하는지 확인한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 전역 경로가 홈 디렉토리로 바뀌었는지 확인
npm config get prefix        # 기대: ~/.npm-global

# 전역 패키지가 설치되는지 확인
npm install -g cowsay
cowsay "hello devtrace"      # 설치된 바이너리가 PATH에서 실행되어야 함

# sudo 없이 전역 목록
npm ls -g --depth=0
# node/npm 버전도 바뀌지 않았는지 확인
node -v
npm -v

6. 잘못된 해결책 (주의해야 할 유형)

sudo npm install -g 는 당장 에러를 가리키지만 권한 문제의 근본을 해결하지 못하고 시스템 경로에 루트 소유 파일을 쌓아둔다. 이후 그 경로를 사용하는 모든 동료 사용자/빌드가 권한 문제를 다시 겪게 되고, 나중에 npm으로 만든 바이너리를 잘못된 파일 권한으로 관리하게 되어 위험하다. 마찬가지로 /usr/lib/node_modules 전체를 chmod -R 777 하는 방식은 시스템 보안 설정을 무력화하므로 피해야 한다.

7. 향후 예방 조치 / 참고

• 전역 설치를 최소화한다. 대부분의 도구는 npx를 사용하면 전역 설치 없이 실행할 수 있어 권한 문제의 출발점 자체를 제거한다.
• **Node 버전 매니저(NVM 등)**을 사용하면 사용자 홈 안에서 Node 버전 전환과 전역 경로가 함께 바뀌어 EACCES를 원천 차단할 수 있다.
• 새 머신에서 npm을 처음 설정할 때, 이 글의 ~/.npm-global 구성을 미리 적용해두면 재발 방지에 유효하다.
• npm config get prefix의 결과가 /usr이 아닌지 주기적으로 확인해 시스템 경로로 회귀하는 것을 막는다.

DevTrace verdict: 이 npm EACCES 오류의 핵심은 “권한이 없다"가 아니라 npm이 바라보는 전역 경로가 시스템 경로(/usr)와 사용자 권한 경계가 어긋나 있는 것이다. chown/chmod보다 NPM_CONFIG_PREFIX=~/.npm-global로 전역 경로를 홈으로 옮기는 쪽이 더 안전하고, 보다 근본적인 해결책이다.

출처: Stack Overflow 16151018 — How to fix npm throwing error without sudo

DevTrace 결론

npm EACCES 권한 오류는 chown/chmod보다 npm 전역 설치 경로를 사용자 홈 디렉토리로 옮기는 방식으로 sudo 없이, 더 안전하게 해결하는 것이 권장된다.

원문 출처는 문제 발견의 단서이며, 위 판단과 점검 항목은 DevTrace의 독자 분석이다.