기본 콘텐츠로 건너뛰기

Claude Code 터미널 연동 시 EACCES 권한 에러 3분 해결법

대표 썸네일

npm install -g @anthropic-ai/claude-code 딱 쳤는데, 터미널이 시뻘겋게 물들면서 멈춘 적 있으신가요?

npm ERR! code EACCES라는 메시지를 보는 순간 "내가 뭘 잘못 눌렀나" 싶어 당황하게 됩니다. 결론부터 말하면, 이건 Claude Code 자체의 버그가 아니라 npm 전역 설치 폴더의 소유권 문제입니다. 구글링하면 제일 먼저 나오는 답이 sudo npm install -g인데, 이걸 그대로 실행하기 전에 딱 3분만 시간을 내주세요. 지금 당장은 편하지만 나중에 더 큰 골칫거리를 만드는 방법이거든요.

EACCES 에러, 정확히 뭘 말하는 걸까

npm이 전역 패키지를 설치하는 기본 폴더(/usr/local/lib/node_modules 같은 곳)는 시스템 소유입니다. 아파트로 치면 관리사무소가 관리하는 우편함이라고 생각하면 쉽습니다. 내 명의로 등록된 우편함이 아닌데 그 앞에 택배를 쌓으려니 문이 안 열리는 상황, 그게 바로 EACCES입니다.

실제로 이런 로그를 보게 됩니다.

npm ERR! code EACCES
npm ERR! syscall access
npm ERR! path /usr/local/lib/node_modules
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied, access '/usr/local/lib/node_modules'

여기서 sudo를 붙이면 관리사무소 열쇠를 억지로 복사해서 문을 따는 셈입니다. 당장은 열리지만, 이후 생성되는 모든 파일의 소유권이 root로 바뀌어버립니다. 그러면 다음번 npm update나 npm uninstall을 할 때마다 똑같은 권한 에러가 반복되고, 심한 경우 전역 Node.js 설치 자체가 꼬여버립니다. npm 공식 문서도 이 문제를 별도 페이지로 만들어 다룰 만큼 흔한 함정입니다.

macOS/Linux와 Windows는 증상이 조금 다르게 나타나므로 표로 정리했습니다.

구분 macOS / Linux Windows
에러 코드 EACCES EPERM으로 표기되는 경우가 많음
원인 전역 설치 경로(/usr/local/lib)가 root 소유 회사 보안 정책으로 잠긴 PC에서 발생
임시 방편 sudo npm install -g (비권장) PowerShell "관리자 권한으로 실행"
근본 해결 prefix 재설정 또는 nvm prefix 재설정 또는 nvm-windows

3분 해결법: npm 전역 설치 경로 옮기기

가장 빠른 방법은 npm이 패키지를 설치하는 위치 자체를 내 소유의 폴더로 바꿔버리는 겁니다. 우편함 열쇠를 새로 파는 대신, 내 집 앞에 새 우편함을 하나 만드는 방식이라고 보면 됩니다.

# 1단계: 내가 소유한 전역 설치 폴더를 새로 만든다
# (기존 /usr/local 대신 홈 디렉터리 아래에 생성 - 권한 문제가 원천적으로 없음)
mkdir ~/.npm-global

# 2단계: npm에게 앞으로 여기다 설치하라고 알려준다
npm config set prefix '~/.npm-global'

# 3단계: 셸 설정 파일을 열어서 PATH에 새 경로를 추가한다
# zsh 사용자는 ~/.zshrc, bash 사용자는 ~/.bash_profile 또는 ~/.bashrc
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

# 4단계: 방금 수정한 설정 파일을 즉시 반영한다
# (터미널을 완전히 껐다 켜도 되지만, source 명령이 더 빠르다)
source ~/.zshrc

# 5단계: 이제 sudo 없이 그대로 재시도한다
npm install -g @anthropic-ai/claude-code

# 6단계: 설치가 제대로 됐는지 버전 확인으로 검증
claude --version

claude --version에서 버전 번호가 찍히면 끝입니다. 여기까지 왔는데도 안 된다면, 3단계에서 PATH 등록이 안 됐거나 다른 셸 프로필 파일을 수정했을 가능성이 큽니다. 이 부분은 아래 VS Code 섹션에서 별도로 다룹니다.

💡 npm 관련 다른 에러 유형(EPERM, ENOENT 등)까지 궁금하다면 npm 전역 패키지 설치 에러 총정리 글도 함께 보시면 도움이 됩니다.

근본 해결법: nvm으로 아예 권한 문제 차단하기

회사 PC처럼 몇 달 뒤에 또 같은 에러를 만날 가능성이 높은 환경이라면, prefix 재설정보다 nvm(Node Version Manager)을 쓰는 게 낫습니다. nvm으로 설치한 Node.js는 애초에 사용자 홈 디렉터리 안에 완전히 격리되기 때문에, root 소유 폴더를 건드릴 일 자체가 사라집니다. npm 공식 문서도 이 방법을 "가장 권장되는 방법"으로 명시하고 있습니다.

📌 상황별 권장 해결 경로
⚡ npm install -g 실행 시 EACCES 발생
↓
[일회성 / 빠른 해결] prefix 재설정 (3분)
[회사 PC / 장기적 원천 차단] nvm 설치 (근본 해결)
↓
✅ claude --version 검증 및 정상 실행 확인 
# nvm 설치 스크립트 실행 (공식 저장소 기준)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 터미널 재시작 후 최신 LTS 버전의 Node.js 설치
# Claude Code는 Node.js 18 이상을 요구한다
nvm install --lts

# 방금 설치한 Node.js를 기본값으로 지정
nvm use --lts

# 이 상태에서 Claude Code를 설치하면 권한 에러가 아예 발생하지 않는다
npm install -g @anthropic-ai/claude-code

# 정상 설치 확인
claude --version

nvm으로 설치한 Node.js는 ~/.nvm 폴더 안에서만 동작하기 때문에 root 권한이 개입할 여지가 없습니다. 한 번 세팅해두면 이후 Node.js 버전을 바꿔가며 테스트할 때도 훨씬 편해집니다.

VS Code 터미널 연동 특이 케이스

일반 터미널(Terminal.app, iTerm 등)에서는 문제없이 됐는데, VS Code 통합 터미널에서 claude를 치면 갑자기 command not found가 뜨는 경우가 있습니다. 이건 EACCES와는 결이 다른 문제입니다.

VS Code 통합 터미널은 기본적으로 사용자의 셸 프로필(.zshrc, .bashrc)을 로드하지만, VS Code 자체를 관리자 권한으로 실행했는지 여부에 따라 일반 터미널과 PATH 컨텍스트가 미묘하게 달라질 수 있습니다. 확인 방법은 간단합니다.

  1. VS Code 통합 터미널에서 echo $SHELL을 입력해 현재 셸이 무엇인지 확인합니다.
  2. echo $PATH로 ~/.npm-global/bin 또는 nvm 경로가 실제로 포함돼 있는지 확인합니다.
  3. 포함돼 있지 않다면, VS Code 설정에서 기본 프로필을 바꾼 뒤 터미널을 완전히 새로 열어야 합니다 (기존 탭은 이전 세션을 그대로 들고 있습니다).

⚠️ PATH 등록 후에도 command not found가 뜬다면, 셸 설정 파일을 잘못 수정했을 확률이 높습니다. zsh인데 .bash_profile을 고쳤다거나, VS Code 터미널은 sh 프로필을 쓰는데 zsh 설정만 바꾼 경우가 대표적입니다. echo $SHELL 결과에 맞는 프로필 파일에 PATH를 추가했는지 다시 한번 확인해보세요.

VS Code에서 Claude Code 외에 다른 AI 코딩 도구 설정까지 비교해보고 싶다면 VS Code AI 코딩 도구 3종 비교 글에서 셸 프로필 설정 차이를 더 자세히 다루고 있습니다. 아직 Claude Code 자체를 처음 설치하는 단계라면 Claude Code 설치부터 첫 실행까지 가이드를 먼저 훑어보시는 걸 추천합니다.

💡 정리하며

EACCES는 무서운 에러가 아니라, npm이 "이 우편함은 네 소유가 아니야"라고 알려주는 정직한 신호일 뿐입니다. sudo npm install -g로 일단 넘기고 싶은 유혹이 들겠지만, 그 순간부터 전역 Node.js 환경의 소유권이 뒤죽박죽되고 다음 업데이트마다 같은 에러를 또 만나게 됩니다. 지금 3분 투자해서 prefix를 옮기거나 nvm으로 갈아타는 게 장기적으로 훨씬 마음 편합니다.

이 방법으로 에러를 해결하셨다면, 댓글로 어떤 환경(macOS/Windows/WSL)에서 겪으셨는지 알려주세요. 비슷한 상황에 놓인 다른 분들에게 큰 참고가 됩니다.

Dev
개발 생산성 연구소

Node.js 및 AI 개발 환경 구축 시 발생하는 트러블슈팅과 개발 환경 최적화 팁을 정밀 검증하여 전달합니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

Gemini Many-Shot Prompting: Why 500 Examples Beat Fine-Tuning

💻 Tech & AI Deep Dive Guide 본 문서의 검증된 팩트 및 가이드는 실시간 최신 라인업을 기반으로 작성되었습니다. Gemini Many-Shot Prompting: Why 500 Examples Beat Fine-Tuning You've built an AI agent with five carefully crafted examples, and it handles the happy path beautifully. Then a slightly weird edge case shows up in production, and the model confidently returns garbage. The usual advice is "just fine-tune it," but spinning up a training pipeline for what is essentially a formatting problem feels like using a sledgehammer to crack a nut. Gemini 3.1 Pro changes this calculus entirely. Its context window doesn't just fit a long PDF, it fits hundreds of full examples in a single call. This turns prompt engineering into something closer to database-style context loading than the trial-and-error tweaking most of us grew up with. This guide walks through Gemini Many-Shot Prompting , the research behind why it...
자세한 내용 보기

No More Git Conflicts: Automate PR Reviews with Cline

📌 Key Takeaways Autonomous PR Reviews: Cline is a free, open-source VS Code agent that reads PR diffs, flags risky changes, and leaves comments using Claude Sonnet 5, Gemini 3.6 Flash, or GPT-5.6. Built-in Safety Nets: The Plan/Act split ensures you review blueprints before execution, while shadow Git Checkpoints allow instant 1-click rollbacks. Automated Team Standards: Set up repository rules once via .clinerules and the GitHub MCP server to enforce consistent code reviews automatically. It's 5:47 PM on a Friday. A teammate pushes a PR right before logging off. Nobody reviews it over the weekend. Monday morning, you pull the branch and three files are screaming with merge conflicts, touching legacy code nobody remembers writing context for. Sound familiar? You're not the only reviewer on the team, but somehow you're always the one untangling this mess. What if something had already scann...
자세한 내용 보기

기밀 유출 없는 DeepSeek R1 무료 로컬 실행법

💻 Tech & AI Deep Dive Guide 본 문서의 검증된 팩트 및 가이드는 실시간 최신 라인업을 기반으로 작성되었습니다. 📌 3초 핵심 결과 요약 DeepSeek 웹·앱은 입력 데이터가 중국 서버로 전송되지만, Ollama로 로컬 실행하면 인터넷 연결 없이 100% 내 PC 안에서만 처리 돼 유출 자체가 불가능합니다. 사양에 맞는 경량 모델(7B~14B)만 골라도 GPU 없는 노트북에서 무료로 돌아갑니다. 방화벽으로 Ollama의 외부 통신을 막는 설정까지 마쳐야 "진짜 완전 오프라인" 보안이 완성됩니다. 사내 회의록을 요약하려고 DeepSeek 웹사이트에 텍스트를 붙여넣던 순간, 보안팀 슬랙 메시지가 날아왔습니다. "이거 중국 서버로 나가는 거 아시죠?" 등에서 식은땀이 흘렀습니다. 급하게 찾아보니 진짜였습니다. 2025년 초 이탈리아 개인정보보호청(Garante)은 DeepSeek 앱 접속을 아예 차단했고, 한국 개인정보보호위원회도 신규 다운로드를 일시 중단시켰습니다. DeepSeek 공식 개인정보처리방침에는 사용자 입력 데이터와 키 입력 패턴까지 중국 내 서버에 저장된다고 명시돼 있습니다. 그렇다고 성능 좋은 추론 특화 오픈소스 모델 을 포기하기는 아까웠습니다. 결국 답은 하나였습니다. 클라우드로 보내지 말고, 내 PC 안에서 직접 돌리면 됩니다. 이 글은 그 과정을 그대로 정리한 실전 기록입니다. 왜 DeepSeek 클라우드는 위험하고, 로컬 실행이 답인가 클라우드 DeepSeek에 문서를 붙여넣는 건 택배 상자를 뜯어서 남의 창고에 맡기는 것과 비슷합니다. 내 물건이지만 일단 남의 공간에 들어가는 순간, 그 안에서 무...
자세한 내용 보기