Claude Code EACCES 오류 해결법, npm 전역 설치 실패 체크리스트

npm install -g @anthropic-ai/claude-code를 돌렸는데 EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@anthropic-ai' 같은 에러 로그만 뜨고 멈춘 적 있으신가요? 이거, 검색해보면 십중팔구 "sudo 붙여서 설치하세요"라는 답이 먼저 나오는데 그게 진짜 근본 해결책은 아닙니다. npm이 root 소유 디렉터리에 파일을 쓰려다 막히는 게 원인이라서, sudo는 증상만 잠깐 가리는 처방이거든요. EACCES가 왜 나는지, OS별로 왜 다르게 대응해야 하는지, 그리고 Anthropic이 공식적으로 권장하는 우회 방법은 뭔지 아래서 하나씩 확인해보세요.

터미널에 표시된 npm EACCES permission denied 에러 로그 예시

 

EACCES 권한 오류, 왜 발생하나

npm 공식 문서에 따르면 이 오류는 npm이 전역 패키지를 설치하면서 쓰기 권한이 없는 디렉터리에 접근하려 할 때 발생합니다. 대표적으로 /usr/local/lib/node_modules처럼 root가 소유한 경로죠. 일반 사용자 계정으로는 여기에 파일을 못 만드니 mkdir 단계에서 바로 막히는 겁니다.

실제로 이 문제가 재현된 사례가 있습니다. anthropics/claude-code 저장소의 이슈 #3951에서 Ubuntu/Debian, Node.js v22.14.0, npm 10.9.2 조합으로 npm install -g @anthropic-ai/claude-code를 실행하자 위와 똑같은 에러 로그가 그대로 나왔습니다. 근데 더 흥미로운 건 그 다음이에요. 이슈 보고자가 급한 대로 sudo를 붙여서 설치는 성공했는데, 이후 claude 명령어 자체를 터미널이 못 찾는 후속 문제가 이어졌습니다. 임시방편이 또 다른 문제를 낳은 셈이죠.

 

sudo로 설치하면 안 되는 이유

sudo npm install -g로 밀어붙이면 당장은 설치가 됩니다. 문제는 그다음부터예요. 그렇게 설치된 파일은 전부 root 소유가 되고, 나중에 같은 패키지를 업데이트하거나 지우려 하면 다시 EACCES가 뜹니다. 게다가 sudo로 실행되는 설치 스크립트는 root 권한으로 임의 코드를 돌리는 셈이라 보안 측면에서도 좋지 않습니다.

Anthropic 공식 문서(code.claude.com/docs/en/troubleshoot-install)도 이 부분을 명확히 짚습니다. "npm install fails with EACCES / permission denied. This usually means the install was run with sudo, or your global npm directory is root-owned"라고 원인을 밝힌 뒤, sudo를 쓰지 말고 네이티브 인스톨러를 쓰거나 npm prefix를 고치라고 안내하죠. 공식 문서와 npm 쪽 설명이 정확히 같은 방향을 가리키고 있다는 게 포인트입니다.

sudo로 설치한 npm 패키지가 root 소유가 되는 구조를 보여주는 다이어그램

 

해결법 1 — npm 전역 디렉터리를 홈으로 옮기기

macOS·Linux에서 가장 많이 쓰이는 방법은 npm이 쓸 전역 디렉터리 자체를 사용자 홈 안으로 바꿔버리는 겁니다.

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
source ~/.profile
npm install -g @anthropic-ai/claude-code

기존 Node.js나 npm을 재설치할 필요가 없다는 게 이 방법의 장점입니다. 다만 npm 공식 문서는 "이 섹션은 Windows에는 적용되지 않는다"고 못 박고 있어요. Windows는 npm 전역 디렉터리가 원래부터 사용자 프로필 하위에 있어서 이런 권한 충돌이 잘 안 생기기 때문입니다.

 

해결법 2 — EACCES 디렉터리 소유권만 chown으로 고치기

새 디렉터리를 만드는 대신 문제가 되는 디렉터리의 소유자만 바꾸는 방법도 있습니다.

sudo chown -R $(whoami) /usr/local/lib/node_modules
sudo chown -R $(whoami) /usr/local/bin
sudo chown -R $(whoami) /usr/local/share

한 번만 실행하면 되니 간편하긴 한데, 서버를 여러 사용자가 같이 쓰는 환경이라면 추천하지 않는다는 지적이 커뮤니티 자료에도 따라붙습니다. npm 캐시 자체(~/.npm)가 원인일 때는 sudo chown -R $(whoami) ~/.npm로 대응한다는 사례도 Claude Code 관련 커뮤니티 글에서 확인됩니다.

 

해결법 3 — nvm으로 npm 권한 오류 자체를 없애기

npm 공식 문서는 "Node 버전 관리자를 쓰는 게 권한 문제를 피하는 가장 좋은 방법"이라고 명시합니다. nvm으로 설치한 Node는 애초에 전부 사용자 홈 디렉터리 안에 자리 잡기 때문에, root 소유 디렉터리를 건드릴 일 자체가 없어지는 거죠.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install --lts
nvm use --lts
npm install -g @anthropic-ai/claude-code

기존 시스템 Node.js를 지울 필요 없이 nvm만 추가로 설치하면 됩니다. 근데 매번 새 셸을 열 때 nvm 초기화가 안 되면 또 헷갈릴 수 있으니, .bashrc나 .zshrc에 nvm 로더가 잘 들어가 있는지는 확인해두는 게 좋습니다.

npm prefix 방식, chown 방식, nvm 방식 세 가지 해결법 비교 표

 

해결법 4 — Anthropic 공식 권장: 네이티브 인스톨러로 npm 우회

사실 Anthropic 공식 문서가 1순위로 권장하는 건 위 세 가지 우회법이 아니라 아예 npm을 거치지 않는 겁니다. 네이티브 인스톨러는 Node.js 설치 여부와 무관하게 동작하고, 백그라운드 업데이트도 자체적으로 처리합니다.

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

macOS는 Homebrew(brew install --cask claude-code), Windows는 WinGet(winget install Anthropic.ClaudeCode)으로도 설치할 수 있습니다. 이미 npm으로 설치해서 EACCES를 겪는 중이라면 공식 문서는 아래처럼 정리하고 넘어가라고 안내합니다.

npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash

 

OS별 EACCES 권한 오류 대응, 뭐가 다른가

macOS·Linux는 네이티브 인스톨러가 ~/.local/bin/, ~/.claude/ 두 경로에 쓰기 권한을 요구합니다. test -w ~/.local/bin으로 먼저 확인하고, 안 되면 sudo chown -R $(whoami) ~/.local로 소유권만 바꿔주면 됩니다.

Windows는 사정이 좀 다릅니다. 공식 문서가 "Windows의 설치 위치는 %USERPROFILE% 하위라 이 섹션이 거의 적용되지 않는다"고 밝힐 정도로, 리눅스식 EACCES는 원래 잘 안 생깁니다. 대신 실제로 자주 걸리는 건 PATH에 claude가 안 잡혀서 나는 인식 오류, 구버전 Claude Desktop이 WindowsApps 경로에 등록해둔 Claude.exe가 PATH 우선순위를 가로채는 문제 쪽입니다. 그래도 npm 전역 경로 자체를 바꾸고 싶다면 이렇게 하면 됩니다.

mkdir %APPDATA%\npm-global
npm config set prefix %APPDATA%\npm-global

이후 시스템 환경 변수의 사용자 변수 Path에 %APPDATA%\npm-global을 추가해주면 끝입니다.

WSL은 또 다른 케이스예요. 여기서 흔한 건 EACCES가 아니라 OS 오검출과 잘못된 바이너리 참조입니다. which npm, which node 결과가 /mnt/c/로 시작한다면 Windows 쪽 바이너리를 그대로 물고 있다는 뜻이고, 이 상태에서 설치하면 플랫폼 불일치가 납니다. 공식 문서는 이럴 때 npm config set os linux를 먼저 실행한 뒤 npm install -g @anthropic-ai/claude-code --force로 설치하라고 안내하는데, 여기서도 "sudo는 쓰지 말라"는 원칙은 그대로 유지됩니다. 리눅스용 Node를 nvm이나 배포판 패키지 매니저로 따로 설치해두는 편이 근본적으로 깔끔합니다.

 

FAQ

Q. sudo로 일단 설치했는데 지금이라도 되돌릴 수 있나요?
가능합니다. npm uninstall -g @anthropic-ai/claude-code로 root 소유 설치본을 지운 다음, 위에서 소개한 prefix 변경이나 네이티브 인스톨러로 다시 깔면 됩니다.

Q. Windows인데도 EACCES 비슷한 오류가 났어요.
공식 문서 기준으로는 예외적인 케이스입니다. 관리자 권한으로 설치된 시스템 전역 Node.js를 쓰고 있거나, npm-global 경로 설정이 꼬여 있을 가능성이 큽니다. 위의 %APPDATA%\npm-global 설정으로 경로를 사용자 소유 쪽으로 옮겨보세요.

Q. nvm과 네이티브 인스톨러 중 뭘 써야 하나요?
Node.js를 다른 프로젝트에서도 계속 쓸 계획이면 nvm이 낫고, Claude Code만 깔끔하게 쓰고 싶다면 Anthropic이 권장하는 네이티브 인스톨러가 더 간단합니다.

 

다음에 볼 만한 것

설치 자체는 끝냈는데 claude 명령어가 인식이 안 되거나 로그인 단계에서 막힌다면, 이건 오늘 다룬 EACCES와는 원인이 다른 별개 이슈일 가능성이 큽니다. Claude Code 공식 트러블슈트 문서(code.claude.com/docs/en/troubleshoot-install)를 한 번 열어두고 옆에서 참고하면서 진행하는 걸 추천합니다.