Claude Code 설치 방법: macOS·Windows와 command not found 해결

Claude Code는 터미널에서 프로젝트를 읽고 코딩 작업을 돕는 도구다. macOS는 공식 설치 스크립트 또는 Homebrew cask, Windows는 PowerShell 설치 스크립트 또는 WinGet을 쓰는 것이 현재 공식 권장 경로다. 설치 후 새 터미널에서 claude를 실행하면 된다. claude: command not found는 대부분 설치 실패가 아니라 새 실행 파일 경로가 현재 셸의 PATH에 반영되지 않은 문제다.

설치 전에 확인할 것

Claude Code 공식 Setup 문서의 현재 지원 운영체제와 요구 사항을 먼저 확인한다. Windows에서는 네이티브 설치와 WSL 사용 여부에 따라 설치 위치와 셸이 달라진다. 중요한 원칙은 ‘설치한 환경과 실행하는 환경을 같게’ 하는 것이다. PowerShell에 설치하고 WSL의 bash에서 바로 claude를 찾거나, WSL에 설치하고 Windows 명령 프롬프트에서 찾으면 경로가 다를 수 있다.

예전 글에서 자주 보이는 npm install -g @anthropic-ai/claude-code는 공식 저장소에서 deprecated로 표시되어 있다. 기존 npm 설치가 동작할 수는 있지만 새 설치 안내라면 네이티브 설치 방법을 우선해야 한다.

macOS에 Claude Code 설치하기

공식 저장소의 권장 명령은 다음과 같다.

curl -fsSL https://claude.ai/install.sh | bash

원격 스크립트 실행 대신 Homebrew를 관리 도구로 쓰고 싶다면 공식 대안은 다음과 같다.

brew install --cask claude-code

설치가 끝나면 터미널 창을 닫고 새로 연 뒤 확인한다.

claude --version
cd /path/to/your-project
claude

Apple Silicon과 Intel Mac에서 Homebrew 경로가 다를 수 있으므로, brew 자체가 안 잡힌다면 Claude Code보다 Homebrew PATH를 먼저 고쳐야 한다. 설치 명령의 성공 메시지만 보지 말고 claude --version까지 실행해야 설치가 끝난 것이다.

Windows에 Claude Code 설치하기

PowerShell을 열고 공식 권장 설치 명령을 실행한다.

irm https://claude.ai/install.ps1 | iex

WinGet으로 패키지를 관리하고 싶다면 공식 저장소에 다음 대안이 안내되어 있다.

winget install Anthropic.ClaudeCode

설치 후 기존 PowerShell을 닫고 새 창을 연다.

claude --version
cd C:\path\to\your-project
claude

회사 보안 정책이 원격 스크립트 실행을 막는다면 실행 정책을 무작정 낮추지 말고 WinGet 또는 조직이 허용한 배포 방법을 사용한다. Git이 추가 의존성으로 필요한 구성도 있으므로 공식 Setup 문서의 Windows 항목과 claude doctor 결과를 확인한다.

WSL을 사용한다면 WSL 터미널 안에서 macOS/Linux용 설치 경로를 따르고, 실행도 같은 WSL 셸에서 한다. Windows PowerShell용 설치와 WSL용 설치를 섞으면 PATH 문제를 만들기 쉽다.

첫 실행과 로그인

프로젝트 디렉터리에서 claude를 실행한다. 첫 실행에서는 안내에 따라 인증한다. 인증 방식은 개인 Claude 계정, 조직 설정, API 제공자 구성에 따라 다를 수 있으므로 화면에 표시되는 현재 옵션과 공식 Authentication 문서를 따른다.

처음부터 중요한 저장소에서 시작하기보다 작은 테스트 폴더를 만드는 편이 좋다.

mkdir claude-code-test
cd claude-code-test
printf '# Test project
' > README.md
claude

Windows PowerShell에서는 mkdir claude-code-test 후 Set-Location claude-code-test처럼 해당 셸 문법을 사용한다. Claude Code가 파일 변경이나 명령 실행을 제안하면 내용을 읽고 승인한다. 설치 확인 단계에서 관리자 권한으로 상시 실행할 이유는 없다.

claude: command not found 해결 순서

1. 터미널을 완전히 다시 연다

설치 프로그램이 PATH를 바꿔도 이미 열린 셸은 이전 환경 변수를 유지한다. 모든 터미널 창과 IDE 내장 터미널을 닫고 새 창에서 다시 실행한다.

claude --version

Windows도 새 PowerShell을 열어 claude --version을 확인한다.

2. 실행 파일을 셸이 찾는지 확인한다

macOS/Linux/WSL:

command -v claude
which claude

Windows PowerShell:

Get-Command claude -ErrorAction SilentlyContinue
where.exe claude

아무 결과가 없으면 현재 PATH에서 실행 파일을 못 찾는 상태다. 공식 설치 명령을 다시 무한 반복하기 전에 설치 로그와 공식 Setup 문서의 설치 위치·PATH 진단 항목을 확인한다.

3. 설치한 셸과 실행 셸을 맞춘다

• macOS에서 zsh에 설치했는데 IDE가 다른 로그인 셸을 쓰는지 확인한다.
• Windows용으로 설치했다면 PowerShell에서 먼저 검증한다.
• WSL에 설치했다면 Ubuntu 등 해당 WSL 배포판 안에서 실행한다.
• 과거 npm 전역 설치와 네이티브 설치가 섞였다면 어느 claude가 먼저 잡히는지 which 또는 Get-Command로 확인한다.

4. 진단 명령을 실행한다

명령 자체가 실행되기 시작했다면 공식 문서가 안내하는 상태 점검을 쓴다.

claude doctor

이 단계는 PATH가 해결된 뒤의 진단이다. command not found 상태에서는 doctor도 실행되지 않으므로 순서를 거꾸로 하지 않는다.

5. 권한 오류와 PATH 오류를 구분한다

permission denied는 파일을 찾았지만 실행 권한이 없는 경우이고, command not found는 셸이 파일을 못 찾는 경우다. 전자는 설치 파일 권한이나 보안 정책을 보고, 후자는 설치 위치와 PATH를 본다. 오류 문구가 다른데 같은 해결책을 반복하면 시간이 오래 걸린다.

설치가 끝났다고 판단하는 기준

claude --version이 새 터미널에서 동작하고, 프로젝트 폴더에서 claude를 실행해 인증 화면 또는 대화 화면까지 들어가며, claude doctor가 현재 설치 상태를 읽을 수 있으면 기본 설치는 완료다.

오래된 npm 설치 글을 따라가기 전에 공식 문서를 다시 확인하자. Claude Code는 설치 방식이 바뀐 제품이므로, 현재 공식 저장소가 권장하는 네이티브 설치 명령을 기준으로 삼는 것이 command not found와 중복 설치를 줄이는 가장 짧은 방법이다.

출처: Claude Code Setup, Claude Code 공식 저장소, Claude Code Authentication, Claude Code Troubleshooting