Claude Code "command not found" 에러 해결법 7가지

Claude Code를 설치하고 신나서 claude를 입력했는데 "command not found"가 뜨면 정말 당황스럽습니다. 분명 설치는 됐다는데 왜 안 보이는 걸까요.

이 글은 코드 한 줄 안 써본 분도 따라올 수 있게, 이 에러의 7가지 원인과 해결법을 하나씩 짚어드립니다. 저도 처음 맥에서 설치할 때 3번이나 막혔던 부분이라 그때 시행착오를 그대로 담았습니다.

먼저 안심하세요. 이 에러는 거의 100% 설정 문제라서 컴퓨터를 망가뜨리는 종류가 아닙니다.

"command not found"가 뜻하는 것

이 에러는 "설치가 안 됐다"가 아니라 "어디 있는지 못 찾겠다"는 컴퓨터의 하소연입니다.

터미널(검은 화면에 명령어를 입력하는 프로그램)에서 claude라고 치면, 컴퓨터는 정해진 폴더 목록을 차례로 뒤져서 claude라는 이름의 프로그램을 찾습니다. 이 폴더 목록을 PATH라고 부릅니다.

비유하자면 PATH는 "내 책장 위치 메모"입니다. 책(프로그램)이 책장에 분명히 꽂혀 있어도, 메모에 그 책장 위치가 안 적혀 있으면 컴퓨터는 "그런 책 없는데요?"라고 답합니다.

증상	진짜 의미
command not found	프로그램 위치를 PATH가 모름
permission denied	위치는 찾았는데 실행 권한 없음
no such file or directory	그 경로에 파일 자체가 없음

이 글은 첫 번째 경우만 다룹니다. 나머지 두 개는 원인이 다릅니다.

진단 먼저: 내가 어디서 막힌 건가

해결책으로 바로 가기 전에 2분짜리 진단을 권합니다. 잘못된 해결법을 시도하면 시간만 더 듭니다.

터미널을 열고 아래 3가지를 순서대로 입력해 보세요.

node -v
npm -v
which claude

각 명령이 뜻하는 건 이렇습니다.

• node -v: 자바스크립트를 실행시켜주는 엔진 Node.js의 버전 확인
• npm -v: Node.js와 함께 설치되는 패키지 관리자(앱스토어 같은 역할)의 버전 확인
• which claude: claude 명령이 어디 있는지 위치 출력

결과를 보고 아래 표에서 자기 경우를 찾으세요.

node 결과	npm 결과	which claude 결과	가야 할 섹션
command not found	command not found	command not found	해결법 1 (Node.js부터)
v18.x 이상	9.x 이상	command not found	해결법 2~4
v16 이하	8.x 이하	command not found	해결법 5 (버전 업그레이드)
정상	정상	경로 출력됨	해결법 6~7 (셸 문제)

Claude Code는 Node.js 18 이상이 필요합니다(Anthropic 공식 문서 기준). 16 이하면 설치는 돼도 실행 단계에서 문제가 생깁니다.

해결법 1. Node.js를 먼저 설치하기

node -v가 command not found라면, 그러니까 Node.js 자체가 없는 상태라면 Claude Code도 당연히 안 잡힙니다.

Claude Code는 Node.js 위에서 돌아가는 도구거든요. 비유하면 Node.js가 콘센트고, Claude Code는 거기 꽂는 가전제품입니다.

설치 방법은 운영체제별로 이렇습니다.

• 맥: 공식 사이트(nodejs.org)에서 LTS 버전 .pkg 파일 다운로드 → 더블클릭 → 다음만 누르면 끝
• 윈도우: 같은 사이트에서 .msi 파일 다운로드 → 설치 마법사 진행
• 윈도우 사용자가 더 매끄럽게 쓰려면: WSL이라는 윈도우 내부의 리눅스 환경 위에서 설치하는 게 권장됩니다(하지만 입문 단계에선 일반 윈도우 설치로도 충분합니다)

설치 후 터미널을 완전히 닫았다가 다시 열어야 node -v 결과가 보입니다. 이거 모르고 한참 헤매는 분들 많습니다. 저도 그랬습니다.

해결법 2. PATH에 npm 글로벌 경로 추가하기

Node.js는 멀쩡한데 claude만 안 잡히면 가장 흔한 원인이 이겁니다. npm으로 설치한 도구가 들어가는 폴더를 PATH가 모르는 경우입니다.

먼저 npm이 어디다 도구를 깔았는지 확인합니다.

npm config get prefix

이 명령은 "npm이 도구를 저장하는 본부 주소"를 보여줍니다. 예를 들어 /usr/local이 나왔다면, 실제 실행 파일은 /usr/local/bin/에 들어 있습니다.

이제 이 경로를 PATH에 추가해야 합니다. 맥/리눅스 기준으로 터미널에 이렇게 입력합니다.

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

첫 줄은 설정 파일에 PATH 추가 명령을 적어두는 것이고, 두 번째 줄은 그 변경을 지금 즉시 반영합니다.

💡 맥의 기본 셸이 zsh라 .zshrc를 씁니다. 만약 bash를 쓰고 있다면 .bashrc나 .bash_profile로 바꿔주세요. 자기 셸이 뭔지 모르겠으면 echo $SHELL 입력하면 나옵니다.

해결법 3. 권한 문제로 글로벌 설치가 실패한 경우

설치할 때 sudo를 안 쓰고 그냥 npm install -g @anthropic-ai/claude-code로 깔았다가 권한 에러가 떴는데 모르고 지나갔을 수 있습니다.

이 경우 설치가 중간에 멈춰서 실행 파일이 안 만들어진 상태입니다. 다시 깔되, npm 자체의 설치 위치를 사용자 폴더로 옮기는 게 깔끔합니다(sudo 남발은 보안상 권장 안 됨).

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

순서대로 ① 내 폴더 안에 새 작업 공간 만들고 ② npm한테 거기 쓰라고 알려주고 ③ PATH에 추가하고 ④ 적용하고 ⑤ 재설치.

저는 맥에서 이 방법으로 두 번째 시도에 성공했습니다. 첫 시도 때는 sudo로 밀어붙였다가 다른 npm 패키지들이 줄줄이 권한 꼬여서 결국 다 지우고 다시 했거든요. sudo 남발은 비추천입니다.

해결법 4. 셸을 완전히 새로 열기

이게 의외로 가장 흔한 "해결법"입니다. 솔직히 말하면 첫 번째로 시도해야 할지도 모릅니다.

PATH 설정을 바꿔도 현재 열려 있는 터미널 창은 옛날 설정을 들고 있습니다. 새로 연 창에서만 새 설정이 적용됩니다.

다음을 시도해보세요.

• [ ] 터미널 창을 모두 닫는다 (그냥 최소화 ❌, 완전히 종료)
• [ ] 터미널 앱 자체를 종료한다 (맥은 Cmd+Q)
• [ ] 다시 열어서 claude --version 입력

그래도 안 되면 컴퓨터를 한 번 재시작해보세요. 너무 원시적으로 들리지만, 환경 변수 관련 문제는 재시작으로 절반은 풀립니다.

해결법 5. Node 버전이 너무 낮은 경우

node -v가 v16 이하라면 업그레이드가 필요합니다. Claude Code는 Node 18 이상에서 동작합니다.

가장 깔끔한 방법은 nvm(엔브이엠, Node Version Manager)을 쓰는 것입니다. 여러 버전의 Node를 갈아끼울 수 있게 해주는 도구입니다.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

설치 후 터미널 새로 열고:

nvm install --lts
nvm use --lts

LTS(Long Term Support)는 장기 지원 안정 버전이라는 뜻으로, 일반 사용자는 무조건 이걸 쓰면 됩니다.

업그레이드 후에는 Claude Code를 다시 설치해야 합니다. Node 버전이 바뀌면 그 위에 깔린 도구는 새 버전 입장에선 처음 보는 것이거든요.

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

해결법 6. 자주 막히는 부분 모음

위 5가지로 해결 안 되는 케이스들이 있습니다. 제가 직접 겪었거나, Stack Overflow·Anthropic 커뮤니티에서 자주 보이는 사례들입니다.

증상	원인	해결
맥에서 claude 입력 시 권한 팝업 후 차단	Gatekeeper(맥 보안 기능)가 막음	시스템 설정 → 개인정보 보호 및 보안 → 차단된 항목 허용
윈도우에서 PATH 추가했는데 여전히 안 잡힘	시스템 환경 변수 vs 사용자 환경 변수 혼동	제어판 → 시스템 → 고급 시스템 설정 → 환경 변수에서 양쪽 확인
VS Code 터미널에서만 안 잡힘	VS Code가 옛날 PATH를 기억 중	VS Code 완전히 종료 후 재시작
claude 입력 시 다른 프로그램이 실행됨	같은 이름의 다른 도구와 충돌	which -a claude로 충돌 확인 후 하나 제거
회사 노트북에서만 안 됨	보안 정책상 글로벌 설치 차단	IT팀에 문의 또는 npx로 일회성 실행

특히 회사 노트북 케이스는 직접 해결하기 어렵습니다. 사내 보안 솔루션이 npm 글로벌 설치 자체를 막는 경우가 있어요. 이때는 무리하지 말고 IT팀에 문의하는 게 빠릅니다.

해결법 7. 그냥 처음부터 다시 깔기

부끄럽게도, 1~6번을 다 시도하고도 안 되면 재설치가 가장 빠릅니다. 솔직히 30분 헤맬 바엔 5분 만에 깔끔하게 다시 까는 게 낫습니다.

순서는 이렇습니다.

npm uninstall -g @anthropic-ai/claude-code
npm cache clean --force
npm install -g @anthropic-ai/claude-code
claude --version

각 줄의 의미는 ① 기존 설치 제거 ② npm이 캐시(임시 저장본)로 갖고 있는 옛날 파일 강제 청소 ③ 새로 설치 ④ 버전 확인으로 성공 여부 체크.

마지막 명령에서 버전 번호(예: 0.2.x)가 뜨면 성공입니다.

⚠️ 글 작성 시점 기준 Claude Code는 활발히 업데이트되는 중이라 명령어나 옵션이 달라질 수 있습니다. 공식 문서(docs.anthropic.com)에서 최신 설치 방법을 한 번 확인하는 걸 추천합니다.

흔한 실수와 빠른 체크리스트

마지막으로 시간을 절약해줄 체크리스트입니다. 다음에 또 막히면 이 순서로 점검하세요.

• [ ] 터미널을 완전히 새로 열었는가
• [ ] node -v가 18 이상인가
• [ ] npm config get prefix 경로가 PATH에 들어 있는가
• [ ] 설치 중 빨간색 에러 메시지를 놓치지 않았는가
• [ ] VS Code 같은 IDE 터미널이 아닌 순수 터미널 앱에서 테스트했는가
• [ ] 회사 보안 정책이 글로벌 npm 설치를 막고 있진 않은가

특히 네 번째, 설치 중 빨간 글씨는 진짜 중요합니다. 화면이 빨리 지나가서 못 본 분들이 많은데, 위로 스크롤해서 ERROR 또는 ERR! 같은 단어를 검색해보세요. 거기 답이 있는 경우가 절반 이상입니다.

마무리

"command not found"는 무서워 보이지만 결국 "어디 있는지 못 찾겠어"라는 메시지일 뿐입니다. 7가지 해결법 중 본인 상황에 맞는 1~2개만 적용하면 대부분 풀립니다.

만약 위 방법으로도 안 되면, 에러 화면 전체를 스크린샷으로 찍어서 Anthropic 디스코드나 GitHub Issues에 올려보세요. 비슷한 사례가 이미 올라와 있을 가능성이 높습니다.

Claude Code가 잘 설치되면 그 다음부턴 진짜 재미있어집니다. 폴더 안에서 자연어로 코드를 시키는 경험은 한 번 맛보면 못 돌아가거든요. 그 첫 단추가 이 에러에 막혀 끊기지 않길 바라며, 여기서 마칩니다.

함께 보면 좋은 글

• Claude Artifacts 예시 7가지 — 직접 만들어본 미니앱
• Claude Code Skills 활용법, 직접 만든 5가지 스킬 후기
• Claude Fable 사용법과 보안 논란, 비개발자가 꼭 알아야 할 점