zsh: command not found: claude 해결, Claude Code 설치 후 PATH 추가하는 법 (2026년 10월 기준)

Claude Code를 설치했는데 터미널에 claude를 치면 "zsh: command not found: claude"가 나온다면, 프로그램은 깔렸는데 그 폴더가 PATH에 없어서 그래요. 맥과 리눅스는 ~/.local/bin 을 PATH에 한 줄 추가하고 새 터미널을 열면 해결됩니다.

이 글은 2026년 10월 17일에 Claude Code 공식 문서의 Set up Claude Code, Troubleshoot installation and login 페이지를 읽고 정리했어요. 명령어 흐름은 맥 터미널에서 직접 돌려 봤습니다.

테스트 환경: macOS 26.6.2, zsh 5.9

에러 문구는 셸마다 달라요

공식 문서에 나온 운영체제별 문구는 아래와 같아요. 문구는 달라도 원인은 같습니다.

환경	보이는 문구
맥 (zsh)	zsh: command not found: claude
리눅스 (bash)	bash: claude: command not found
윈도우 CMD	'claude' is not recognized as an internal or external command
윈도우 PowerShell	claude : The term 'claude' is not recognized as the name of a cmdlet

설치는 됐는데 왜 못 찾을까

공식 설치 명령(curl -fsSL https://claude.ai/install.sh | bash)은 실행 파일을 맥과 리눅스에서는 ~/.local/bin/claude 에, 윈도우에서는 %USERPROFILE%\.local\bin\claude.exe 에 둡니다. 셸은 PATH에 적힌 폴더만 뒤져서 명령을 찾기 때문에, 이 폴더가 PATH에 없으면 파일이 있어도 못 찾아요.

설치 프로그램은 이 상황을 알아채고 출력의 "Setup notes:" 부분에 "Native installation exists but ~/.local/bin is not in your PATH." 라고 알려 줍니다. 다만 PATH를 직접 고쳐 주지는 않아요. 설치 직후 출력을 그냥 넘겼다면 이 줄을 놓쳤을 가능성이 큽니다.

VS Code 확장만 깔았을 때도 같은 증상이 나와요. 확장은 자기 채팅 창용으로 CLI를 따로 들고 있고 PATH에는 추가하지 않습니다. 터미널에서 쓰려면 위 설치 명령을 따로 실행해야 해요.

맥 zsh에서 그대로 재현해 봤어요

이 맥에는 Claude Code를 설치하지 않았어요. 대신 시험용 홈 폴더를 만들고, 설치 프로그램이 쓰는 위치(~/.local/bin/claude)에 이름만 같은 시험용 스크립트를 두고 PATH 동작만 재현했습니다.

zsh: command not found: claude

파일이 진짜 있는지, PATH에 그 폴더가 있는지 차례로 확인했어요.

ls ~/.local/bin/
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
echo "grep exit code: $?"

claude
grep exit code: 1

파일은 있는데 PATH 검색 결과는 아무것도 안 나오고 종료 코드가 1이에요. 딱 이 경우가 PATH 문제입니다.

해결: PATH에 한 줄 추가

맥 기본 셸인 zsh라면 아래 두 줄이에요. 첫 줄은 새 터미널마다 적용되게 저장하고, 두 번째 줄은 지금 창에 바로 적용합니다.

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

실행한 뒤 PATH 검색, grep -n '.local/bin' ~/.zshrc, which -a claude, claude --version 을 차례로 쳐 보니 이렇게 나왔어요. 마지막 줄은 시험용 스크립트가 찍은 문구라서, 실제 설치였다면 여기에 버전 번호가 나옵니다.

/tmp/cchome/.local/bin
1:export PATH="$HOME/.local/bin:$PATH"
/tmp/cchome/.local/bin/claude
test stub: not real Claude Code

리눅스 bash는 같은 줄을 ~/.bashrc 에, 맥에서 bash를 쓰면 ~/.bash_profile 에 넣으라고 공식 문서에 나와 있어요. 맥 터미널은 bash를 로그인 셸로 띄워서 ~/.bashrc 를 읽지 않기 때문이에요.

윈도우 PowerShell은 사용자 PATH에 폴더를 추가하고 터미널을 다시 열면 됩니다.

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

그래도 안 될 때 볼 곳

Q. 줄을 추가했는데 여전히 command not found가 나와요.

이미 열려 있던 터미널은 예전 PATH를 그대로 들고 있어요. VS Code나 IntelliJ 안의 터미널은 편집기의 PATH를 물려받으니 편집기까지 껐다 켜야 합니다. grep -n '.local/bin' ~/.zshrc 로 줄이 저장됐는지도 확인해 보세요.

Q. zsh에 넣었는데 bash에서는 안 돼요.

셸마다 읽는 설정 파일이 달라요. 시험용 홈에서 zsh 설정만 고친 채 bash로 같은 명령을 치니 "bash: claude: command not found"가 그대로 나왔습니다. echo $0 으로 지금 셸을 확인하고 그 셸의 파일에 넣으면 돼요.

Q. 예전에 npm으로도 깔았는데 괜찮을까요?

설치가 여러 개면 버전이 엇갈릴 수 있어요. which -a claude 로 잡히는 걸 모두 보고, 공식 문서는 ~/.local/bin/claude 네이티브 설치 하나만 남기길 권합니다. npm 쪽은 npm uninstall -g @anthropic-ai/claude-code 로 지워요.

Q. 실행은 되는데 뭔가 이상해요.

claude doctor 를 터미널에서 치면 세션을 열지 않고 설치 상태와 설정 오류를 점검해 줍니다. 참고로 Claude Code는 Pro, Max, Team, Enterprise, Console 계정이 필요하고 무료 플랜에는 들어 있지 않아요.

관련 글: zsh: permission denied: ./test.sh 오류 해결 (chmod +x 실행 권한, 맥 터미널)

이 글의 내용은 공식 문서로 확인했고, 정리에는 AI 도구를 활용했습니다.

출처: Claude Code 공식 문서 Set up Claude Code, Troubleshoot installation and login (code.claude.com, 2026년 10월 17일 확인)