Claude Code를 설치한 후 터미널에서 claude 명령어를 입력했을 때 command not found 에러가 발생하는 경우를 위한 가이드입니다. 이 에러는 설치 과정의 오류라기보다, 시스템이 실행 파일을 찾을 수 있도록 경로(PATH)를 등록하지 않아 발생하는 환경 설정 문제입니다.
해결 방법 요약
본인의 쉘(Shell) 환경에 맞는 명령어를 터미널에 입력하세요. 공식 문서에서 권장하는 ~/.local/bin 디렉토리를 환경 변수에 등록하는 과정입니다.
1. Zsh 환경 (macOS 기본 및 최신 리눅스)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
2. Bash 환경 (일반적인 리눅스 기본)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
설정 후 claude 명령어를 입력하여 정상적으로 작동하는지 확인해 보세요.
1. 운영체제별 설계 철학의 차이
Windows 환경은 설치 프로그램이 시스템의 환경 변수를 자동으로 제어하는 경우가 많아 사용자가 경로를 직접 관리할 일이 드뭅니다. 반면, Mac과 Linux 등 Unix 계열 시스템은 사용자가 환경 설정을 명시적으로 제어하는 방식을 지향합니다.
이는 시스템 전체의 설정이 사용자 개별 설정을 오염시키지 않도록 분리하고, 보안과 효율성을 높이기 위한 설계입니다. Windows를 쓰다가 Mac이나 리눅스로 넘어온 분들이 가장 처음 겪는 낯선 경험이기도 합니다.
2. 쉘(Shell)이란 무엇인가요?
터미널을 사용하다 보면 '쉘'이라는 단어를 자주 접하게 됩니다. 쉘은 쉽게 말해 사용자와 운영체제 사이의 다리 역할을 하는 명령어 해석기입니다.
- 역할: 사용자가 터미널에
claude같은 텍스트 명령을 입력하면, 쉘이 이를 읽어 들여 운영체제가 이해할 수 있는 신호로 변환하고 실행을 요청합니다. - 환경 제공: 우리가 명령어를 입력하는 검은 화면(터미널) 자체가 아니라, 그 안에서 명령을 처리하고 결과를 보여주는 '소프트웨어 환경'이 바로 쉘입니다.
- 종류: 대표적으로 Zsh와 Bash가 있습니다. 쉘마다 설정을 저장하는 파일이 다르기 때문에 본인이 어떤 쉘을 쓰고 있는지 아는 것이 중요합니다.
3. 발생 원인 진단: 환경 변수(PATH)의 역할
터미널에서 특정 명령어를 입력하면, 쉘은 해당 이름의 실행 파일을 찾기 위해 미리 지정된 디렉토리 목록을 탐색합니다. 이 디렉토리 목록을 **환경 변수(PATH)**라고 합니다.
- 경로 인식 문제: Claude Code의 네이티브 설치 스크립트는 실행 파일을
~/.local/bin디렉토리에 생성하거나 링크합니다. 하지만 대다수의 시스템에서 이 경로는 기본 탐색 리스트(PATH)에 포함되어 있지 않습니다. - 설정 파일의 독립성: Unix 계열 시스템은 각 사용자마다 고유한 설정 파일(Dotfiles)을 가집니다. 설치 스크립트가 이 파일을 수정하려고 시도하지만, 환경에 따라 누락되거나 현재 열려 있는 터미널 세션에 즉시 반영되지 않을 수 있습니다.
4. 내 쉘에 맞는 설정 파일 찾기 및 선택
사용 중인 쉘에 따라 읽어 들이는 설정 파일이 다릅니다. 터미널에서 echo $SHELL 명령을 입력하면 어떤 쉘을 쓰고 있는지 확인할 수 있습니다.
- Zsh (최신 macOS 기본): 주로
~/.zshrc파일을 사용합니다. - Bash (리눅스 및 구형 macOS 표준): 보통
~/.bashrc를 사용하지만, 운영체제 설정이나 로그인 방식에 따라~/.bash_profile또는~/.profile파일을 읽기도 합니다.
팁: 만약 해당 파일들이 없다면? 처음 시스템을 설정했을 때는 이 파일들이 존재하지 않을 수 있습니다. 상단 요약에서 사용한
>>명령어는 파일이 없을 경우 자동으로 새 파일을 생성하여 내용을 저장하니 안심하고 진행하셔도 됩니다.
5. 해결 명령어의 상세 분석
우리가 입력한 명령어들이 실제로 어떤 동작을 하는지 정확히 알면 나중에 다른 문제가 생겨도 대처할 수 있습니다.
1. echo와 >> (내용 기록)
echo는 글자를 출력하고, >>는 그 내용을 파일 끝에 덧붙이라는 뜻입니다. 즉, "설정 파일 맨 아래에 경로 지정 코드를 한 줄 추가해라"라는 명령입니다.
2. export PATH="..." (경로 우선순위)
기존의 경로 리스트($PATH) 앞에 새로운 경로($HOME/.local/bin)를 추가합니다. 새 경로를 맨 앞에 배치함으로써 동일한 이름의 프로그램이 여러 개 있을 때 우리가 지정한 폴더의 파일을 가장 먼저 실행하게 만듭니다.
3. source (즉시 반영)
쉘 설정 파일은 원래 터미널이 켜질 때 읽어옵니다. source 명령어는 이미 켜져 있는 터미널에게 "지금 당장 이 파일을 다시 읽어서 적용해라"라고 강제로 업데이트를 시키는 것입니다.
6. 터미널 명령어 구조 익히기
터미널 명령어는 기본적으로 **[누구에게] [무엇을] [어떻게]**라는 구조를 가집니다.
[실행 파일] [하위 명령/동사] [옵션 및 인자]
- 누구에게 (실행 파일): 명령을 내릴 프로그램의 이름입니다. (예:
claude,npm,git) - 무엇을 (하위 명령): 그 프로그램이 해야 할 구체적인 동작입니다. (예:
config,install,commit) - 어떻게 (옵션/인자): 동작에 필요한 추가 정보나 세부 설정입니다. (예:
--help,-v, 파일명)
마치며
앞으로 어떤 도구를 설치하더라도 command not found 메시지를 보게 된다면, 이제는 당황하지 말고 "아, 경로 등록이 필요하구나!"라고 생각하며 자신 있게 해결해 보세요.