claude command not found 해결방법 — 설치 후 오류 가이드
Claude Code를 설치했는데
claude command not found오류가 뜬다면? 원인은 대부분 PATH 설정 문제입니다. Windows·Mac·Linux 환경별 해결 방법을 단계별로 정리했습니다. 이 글 하나로 오류를 끝내세요.
claude command not found, 왜 생기는 걸까?
설치는 분명히 됐는데 명령어가 안 먹힌다. 이 오류를 처음 보면 당황스럽습니다.
하지만 원인은 단순합니다. 터미널이 claude 실행 파일을 어디서 찾아야 하는지 모르는 것입니다.
터미널은 명령어를 입력받으면 PATH라는 환경 변수에 등록된 폴더들을 순서대로 뒤집니다.claude가 설치된 폴더가 PATH에 없으면, 파일이 분명 존재해도 “없다”고 나옵니다.
즉, 파일 자체의 문제가 아니라 경로 등록의 문제입니다.
크게 두 가지 패턴으로 나뉩니다.
| 패턴 | 증상 |
|---|---|
| PATH 미등록 | 설치 후 즉시 오류, 재설치해도 동일 |
| 터미널 세션 미갱신 | 설치 직후는 오류, 새 창 열면 정상 |
먼저 확인할 것 — 터미널 재시작
가장 흔한 원인이자 가장 단순한 해결책입니다.
설치 직후에는 PATH 변경이 현재 열린 터미널에 아직 반영되지 않습니다.
지금 쓰는 터미널 창을 완전히 닫고 새 창을 여세요.
새 창에서 다시 claude --version을 입력했을 때 버전이 뜨면 해결된 겁니다.
그래도 안 된다면 아래 환경별 해결법으로 넘어가세요.
Windows 환경별 해결방법
Windows에서 이 오류가 특히 많이 발생하는 이유는 터미널 종류가 여러 개이기 때문입니다.
PowerShell, cmd, Git Bash, WSL은 각각 독립된 환경으로 PATH를 따로 관리합니다.
PowerShell / cmd에서 오류가 날 때
npm으로 설치했다면 실행 파일이 AppData\Roaming\npm 폴더에 들어갑니다.
이 폴더가 PATH에 없을 때 오류가 납니다.
Step 1. npm 글로벌 경로 확인
npm config get prefix
보통 C:\Users\사용자이름\AppData\Roaming\npm 형태로 출력됩니다.
Step 2. 해당 경로를 PATH에 추가 (PowerShell 관리자 권한)
$npmPath = npm config get prefix
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$npmPath", "User")
Step 3. 터미널 완전히 닫고 새 창 열기
새 PowerShell 창에서 claude --version으로 확인합니다.
Git Bash에서만 오류가 날 때
cmd나 PowerShell에서는 되는데 Git Bash에서만 안 된다면, Git Bash가 npm 글로벌 경로를 인식 못하는 것입니다.
Git Bash는 Unix 방식 PATH를 사용하기 때문에 Windows 경로를 변환해서 등록해야 합니다.
.bashrc 파일에 아래 줄을 추가하세요.
echo 'export PATH="$PATH:/c/Users/사용자이름/AppData/Roaming/npm"' >> ~/.bashrc
source ~/.bashrc
사용자이름 부분을 본인의 Windows 사용자 이름으로 바꿔서 입력하세요.
근본 해결 — 공식 네이티브 설치로 전환
2026년 현재 Anthropic은 npm 방식보다 네이티브 인스톨러를 공식 권장합니다.
PowerShell을 열고 아래 명령어 하나만 실행하면 PATH 문제 없이 설치됩니다.
irm https://claude.ai/install.ps1 | iex
설치 후 새 터미널 창을 열면 바로 claude 명령어를 쓸 수 있습니다.
macOS / Linux 환경 해결방법
~/.local/bin 경로 추가
macOS와 Linux에서는 Claude Code가 ~/.local/bin 폴더에 설치됩니다.
이 경로가 PATH에 빠져 있으면 동일한 오류가 납니다.
zsh 사용자 (macOS 기본 셸)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
bash 사용자
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
설정 후 claude --version으로 정상 작동을 확인하세요.
네이티브 설치 명령어 (macOS / Linux 공통)
curl -fsSL https://claude.ai/install.sh | bash
설치 완료 후 새 터미널 창을 열면 바로 사용 가능합니다.sudo는 절대 붙이지 마세요. 권한 오류의 원인이 됩니다.
설치 자체가 문제일 때 — claude doctor 진단
PATH를 고쳐도 오류가 계속된다면, 설치 자체에 문제가 있을 수 있습니다.
이럴 때는 Claude Code 내장 진단 명령어를 써보세요.
claude doctor
설치 방식, 버전, 오류 여부를 한눈에 보여줍니다.
진단 결과에 문제가 있다면 아래처럼 완전히 지우고 재설치하는 것이 가장 빠릅니다.
macOS / Linux 재설치
rm -rf ~/.claude
curl -fsSL https://claude.ai/install.sh | bash
Windows 재설치 (PowerShell)
irm https://claude.ai/install.ps1 | iex
자주 실수하는 것들
처음 Claude Code를 설치할 때 많이 겪는 실수들을 정리했습니다.
sudo 사용 금지sudo npm install -g로 설치하면 실행 파일이 시스템 폴더에 들어가서 일반 사용자 권한으로는 실행이 안 됩니다. sudo 없이 설치하세요.
여러 개 설치 금지
npm, 네이티브 인스톨러, Homebrew를 동시에 설치하면 충돌이 납니다. 하나만 유지하세요.
Node.js 버전 확인
npm 방식을 쓴다면 Node.js 18 이상이 필요합니다. node -v로 버전을 확인하세요.
WSL과 Windows 혼용 주의
Windows에서 설치한 Claude Code는 WSL에서 동작하지 않습니다. 환경을 분리해서 관리하세요.
정리
claude command not found 오류는 대부분 PATH 미등록 또는 터미널 미갱신이 원인입니다.
해결 순서는 간단합니다.
- 터미널 새 창 열기
- npm 글로벌 경로 PATH에 추가
- 그래도 안 되면 네이티브 인스톨러로 재설치
가장 빠르고 안정적인 방법은 처음부터 공식 네이티브 인스톨러를 쓰는 것입니다.
설치 방법만 바꿔도 PATH 문제 대부분은 사라집니다.
Claude Code 설치 이후 기본 사용법이 궁금하다면, 공식 문서를 참고하세요.
