이번에 인텔 아이맥에 Claude Code CLI를 새로 설치하면서 겪은 EACCES 에러를, 다른 프로젝트에서도 반복해서 마주쳤던 참에 한 번 근본 원인부터 정리해두기로 했다.

에러가 나는 이유

$ npm install -g @anthropic-ai/claude-code
npm error code EACCES
npm error syscall access
npm error path /usr/local/lib/node_modules

npm의 전역 설치 기본 경로(/usr/local/lib/node_modules 또는 Homebrew/Node 버전에 따라 다른 시스템 경로)는 macOS·리눅스 배포판 대부분에서 일반 사용자 계정에 쓰기 권한이 없는 시스템 디렉터리다. npm install -g는 이 경로에 패키지를 풀어야 하는데, 권한이 없으니 거부당하는 것이다.

흔한 대응, 그러나 좋지 않은 방법: sudo

가장 많이 보이는 해결책은 이거다.

sudo npm install -g @anthropic-ai/claude-code

당장은 되지만, 이건 문제를 해결한 게 아니라 미룬 것이다. sudo로 설치한 패키지는 해당 디렉터리에 root 소유 파일을 남긴다. 다음에 npm update -g나 다른 패키지를 sudo 없이 설치하려고 하면 다시 권한 충돌이 나고, 결국 전역 node_modules 디렉터리 전체가 root와 일반 사용자 파일이 뒤섞인 지뢰밭이 된다. 게다가 sudo로 실행되는 postinstall 스크립트는 필요 이상의 권한으로 임의 코드를 실행하게 되는 셈이라 보안 관점에서도 바람직하지 않다.

근본적인 해결: 전역 설치 경로를 사용자 소유로 옮기기

가장 깔끔한 방법은 npm의 전역 설치 경로 자체를 사용자 홈 디렉터리 아래로 바꾸는 것이다.

npm config set prefix "$HOME/.npm-global"

그리고 이 경로를 PATH에 추가한다 (~/.zshrc 또는 ~/.bashrc).

export PATH="$HOME/.npm-global/bin:$PATH"

이후로는 sudo 없이 어떤 전역 패키지든 사용자 권한만으로 설치·업데이트·삭제할 수 있다.

npm install -g @anthropic-ai/claude-code

두 번째 관문: postinstall 스크립트 차단

경로 문제를 해결해도, 최근 npm 버전은 보안 강화를 위해 패키지의 postinstall 스크립트 실행을 기본적으로 제한하는 경우가 있다. 이때는 이렇게 명시적으로 허용해줘야 한다.

npm install -g --allow-scripts=@anthropic-ai/claude-code @anthropic-ai/claude-code

--allow-scripts는 신뢰할 수 있는 패키지에 한해서만 쓰는 게 안전하다 — 아무 패키지에나 이 옵션을 습관적으로 붙이는 건 애초에 이 제한을 두는 취지를 무력화하는 것이기 때문이다.

참고: 플랫폼마다 권한 모델은 다르다

이 EACCES 문제와 해결법은 macOS·리눅스처럼 유닉스 계열 파일 권한 모델을 쓰는 환경에 해당한다. 안드로이드(Termux)처럼 애초에 다른 권한/샌드박스 구조를 쓰는 환경에서는 같은 에러 메시지가 나더라도 원인과 해법이 다를 수 있으니, 에러 메시지만 보고 무작정 같은 해결책을 적용하기보다는 실행 중인 플랫폼의 권한 모델부터 확인하는 게 먼저다.

정리

EACCES를 만나면 반사적으로 sudo를 붙이기 전에, 왜 이 경로에 권한이 없는지부터 생각해보는 게 좋다. 대부분의 경우 답은 “이 디렉터리가 애초에 시스템 영역이라서"이고, 해결책은 권한을 억지로 얻는 게 아니라 애초에 권한이 있는 곳으로 설치 위치를 옮기는 것이다.