[바이브코딩] Claude Code command not found 해결법 — 설치했는데 명령어가 안 될 때 확인할 것

claude를 입력했는데 command not found가 뜬다면 재설치부터 할 필요는 없습니다.

대부분은 PATH 갱신, 설치 위치, 셸 설정, 구버전 충돌 중 하나가 원인입니다. 이 글은 진단 순서대로 확인해 5분 안에 원인을 좁히는 방법을 정리합니다.

이 글에서 해결할 문제

"Claude Code 설치했는데 안 돼요"를 검색하면 나오는 글들이 대부분 "재설치하세요"로 끝나요. 사실 원인은 4가지로 정해져 있고, 진단 순서만 알면 1~2분이면 끝나는 문제거든요.

• 설치 후 claude 명령을 쳤더니 claude: command not found가 뜨는 분
• npm으로 깔았는데 버전이 옛날이거나 실행이 안 되는 분
• 설치 메시지에 PATH 관련 안내가 떴는데 무슨 말인지 모르는 분
• Warp·iTerm2·VS Code 통합 터미널처럼 서드파티 터미널에서만 안 되는 분

아래 진단 흐름대로 따라가면 어떤 셸을 쓰든 5분 안에 해결됩니다.

누가 읽으면 좋은가

• ✅ Claude Code 설치는 진행됐는데 명령어가 안 먹는 분
• ✅ macOS·Linux·WSL에서 새 셸/터미널을 자주 바꾸는 분
• ✅ npm 전역 설치(npm install -g) 후 명령어가 사라지는 경험을 한 분
• ✅ Warp·iTerm2·Tabby 같은 서드파티 터미널 사용자
• ❌ 아직 설치를 안 한 분은 공식 빠른 시작 가이드를 먼저 보세요

전제 지식: 터미널을 열고 명령어 한 줄을 입력할 수 있는 수준이면 충분합니다.

목차

1. 이 글에서 해결할 문제
2. 누가 읽으면 좋은가
3. 핵심 용어와 원인 요약
4. 해결방법 1: 터미널 재시작과 설치 확인
5. 해결방법 2: Node.js·npm 경로 확인
6. 해결방법 3: PATH 문제 확인
7. 해결방법 4: macOS·Warp·iTerm2에서 확인할 것
8. 비대화형 환경에서 확인할 것
9. 어떤 방법부터 시도할지 — 선택 기준
10. 지금 바로 할 수 있는 것 (적용 전 점검 포인트)
11. FAQ
12. 참고자료

핵심 용어와 원인 요약 — 왜 command not found가 뜨는가

• PATH — 터미널이 명령어를 찾을 때 뒤지는 폴더 목록. PATH에 없는 폴더의 실행 파일은 항상 "command not found"가 뜹니다.
• 셸(Shell) — 터미널에서 명령어를 해석하는 프로그램. macOS는 기본 zsh, 리눅스는 보통 bash. 셸마다 설정 파일이 다릅니다.
• ~/.zshrc / ~/.bashrc — 셸이 시작할 때 자동으로 읽는 설정 파일. PATH 추가는 보통 여기에 씁니다.
• 네이티브 설치(Native Install) — Anthropic 공식 설치 스크립트(curl … install.sh | bash). Node.js 의존성 없이 ~/.claude/bin/에 바이너리를 둡니다.
• npm 전역 설치 — npm install -g @anthropic-ai/claude-code 방식. 옛 가이드에서 쓰던 방법으로, 지금은 PATH 충돌 원인 1순위입니다.

command not found가 뜨는 4가지 원인 (빈도순):

1. 설치는 됐지만 터미널을 재시작하지 않아 PATH가 갱신되지 않음
2. npm 전역 경로가 PATH에 없거나 nvm·asdf 같은 버전관리자와 충돌
3. 설치 스크립트가 추가하려던 PATH 줄이 ~/.zshrc에 누락됨
4. Warp·iTerm2·VS Code 통합 터미널이 다른 셸 프로파일을 로드

해결방법 1: 터미널 재시작과 설치 확인 — 가장 흔한 원인

설치 직후 claude가 안 먹는 케이스 중 절반 이상이 여기서 해결됩니다.

1-1. 터미널 창을 완전히 닫고 다시 열기

탭만 새로 여는 게 아니라 창 자체를 종료해야 합니다. macOS 기준 Cmd + Q로 터미널 앱을 완전히 종료한 뒤 Spotlight로 다시 여세요. Windows PowerShell도 동일합니다.

1-2. 셸 설정 다시 불러오기 (재시작 없이)

창을 닫기 귀찮으면 셸 설정 파일을 즉시 다시 읽을 수 있어요.

# macOS / zsh
source ~/.zshrc

# Linux / bash
source ~/.bashrc

# fish 셸
source ~/.config/fish/config.fish

이 명령으로도 안 되면 PATH가 아예 추가되지 않은 상태입니다 → 해결방법 3으로 넘어가세요.

1-3. 설치 자체를 검증

설치가 정상적으로 끝났는지 확인합니다.

# 바이너리 위치 확인
ls -la ~/.claude/bin/claude

# 실행 파일 권한 확인 (-rwxr-xr-x 형태여야 함)
file ~/.claude/bin/claude

파일이 없다면 설치가 실패한 겁니다. 설치 명령을 다시 실행하세요.

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

해결방법 2: Node.js·npm 경로 확인 — 옛날 설치 방식의 흔적

예전 가이드를 보고 npm install -g @anthropic-ai/claude-code로 설치한 경우 가장 많이 막힙니다.

2-1. 현재 npm 전역 경로 확인

npm prefix -g
# 출력 예: /Users/sam/.nvm/versions/node/v20.10.0
# 또는: /opt/homebrew/lib

여기에 나온 경로 + /bin이 PATH에 들어 있어야 npm 전역 명령어가 실행됩니다.

2-2. nvm·asdf 사용자가 자주 막히는 이유

nvm은 Node 버전을 바꿀 때마다 전역 패키지 경로가 함께 바뀝니다. nvm use 18로 바꿨다면 18 버전 폴더에만 claude가 설치돼 있고, 다른 버전으로 바꾸면 사라진 것처럼 보여요.

해결: 네이티브 설치로 마이그레이션하세요. Anthropic이 권장하는 방식이고 Node 버전과 완전히 분리됩니다.

# 기존 npm 버전 제거
npm uninstall -g @anthropic-ai/claude-code

# 네이티브로 재설치
curl -fsSL https://claude.ai/install.sh | bash

# 새 셸에서 확인
claude --version

2-3. Homebrew로 설치한 경우

brew install --cask claude-code로 설치했다면 PATH는 자동으로 잡혀 있어야 정상이에요. 안 되면:

brew doctor
brew link --overwrite claude-code

해결방법 3: PATH 문제 확인 — 원인 진단

위 두 단계로 안 되면 PATH를 직접 확인할 차례입니다. 사실 이 케이스가 "command not found"의 본질이에요.

3-1. 현재 PATH 출력

echo $PATH

콜론(:)으로 구분된 폴더 목록이 줄줄 나옵니다. 여기에 ~/.claude/bin 또는 npm 전역 bin 경로가 들어 있어야 해요.

3-2. claude 바이너리 위치와 PATH 비교

# claude 바이너리가 실제로 어디 있는지
which claude
# 아무것도 안 나오면 → PATH에 등록 안 됨

# 직접 경로로 실행해서 동작 자체는 확인
~/.claude/bin/claude --version

직접 경로로는 실행되는데 claude만 치면 안 된다 → PATH 설정만 빠진 것. 거의 다 왔습니다.

3-3. ~/.zshrc에 PATH 직접 추가

설정 파일을 열어 마지막 줄에 추가하세요.

# macOS / zsh
echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Linux / bash
echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

⚠️ 주의: 같은 줄을 두 번 넣으면 PATH가 길어지지만 동작은 같습니다. 헷갈리면 nano ~/.zshrc로 열어 중복된 줄을 정리하세요.

해결방법 4: macOS·Warp·iTerm2에서 확인할 것 — 서드파티 터미널 함정

기본 Terminal.app에서는 잘 되는데 Warp나 VS Code 통합 터미널에서만 안 되는 경우가 의외로 많아요.

4-1. Warp Terminal

Warp는 자체적으로 셸 통합 스크립트를 주입합니다. ~/.zshrc에 추가한 PATH가 Warp의 자동 주입 순서 때문에 늦게 로드돼 가려질 수 있어요.

• Warp 설정 → Subshells 또는 Shell Integration 항목 확인
• printenv PATH로 Warp 안에서의 실제 PATH 출력 후 ~/.claude/bin 포함 여부 확인
• 안 보이면 Warp 재시작 → 그래도 안 되면 PATH 줄을 ~/.zprofile(zsh 로그인 셸용)에도 동일하게 추가

4-2. iTerm2

iTerm2는 보통 ~/.zshrc를 정상 로드하지만, "로그인 셸로 시작" 옵션 여부에 따라 PATH가 누락됩니다.

• iTerm2 → Preferences → Profiles → General → Command → Login shell 체크
• 또는 PATH 줄을 ~/.zprofile에 추가 (로그인 셸 시작 시 읽힘)

4-3. VS Code 통합 터미널

VS Code를 GUI로 띄울 때 셸 환경변수를 전부 못 가져오는 경우가 있어요.

• VS Code 설정에서 terminal.integrated.inheritEnv를 true로
• 또는 VS Code를 터미널에서 code .로 실행 (환경변수 상속)

4-4. macOS Sequoia 이후 권한 이슈

macOS는 다운로드한 실행 파일에 Quarantine 속성을 붙입니다. 설치 직후 권한이 차단됐다면:

xattr -d com.apple.quarantine ~/.claude/bin/claude

비대화형 환경에서 확인할 것

터미널에서는 claude가 실행되는데 LaunchAgent·cron·CI에서만 command not found가 발생한다면 설치 문제가 아니라 실행 환경의 PATH 차이를 확인해야 합니다.

비대화형 환경은 로그인 셸과 달리 ~/.zshrc를 읽지 않을 수 있습니다. 따라서 터미널에서 정상 실행된다는 사실만으로 자동 실행 환경도 정상이라고 판단할 수 없습니다.

확인 방법: plist의 EnvironmentVariables에 PATH를 명시하거나, 셸 스크립트에서 /Users/계정/.claude/bin/claude처럼 절대 경로로 호출하세요.

로그인 셸과 비대화형 셸의 PATH를 각각 출력해 비교하면 원인을 빠르게 좁힐 수 있습니다.

어떤 방법부터 시도할지 — 선택 기준

증상	먼저 시도	그래도 안 되면
방금 설치했고 한 번도 안 됨	해결방법 1 (터미널 재시작)	해결방법 3 (PATH 확인)
npm으로 깔았는데 안 됨	해결방법 2 (네이티브 마이그레이션)	해결방법 3 (PATH 확인)
Terminal.app에선 되는데 Warp에서 안 됨	해결방법 4-1 (Warp)	~/.zprofile에 PATH 추가
cron·LaunchAgent에서 안 됨	절대 경로로 호출	plist EnvironmentVariables
which claude는 나오는데 실행 안 됨	해결방법 4-4 (Quarantine)	실행 권한 chmod +x

지금 바로 할 수 있는 것 (적용 전 점검 포인트) — 단기 대응방안

• ☐ 터미널 창을 완전히 닫고 새로 열었다
• ☐ ls -la ~/.claude/bin/claude로 바이너리가 존재함을 확인했다
• ☐ ~/.claude/bin/claude --version 직접 경로로는 실행된다
• ☐ echo $PATH 결과에 ~/.claude/bin이 들어 있다
• ☐ ~/.zshrc 또는 ~/.bashrc에 PATH 추가 줄이 있다
• ☐ source ~/.zshrc로 셸 설정을 다시 불러왔다
• ☐ Warp·VS Code 통합 터미널이라면 로그인 셸 옵션을 확인했다

위 항목에서 차이가 나는 지점을 찾으면 재설치 없이 해결 경로를 좁힐 수 있습니다.

자주 묻는 질문 (FAQ)

Q. 재설치하면 해결되나요?

대부분 해결되지만, 원인을 모른 채 재설치하면 같은 PATH 문제가 그대로 남습니다. 먼저 which claude와 echo $PATH로 원인을 진단한 다음 필요한 경우에만 재설치하세요.

Q. sudo를 붙이면 되나요?

안 됩니다. sudo는 권한을 올려주는 명령이지 PATH 문제를 해결하지 않아요. 오히려 sudo 환경의 PATH는 더 제한적이라 "command not found"가 더 자주 뜹니다.

Q. WSL(Windows Subsystem for Linux)에서도 똑같이 적용되나요?

네. WSL은 사실상 Linux이므로 ~/.bashrc 또는 ~/.zshrc에 PATH 추가 + source로 동일하게 해결됩니다. PowerShell과는 별개의 환경이라는 점만 기억하세요.

Q. ~/.zshrc와 ~/.zprofile, 어디에 PATH를 적어야 하나요?

일반 사용에는 ~/.zshrc로 충분합니다. 다만 Warp나 GUI 앱처럼 "로그인 셸"로 시작하는 환경에서만 안 되는 케이스가 있는데, 이때는 ~/.zprofile에도 같은 줄을 넣어두면 양쪽 다 커버됩니다.

Q. Claude Code를 완전히 지우고 다시 깔고 싶어요.

네이티브 설치는 rm -rf ~/.claude로 완전 제거됩니다. npm 전역 설치는 npm uninstall -g @anthropic-ai/claude-code. Homebrew Cask는 brew uninstall --cask claude-code. 모두 지운 뒤 네이티브 설치 스크립트로 깔면 깨끗하게 시작됩니다.

Q. 회사 노트북이라 PATH를 못 건드려요. 다른 방법은요?

가능합니다. 셸 alias를 쓰면 PATH를 안 건드려도 돼요. alias claude="$HOME/.claude/bin/claude"를 ~/.zshrc에 추가하고 source ~/.zshrc 하면 됩니다. 다만 alias는 셸 안에서만 동작하므로 자동화 스크립트에서는 절대 경로를 써야 해요.

참고자료

• Claude Code 공식 빠른 시작 가이드 (한국어) — Anthropic
• Claude Code 문제 해결 가이드 — Anthropic 공식 문서
• Claude Code Setup & Installation — Anthropic Docs (영문)
• Warp Shell Integration 문서 — Warp 공식 블로그
• zsh 시작 파일 공식 문서 (.zshrc vs .zprofile) — zsh 공식 문서