AI · · 읽는 시간 2분

Claude Code 설치 후 command not found 에러 해결법 (PATH 설정)

이 글의 차례
  1. 해결 방법
  2. 1. Zsh 환경 (macOS 기본)
  3. 2. Bash 환경 (Linux 기본)
  4. 원인: command not found가 발생하는 이유
  5. 상황별 점검 및 추가 해결 방법
  6. 1. 현재 사용 중인 쉘 확인
  7. 2. 실행 바이너리가 실제로 존재하는지 확인
  8. 3. npm 글로벌 설치(npm install -g @anthropic-ai/claude-code)를 사용한 경우
  9. PATH 등록 명령어 설명

Claude Code를 설치한 후 터미널에서 claude 명령어 실행 시 command not found: claude 오류가 발생하는 원인과, macOS(Zsh) 및 Linux(Bash) 환경별 PATH 환경변수 설정 방법을 정리했습니다.

해결 방법

Claude Code 실행 바이너리가 위치한 디렉터리(~/.local/bin 또는 npm 글로벌 경로)를 쉘 환경설정 파일의 PATH에 추가하면 즉시 해결됩니다.

1. Zsh 환경 (macOS 기본)

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. Bash 환경 (Linux 기본)

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

설정 후 터미널에서 버전을 확인합니다:

claude --version

원인: command not found가 발생하는 이유

터미널에서 명령어를 입력하면 쉘은 환경변수 $PATH에 등록된 디렉터리 목록을 순차적으로 탐색하여 실행 파일을 찾습니다.

Anthropic의 공식 설치 스크립트(curl -fsSL https://claude.ai/install.sh | bash)를 사용해 설치한 경우, claude 바이너리는 기본적으로 $HOME/.local/bin/claude 경로에 배치됩니다.

하지만 운영체제나 기본 쉘 설정에 따라 ~/.local/bin 디렉터리가 $PATH에 기본 등록되어 있지 않거나, 설치 스크립트 실행 후 현재 쉘 세션에 반영되지 않아 탐색에 실패하게 됩니다.

상황별 점검 및 추가 해결 방법

1. 현재 사용 중인 쉘 확인

터미널 환경에 따라 설정 파일이 다릅니다:

echo $SHELL
  • /bin/zsh ➔ ~/.zshrc 파일 수정
  • /bin/bash ➔ ~/.bashrc (또는 환경에 따라 ~/.bash_profile) 수정

2. 실행 바이너리가 실제로 존재하는지 확인

바이너리가 정상 설치되었는지 직접 경로로 실행해 확인합니다:

~/.local/bin/claude --version

만약 이 명령어로 정상 실행된다면, 바이너리 자체는 정상적으로 설치된 것이며 PATH 등록만 누락된 상태입니다.

3. npm 글로벌 설치(npm install -g @anthropic-ai/claude-code)를 사용한 경우

npm을 통해 설치했다면 npm 글로벌 바이너리 경로가 PATH에 없을 수 있습니다. npm 글로벌 bin 경로를 확인한 후 등록합니다:

# npm 글로벌 bin 경로 확인
npm prefix -g

# Zsh 기준 PATH 추가
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

PATH 등록 명령어 설명

  • export PATH="$HOME/.local/bin:$PATH": 기존 $PATH의 맨 앞에 ~/.local/bin을 추가하여 해당 경로의 실행 파일을 우선적으로 탐색하도록 지정합니다.
  • source ~/.zshrc: 수정된 설정 파일을 현재 실행 중인 쉘 세션에 즉시 다시 로드합니다. 터미널 창을 닫고 새로 열어도 동일하게 적용됩니다.
1 / 1