클로드코드(Claude Code) 설치 오류와 해결법 정리

Claude Code 설치 중 만나는 오류를 OS별로 정리했습니다. 화면에 뜬 오류 문구로 케이스를 찾아 대응법을 따라 하면 됩니다. 아직 설치를 시작하지 않았다면 윈도우 설치 가이드 (윈도우에서 설치하는 순서 바로가기)나 맥 설치 가이드 (맥에서 설치하는 순서 바로가기)를 먼저 보시는 편이 빠릅니다. 대응법에 자주 등장하는 "네이티브 설치"는 아래 한 줄 명령을 말하며, Node.js와 Git이 없어도 됩니다.

macOS에서 클로드코드 설치 시 발생하는 오류와 해결법

"zsh: command not found: claude"

상황: 설치가 끝났다고 나왔는데 claude 입력 시 이 문구 발생
원인: 설치 실패가 아니라 PATH 문제. 프로그램은 ~/.local/bin에 설치됐지만, 셸이 프로그램을 찾아보는 폴더 주소록(PATH)에 이 위치가 미등록
대응법: 주소록에 설치 위치를 추가하고 설정을 다시 읽음

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

claude --version이 버전 번호를 출력하면 해결된 것입니다. VS Code 확장만 설치한 경우에는 터미널용 claude가 아예 없는 상태이므로, 네이티브 설치를 먼저 실행합니다.

"EACCES" 또는 "permission denied"

상황: npm install -g로 설치 중 권한 오류로 중단
원인: npm이 사용자 소유가 아닌 폴더에 쓰기 시도. sudo로 우회 시 소유권이 꼬여 다음 문제로 이어지기 쉬워 공식적으로 비권장
대응법: 네이티브 설치로 전환. 사용자 폴더에만 쓰기 때문에 권한 문제가 구조적으로 감소. 네이티브 설치에서도 권한 오류 발생 시 설치 폴더 소유자를 본인으로 되돌림: sudo chown -R $(whoami) ~/.local

"Cask 'claude-code' is unavailable: No Cask with this name exists"

상황: Homebrew로 brew install --cask claude-code 실행 시 설치 대상 없음으로 표시
원인: 로컬에 저장된 Homebrew 목록이 오래돼서 새 패키지를 인식하지 못하는 상태
대응법: 목록 갱신 후 재설치: brew update && brew install --cask claude-code

"dyld: cannot load" 또는 "Symbol not found"

상황: 설치나 실행 시 dyld로 시작하는 오류 또는 Abort trap: 6 발생
원인: macOS 버전이 낮아 실행 파일과 비호환. Claude Code는 macOS 13.0 이상 요구
대응법: 애플 메뉴의 "이 Mac에 관하여"에서 버전 확인 후 macOS 업데이트. Homebrew 등 다른 설치 방법도 같은 실행 파일을 받으므로 우회 불가

Windows에서 클로드코드 설치 시 발생하는 오류와 해결법

"'claude' is not recognized"

상황: 설치 후 claude 입력 시 CMD에서는 'claude' is not recognized as an internal or external command, PowerShell에서는 The term 'claude' is not recognized as the name of a cmdlet 발생
원인: macOS의 command not found와 동일한 PATH 문제. 설치 위치(%USERPROFILE%\.local\bin)가 PATH에 미등록
대응법: PowerShell에서 아래 두 줄 실행 후 터미널 재시작

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

"'irm' is not recognized"

상황: 설치 명령 붙여넣기 직후 명령 자체가 실행되지 않음
원인: PowerShell용 명령을 CMD 창에 붙여넣음
대응법: 시작 메뉴에서 "PowerShell" 검색해 열고 irm https://claude.ai/install.ps1 | iex 재실행

"The token '&&' is not valid"

상황: 설치 명령이 문법 오류로 실행되지 않음
원인: 반대로 CMD용 명령을 PowerShell에 붙여넣음
대응법: PowerShell용 명령(irm https://claude.ai/install.ps1 | iex)으로 교체 실행

"'bash' is not recognized" 또는 "A parameter cannot be found that matches parameter name 'fsSL'"

상황: 인터넷에서 복사한 설치 명령이 실행되지 않음
원인: macOS/리눅스용 curl ... | bash 명령을 Windows에서 실행. PowerShell의 curl은 다른 프로그램의 별칭이라 동일 옵션 미지원
대응법: Windows용 명령(irm https://claude.ai/install.ps1 | iex)으로 교체 실행

"Claude Code on Windows requires either Git for Windows (for bash) or PowerShell"

상황: 실행 시 Git 필요 오류로 보이는 메시지 발생
원인: Git for Windows는 필수 아님. Claude Code는 Git Bash 부재 시 PowerShell 대체 사용, 이 오류는 둘 다 미발견을 의미
대응법: 아래 셋 중 하나 진행
- PowerShell 기본 위치(C:\Windows\System32\WindowsPowerShell\v1.0\)를 PATH에 추가
- git-scm.com에서 Git for Windows 설치, 설치 중 "Add to PATH" 선택 후 터미널 재시작
- Git 기설치 시 settings.json에 CLAUDE_CODE_GIT_BASH_PATH로 bash.exe 경로 직접 지정

"Claude Code does not support 32-bit Windows"

상황: 64비트 PC인데도 32비트 미지원 오류 발생
원인: 시작 메뉴의 Windows PowerShell (x86) 항목으로 실행 시 32비트 프로세스로 구동되어 오류 발생
대응법: x86 미표기 Windows PowerShell을 열어 재실행. [Environment]::Is64BitOperatingSystem이 False로 나오는 진짜 32비트 Windows에서는 설치 불가

"The process cannot access the file ... being used by another process"

상황: PowerShell 설치 도중 파일 접근 오류로 실패
원인: 이전 설치 시도가 아직 실행 중이거나, 백신 프로그램이 다운로드 중인 파일을 검사하며 점유 중인 상태
대응법: 다른 PowerShell 창 모두 종료 및 백신 검사 완료 대기 후, 다운로드 폴더 삭제 및 재설치

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

WSL과 리눅스에서 클로드코드 설치 시 발생하는 오류와 해결법

"bash: claude: command not found"

상황: 설치 후 claude 미실행
원인: macOS 케이스와 동일한 PATH 문제
대응법: ~/.bashrc에 PATH 한 줄 추가

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

WSL에서 "exec: node: not found"

상황: npm 방식으로 설치 후 claude 실행 시 node 미발견 오류
원인: WSL이 리눅스용 Node 대신 Windows에 설치된 Node를 참조 중인 상태. which node 결과가 /mnt/c/로 시작하면 이 경우
대응법: 리눅스 쪽에 Node 설치(배포판 패키지 매니저 또는 nvm). 설치 중 플랫폼 불일치 오류 시 npm config set os linux 선행 실행 후 재설치

WSL에서 "cannot execute binary file: Exec format error"

상황: 설치는 완료됐으나 실행 시 실행 파일 형식 오류 발생
원인: WSL1의 알려진 호환성 문제
대응법: PowerShell에서 WSL2로 전환: wsl --set-version <배포판이름> 2

"Killed" 또는 "exit code 137"

상황: 저사양 서버(VPS)에서 설치 도중 Killed 한 줄과 함께 중단
원인: 메모리 부족으로 리눅스가 설치 프로세스 강제 종료. 설치에는 약 512MB의 여유 메모리 필요
대응법: 스왑 공간 생성으로 메모리 보충 후 재설치

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

"Error loading shared library libstdc++.so.6"

상황: 설치 후 실행 시 공유 라이브러리 미발견 오류
원인: 시스템에 맞지 않는 실행 파일 변형이 설치됐거나, Alpine 같은 musl 계열 배포판에 필요한 패키지 부재
대응법: ldd --version으로 시스템 종류 확인. Alpine이면 apk add libgcc libstdc++ ripgrep으로 패키지 설치, 일반(glibc) 시스템에서 이 오류 발생 시 삭제 후 재설치

모든 OS에서 공통으로 발생하는 오류와 해결법

"npm: command not found" 또는 Node 버전 요구 오류

상황: npm 방식(npm install -g @anthropic-ai/claude-code)으로 설치 시도 중 npm 부재 또는 Node 버전 미달 오류
원인: npm 설치 방식은 Node.js 18 이상 요구. 커뮤니티에서는 실제로 20 이상 필요했다는 사례들 존재
대응법: 네이티브 설치로 전환 시 Node.js 없이 설치 가능. npm 방식 유지 필요 시 nodejs.org의 LTS 버전 또는 nvm으로 Node 20 이상 설치 후 재실행

"syntax error near unexpected token '<'"

상황: 한 줄 설치 명령 실행 시 이 문구 또는 curl: (22) ... error: 403 발생
원인: 설치 스크립트 대신 HTML 페이지나 오류 응답 수신. 네트워크 문제, 지역 라우팅, 일시적 장애가 원인일 수 있음
대응법: 몇 분 후 재시도, 또는 대안 설치(macOS는 brew install --cask claude-code, Windows는 winget install Anthropic.ClaudeCode) 사용. 지원 국가가 아니라는 안내 표시 시 해당 지역 설치 불가

"unable to get local issuer certificate" 등 인증서 오류

상황: 회사 컴퓨터에서 설치 시 TLS, SSL, 인증서 관련 오류 발생
원인: 회사망의 보안 장비(프록시)가 통신에 개입 중인 상태
대응법: IT 담당자에게 회사 인증서(CA) 파일 요청 후 설치 명령에 지정, 필요 시 HTTPS_PROXY 환경변수에 프록시 주소 설정. 환경마다 상이하므로 IT 담당자와 함께 확인이 가장 빠름

"OAuth error: Invalid code"

상황: 설치는 완료됐으나 로그인 단계에서 코드 무효 오류 발생
원인: 로그인 코드 만료 또는 복사 중 잘림. 원격(SSH) 환경에서는 브라우저가 다른 컴퓨터에서 열리는 것이 원인일 수 있음
대응법: Enter로 재시도 후 브라우저가 열리면 빠르게 완료. 브라우저 미실행 시 c를 눌러 URL 복사 후 직접 접속. 원격 환경이라면 터미널의 URL을 내 컴퓨터 브라우저에서 열고, 표시된 코드를 터미널에 붙여넣기

여기에 없는 오류를 만났을 때의 대응법

claude doctor 실행: 설치가 절반이라도 된 상태라면 자동 진단 보고서 생성
중복 설치 확인: npm 설치와 네이티브 설치가 함께 있으면 버전 충돌 가능. which -a claude로 확인 후 npm 쪽 제거(npm uninstall -g @anthropic-ai/claude-code)
오류 문구 그대로 검색: 공식 GitHub 이슈에서 동일 문구로 검색 시 알려진 문제인지 확인 가능
데스크톱 앱 우회: 터미널 설치가 계속 막히면 그래픽 화면으로 쓰는 Claude Code 데스크톱 앱(macOS, Windows)이 대안