들어가며
Claude Code 공식 설치 스크립트를 실행한 직후, 터미널에서 claude를 입력하면 다음과 같은 에러를 마주치는 경우가 있다.
$ claude
zsh: command not found: claude
설치 자체는 정상적으로 완료됐음에도 불구하고 명령어가 인식되지 않는 이유는 실행 파일이 설치된 경로가 셸의 PATH에 등록되어 있지 않기 때문이다. 이 글에서는 원인을 구체적으로 분석하고 영구적인 해결 방법을 정리한다.
환경
OS: macOS
Shell: zsh (macOS Catalina 이후 기본값)
설치 방법: curl -fsSL https://claude.ai/install.sh | bash
원인 분석
1. 설치 경로
Anthropic의 네이티브 설치 스크립트는 실행 바이너리를 아래 경로에 설치한다.
~/.local/bin/claude
npm 전역 설치(/usr/local/bin)와 달리, ~/.local/bin은 사용자 레벨의 로컬 바이너리 디렉터리로, 루트 권한 없이 쓰기가 가능하고 자동 업데이트를 지원하기 위해 선택된 경로다.
2. macOS 기본 PATH에 ~/.local/bin 미포함
macOS의 기본 PATH를 확인하면 다음과 같이 구성되어 있다.
$ echo $PATH
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
~/.local/bin은 기본적으로 포함되어 있지 않다. 셸은 PATH에 등록된 디렉터리만 탐색하므로, 해당 경로에 실행 파일이 존재하더라도 명령어로 호출할 수 없다.
3. 설치 스크립트의 PATH 자동 등록 미적용 케이스
설치 스크립트는 ~/.zshrc 또는 ~/.bash_profile에 PATH 추가 구문을 자동으로 삽입하는 로직을 포함하고 있으나, 기존 설정 파일 구조나 환경에 따라 적용되지 않는 경우가 있다. 설치 완료 후 현재 세션에 즉시 반영되지 않는 문제도 동일 원인이다.
해결 방법
Step 1. 설치 파일 존재 여부 확인
먼저 바이너리가 실제로 존재하는지 확인한다.
$ ls ~/.local/bin/claude
파일이 없다면 설치 자체가 실패한 것이므로 설치 스크립트를 재실행해야 한다. 파일이 존재한다면 PATH 문제이므로 아래 단계를 진행한다.
Step 2. PATH 추가 (~/.zshrc)
$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc
bash를 사용하는 경우 ~/.zshrc 대신 ~/.bash_profile 또는 ~/.bashrc에 추가한다. source 명령으로 현재 세션에 즉시 반영한다.
Step 3. 동작 확인
$ claude --version
$ claude doctor
claude doctor 실행 시 Auto-updates: true가 출력되면 네이티브 설치와 자동 업데이트가 정상적으로 활성화된 것이다.
npm 설치 vs 네이티브 설치 비교
npm install -g @anthropic-ai/claude-code 방식은 /usr/local/bin에 설치되어 PATH 문제가 없지만, 자동 업데이트를 지원하지 않는다. Anthropic은 네이티브 설치 스크립트(curl 방식) 사용을 공식 권장하고 있으며, 이 방식은 Bun 런타임 기반으로 Node.js 의존성이 없고 시작 속도가 더 빠르다.
# 권장: 네이티브 설치 (자동 업데이트 지원)
curl -fsSL https://claude.ai/install.sh | bash
# 비권장: npm 설치 (자동 업데이트 미지원)
npm install -g @anthropic-ai/claude-code
마치며
command not found 에러는 실행 파일의 부재가 아닌 PATH 미등록으로 발생하는 경우가 대부분이다. ~/.local/bin은 사용자 레벨 바이너리의 표준 경로지만 macOS 기본 환경에는 포함되어 있지 않으므로, 네이티브 설치 방식을 사용하는 경우 ~/.zshrc에 명시적으로 추가해두는 것이 안전하다.
새로운 CLI 도구를 설치할 때 동일한 현상이 반복된다면 PATH 설정을 먼저 점검하는 습관을 들이면 디버깅 시간을 크게 줄일 수 있다.