npm: 전역 설치에서 EACCES permission denied

안녕하세요, BlueByte입니다. npm install -g가 EACCES: permission denied로 멈춘다면, 패키지나 네트워크에 문제가 있는 게 아닙니다 — npm이 여러분 계정 소유가 아닌 디렉터리에 쓰려 했고 운영체제가 거부한 것입니다. 증상은 전역 설치(npm install -g <무언가>)가 code EACCES와 /usr/local/lib/node_modules 같은 경로를 가리키는 permission denied 줄과 함께 실패하는 것입니다. 오늘은 이게 무슨 뜻인지, prefix 디렉터리 문제가 맞는지 확인하는 법, npm이 권장하는 방식으로 고치는 법, 그리고 sudo에 손대지 않고 재발을 막는 법까지 하나씩 짚어보겠습니다.

EACCES 오류가 알려주는 것

전역 설치가 실패하면 npm은 이런 블록을 출력합니다:

npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/npm-check-updates
npm error errno -13
npm error Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/npm-check-updates'

예전 npm(v9 이하)은 같은 실패를 npm error 대신 npm ERR! 접두사로 출력하고, syscall은 실패한 단계에 따라 access, open, unlink로 표시될 수 있습니다. 공통점은 code EACCES와 permission denied입니다: EACCES는 "접근 거부"를 뜻하는 POSIX 코드이고, errno -13은 같은 것을 숫자로 나타낸 것입니다. npm이 고장난 게 아니라 OS에 폴더 생성을 요청했고 OS가 거절한 것입니다.

전역 설치가 권한 벽에 부딪히는 이유

npm install -g는 npm의 prefix 디렉터리에 씁니다 — 전역 패키지와 그 bin 링크가 놓이는 전역 루트입니다. 시스템 전역 Node 설치(OS 패키지 매니저나 공식 설치 프로그램)에서 이 prefix는 보통 /usr/local(리눅스에서는 /usr)이며, 이곳은 root 소유입니다. 일반 계정은 여기에 파일을 만들 수 없으므로, root로 실행하거나 npm이 여러분 소유 디렉터리를 가리키게 하기 전까지 전역 설치는 실패합니다.

이것이 원인의 전부입니다. 의존성 충돌도, 손상된 캐시도, 잘못된 레지스트리도 아닙니다 — 그런 문제는 다른 오류를 냅니다. EACCES는 오직 대상 디렉터리를 누가 소유하느냐의 문제입니다.

프로젝트가 아니라 prefix 디렉터리 문제인지 확인하기

두 명령이 npm이 어디에 쓰려 하고 누가 그곳을 소유하는지 보여줍니다:

npm config get prefix
ls -ld $(npm config get prefix)/lib/node_modules

시스템 Node에서의 예상 출력 — root root 소유에 주목하세요:

/usr/local
drwxr-xr-x 3 root root 4096 Sep  6 10:12 /usr/local/lib/node_modules

그 디렉터리가 root 소유이고 whoami가 여러분 이름을 출력한다면, EACCES는 완전히 설명됩니다: root만 쓸 수 있는 곳에 쓰려 한 것입니다.

npm이 권장하는 방식으로 고치기: Node 버전 매니저

npm 자체 안내는, 가장 깔끔한 해결이 Node와 npm을 Node 버전 매니저로 다시 설치해 툴체인 전체가 홈 디렉터리 아래에 놓이게 하는 것이라고 말합니다. 그러면 어떤 전역 설치도 root가 필요 없습니다. 그렇게 Node를 설치하면 npm config get prefix가 홈 안쪽을 가리키고,

npm install -g npm-check-updates

...가 EACCES 없이 끝납니다. 새 장비에서는 이 방법을 우선하세요. 앞으로 설치할 모든 Node 버전에서 같은 문제를 함께 해결해 주기 때문입니다.

npm prefix를 내가 소유한 폴더로 옮겨 고치기

Node를 다시 설치할 수 없다면, npm prefix를 여러분이 소유한 디렉터리로 바꾸세요. 이것이 npm이 문서화한 수동 방법입니다(Windows에는 해당하지 않습니다):

npm config set prefix ~/.local

그런 다음 그 prefix의 bin을 PATH에 올리도록 ~/.profile(zsh를 쓰면 ~/.zprofile에도) 다음 줄을 추가합니다:

export PATH=~/.local/bin:$PATH

프로파일을 다시 읽고 설치합니다:

source ~/.profile
npm install -g npm-check-updates

이제 전역 패키지는 ~/.local/lib/node_modules에, 명령은 ~/.local/bin에 놓이며 모두 여러분 소유입니다.

실제 사례: 배포판 Node 뒤의 CLI 설치

배포판 패키지 매니저로 Node를 설치한 뒤 npm install -g typescript를 실행하니 EACCES: permission denied, mkdir '/usr/lib/node_modules/typescript'가 납니다. npm config get prefix를 실행하면 /usr가 나오고, ls -ld /usr/lib/node_modules는 root root를 보여줍니다. sudo 대신, npm config set prefix ~/.local을 실행하고 ~/.profile에 export PATH=~/.local/bin:$PATH를 추가한 뒤 source하고 npm install -g typescript를 다시 실행합니다. 설치가 되고 tsc --version도 동작합니다 — ~/.local/bin이 여러분 PATH에 있고 여러분 소유이기 때문입니다.

전역 설치가 내 디렉터리에 들어가는지 확인하기

위치와 명령이 실제로 잡히는지 함께 확인합니다:

npm root -g
which tsc

/home/you/.local/lib/node_modules
/home/you/.local/bin/tsc

npm root -g가 여전히 root 소유 경로를 보여주면 prefix 변경이 적용되지 않은 것입니다 — npm config get prefix를 다시 확인하세요. which가 아무것도 못 찾으면 PATH 줄이 아직 로드되지 않은 것입니다. 새 셸을 열거나 프로파일을 다시 source하세요.

EACCES를 다시 안 만나기 — 그리고 sudo가 잘못된 반사인 이유

sudo npm install -g는 오류를 사라지게는 하지만, 패키지를 root로 설치해 캐시와 설정 안에 root 소유 파일을 남길 수 있고, 이는 나중에 평범한 명령에서 새로운 EACCES를 유발합니다. npm의 안내는 이를 피하라는 것입니다. prefix를 한 번 설정해 dotfiles에 넣어 두고, 전역 패키지를 절대 root로 설치하지 마세요. 딱 한 번만 실행할 명령이라면 npx <명령>(npm 5.2+)이 전역 prefix를 전혀 건드리지 않고 실행해 줍니다.

EACCES와 ERESOLVE의 차이

EACCES는 파일시스템 권한 오류입니다 — npm이 대상 디렉터리에 쓰지 못한 것입니다. ERESOLVE는 의존성 해석 오류입니다 — npm은 어디에 쓸지는 정확히 알았지만 트리 안의 충돌하는 버전 요구를 조율하지 못한 것입니다. 메시지가 code EACCES / permission denied라면 소유권이나 prefix를 고치고, code ERESOLVE / could not resolve라면 버전 충돌이므로 권한을 아무리 고쳐도 풀리지 않습니다.