claude-code: command not found 오류 해결방법
들어가며
최근 Claude Code CLI를 로컬 환경에 설치하는 과정에서 claude-code: command not found 오류를 겪었다.
설치는 정상적으로 완료된 것처럼 보였지만, 특정 터미널 환경에서만 명령어가 동작하지 않는 문제가 발생했다.
필자의 개발 환경
- OS: Windows 10
- IDE: Cursor
- Shell: Git Bash (MINGW64)
- Node 설치 방식: npm global 설치
- Claude Code 설치 방법:
- install.cmd 방식
- npm install -g @anthropic-ai/claude-code
흥미로운 점은:
- ✅ cmd에서는 정상 실행
- ✅ Cursor 내 cmd 터미널에서도 정상 실행
- ❌ Git Bash에서는 command not found
- ❌ PowerShell에서도 동일 증상
이 글은 그 문제를 어떻게 추적하고 해결했는지 정리한 기록이다.
오류 원인
문제의 핵심은 설치 문제가 아니라, bash 설정 파일에 등록된 alias 충돌이었다.
Git Bash에서 claude 명령을 실행했을 때 내부적으로 이런 동작이 일어나고 있었다.
alias claude="claude-code"
즉,
claude 입력
→ bash가 alias를 먼저 확인
→ claude-code로 변환
→ claude-code 실행파일을 찾음
→ 존재하지 않음
→ command not found 발생
왜 이런 일이 생겼을까?
과거 설치 방식(install.cmd 기반)에서 claude-code 실행 파일을 사용하던 흔적이
.bashrc 파일에 남아 있었던 것이다.
현재 최신 CLI는 실행 파일 이름이 claude이므로
alias가 오히려 정상 실행을 방해하고 있었다.
해결 방법
Step 1. 실제 실행 파일 위치 확인
which claude
결과:
/c/Users/사용자명/npm-global/claude
👉 npm 글로벌 설치 자체는 정상이라는 것을 확인했다.
Step 2. alias 존재 여부 확인
type claude
또는
alias
여기서 다음과 같은 설정을 발견했다.
alias claude="claude-code"
Step 3. 임시 해결 (현재 세션에서만 적용)
unalias claude
이 명령은 현재 쉘 세션에서만 alias를 제거한다.
이후 claude 명령이 정상 실행되었다.
Step 4. 영구 해결을 위해 설정 파일 수정
문제의 근원은 .bashrc 파일이었다.
📌 .bashrc 파일의 역할
- bash 실행 시 자동으로 로드되는 설정 파일
- 환경 변수, alias, 함수 등을 등록하는 곳
- 터미널을 열 때마다 자동 실행됨
파일 열기:
code ~/.bashrc
또는
nano ~/.bashrc
아래 줄을 삭제:
alias claude="claude-code"
Step 5. 변경사항 적용
source ~/.bashrc
📌 source 명령의 역할
- 수정된 설정 파일을 현재 세션에 즉시 반영
- 터미널 재시작 없이 적용 가능
각 작업이 의미하는 것
작업역할왜 필요한가
| npm install -g | CLI 실행 파일 생성 | 명령어 자체 설치 |
| which claude | 실행 파일 위치 확인 | 설치 정상 여부 확인 |
| alias 확인 | 명령어 우선순위 확인 | 충돌 원인 파악 |
| unalias | 임시 충돌 제거 | 문제 원인 검증 |
| .bashrc 수정 | 영구 해결 | 재발 방지 |
| source 적용 | 즉시 반영 | 터미널 재시작 불필요 |
핵심 개념 정리
1️⃣ bash의 명령어 탐색 순서
bash는 명령어를 다음 순서로 찾는다.
1. alias
2. shell function
3. builtin
4. PATH에 등록된 실행 파일
즉, alias는 PATH보다 우선한다.
이번 문제는 바로 이 우선순위 때문에 발생했다.
2️⃣ npm 글로벌 설치의 의미
npm install -g는 실행 파일을 생성할 뿐
쉘 설정까지 정리해주지는 않는다.
따라서 과거 설정이 남아 있으면 충돌이 발생할 수 있다.
마치며
이번 이슈는 단순한 command not found 오류처럼 보였지만,
실제 원인은 bash의 alias 우선순위와 설정 파일 충돌이었다.
문제를 해결하면서 다시 한 번 느낀 점은:
CLI 문제의 상당수는 설치가 아니라 “쉘 설정”에서 발생한다.
특히 Windows + Git Bash 환경에서는
과거 설정 잔재가 남아 충돌이 생기기 쉽다.
비슷한 오류를 겪는 분들에게 이 글이 도움이 되었으면 한다.
