Claude Code 설치하고 신나게 claude 쳐봤는데 command not found가 뜨셨나요? 설치가 잘못된 게 아니거든요. 시스템이 실행 파일 위치를 모르는 거예요. 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 쳐보세요. 될 거예요.
여기까지가 해결 방법이고, 아래부터는 "근데 이게 왜 이런 거야?"가 궁금한 분들을 위한 설명입니다.
Windows랑 뭐가 다르길래?
Windows는 설치 프로그램이 환경 변수를 알아서 잡아주잖아요. 그래서 별 생각 없이 쓰게 되거든요.
근데 Mac이랑 Linux는 철학이 좀 달라요. "네 환경은 네가 관리해라"는 방식이에요. 시스템 설정이 개인 설정을 건드리지 않도록 분리해둔 거죠. 보안이랑 효율성을 위한 설계인데, Windows에서 넘어온 분들한테는 솔직히 좀 낯설어요.
쉘(Shell)이 뭔데요?
터미널 쓰다 보면 '쉘'이란 단어가 계속 나오잖아요. 쉽게 말하면 사용자랑 운영체제 사이의 통역사예요.
터미널에 claude라고 치면, 쉘이 그걸 받아서 운영체제한테 "이거 실행해줘"라고 전달하는 거거든요. 검은 화면 자체가 쉘이 아니라, 그 안에서 명령을 처리하는 소프트웨어가 쉘이에요.
대표적으로 Zsh랑 Bash가 있는데, 각각 설정 파일이 다르거든요. 그래서 내가 뭘 쓰는지 아는 게 중요합니다.
왜 command not found가 뜨는 건지
터미널에서 명령어를 치면 쉘이 "이 이름의 프로그램이 어디 있지?" 하면서 미리 등록된 폴더 목록을 뒤져요. 이 목록이 PATH라는 환경 변수에요.
문제는 이거예요. Claude Code는 ~/.local/bin에 설치되거든요. 근데 대부분의 시스템에서 이 경로가 PATH에 안 들어가 있어요. 설치 스크립트가 등록을 시도하긴 하는데, 환경에 따라 누락되거나 현재 터미널에 바로 반영이 안 되는 경우가 있더라고요.
그래서 우리가 직접 등록해주는 거예요.
내 쉘이 뭔지 확인하는 법
터미널에 이거 치면 돼요.
echo $SHELL
/bin/zsh가 나오면 →~/.zshrc에 설정/bin/bash가 나오면 →~/.bashrc에 설정
Bash는 상황에 따라 ~/.bash_profile이나 ~/.profile을 읽기도 해요.
혹시 해당 파일이 없어도 걱정 마세요.
>>연산자는 파일이 없으면 자동으로 새로 만들어주거든요.
명령어 하나하나 뜯어보기
위에서 입력한 명령어들이 실제로 뭘 하는 건지 알아두면 나중에 다른 도구 설치할 때도 써먹을 수 있어요.
echo와 >> — 텍스트를 출력해서 파일 끝에 붙이는 거예요. "설정 파일 맨 아래에 한 줄 추가해라"라는 뜻이에요.
export PATH="..." — 기존 PATH 앞에 ~/.local/bin을 추가하는 거예요. 앞에 붙이니까 같은 이름의 프로그램이 여러 개 있으면 우리가 지정한 폴더 걸 먼저 실행하게 되는 거죠.
source — 쉘 설정 파일은 원래 터미널 열 때만 읽거든요. source는 "지금 당장 다시 읽어"라고 강제하는 명령어예요. 이걸 안 하면 터미널을 껐다 켜야 적용돼요.
터미널 명령어 구조 (보너스)
터미널 명령어는 기본적으로 [누구에게] [무엇을] [어떻게] 구조예요.
[실행 파일] [하위 명령/동사] [옵션 및 인자]
- 누구에게: 명령을 내릴 프로그램 이름 (예:
claude,npm,git) - 무엇을: 구체적인 동작 (예:
config,install,commit) - 어떻게: 추가 정보나 세부 설정 (예:
--help,-v, 파일명)
이 구조만 알면 처음 보는 명령어도 대충 읽을 수 있어요.
마치며
앞으로 뭘 설치하든 command not found가 뜨면 이제 당황할 필요 없잖아요. "아, PATH 등록이구나" 하고 해결하면 됩니다.