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

Claude Code 설치 중 만나는 오류를 OS별로 정리했습니다. 화면에 뜬 오류 문구로 케이스를 찾아 대응법을 따라 하면 됩니다. 아직 설치를 시작하지 않았다면 윈도우 설치 가이드 (윈도우에서 설치하는 순서 바로가기)나 맥 설치 가이드 (맥에서 설치하는 순서 바로가기)를 먼저 보시는 편이 빠릅니다. 대응법의 ‘네이티브 설치’는 운영체제에 맞는 실행 파일을 직접 받는 방식입니다. Node.js를 미리 설치할 필요는 없습니다. Windows의 Git for Windows는 권장 도구이며, 없으면 PowerShell을 사용하는 방식도 지원합니다. 아래 안내는 2026년 10월 4일 공식 문서 기준입니다.

먼저 오류가 난 단계를 찾습니다

아래 항목 전체를 순서대로 실행하는 글이 아닙니다. 자신의 환경과 오류에 해당하는 부분 하나만 확인합니다. 변경 전에 실행한 명령과 오류의 마지막 몇 줄을 기록합니다. 로그인 코드, API 키와 비밀번호는 기록이나 질문에 넣지 않습니다.

1. 설치 명령이 실패했다면 문법, 네트워크, 권한 오류를 확인합니다.
2. 설치는 끝났는데 실행되지 않으면 새 터미널에서 claude --version을 확인합니다. 명령을 못 찾는지, 실행 파일이 다른 오류를 내는지 구분합니다.
3. 버전은 나오지만 로그인되지 않으면 설치를 반복하지 말고 계정과 인증 오류를 확인합니다.

claude doctor는 설치 및 설정 상태를 읽는 진단 명령입니다. claude 자체를 찾지 못하면 이 명령도 실행되지 않으므로 파일과 PATH를 먼저 확인해야 합니다. 셸은 입력한 명령을 실행하는 프로그램이고, PATH는 셸이 실행 파일을 찾는 폴더 목록입니다.

네이티브 설치를 선택한 경우의 명령은 다음과 같습니다. 이미 설치가 정상 작동하면 다시 실행하지 않습니다.

맥, 리눅스, WSL의 터미널:

Windows PowerShell:

두 명령 중 자신의 환경에 맞는 하나만 사용합니다. 인터넷에서 스크립트를 받아 실행하므로 공식 주소와 셸을 먼저 확인합니다.

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

"zsh: command not found: claude"

새 터미널에서도 같은 오류가 나는지 확인합니다. 네이티브 설치를 했다면 다음 두 명령으로 파일의 존재와 직접 실행 결과를 확인합니다.

첫 명령에서 파일이 없다고 나오면 설치가 끝났는지 확인합니다. VS Code 확장만 설치했다면 터미널용 명령이 PATH에 등록되지 않습니다. 확장 안의 채팅을 쓰는 것과 독립 터미널 설치는 다릅니다. Homebrew 등 다른 방식은 다른 설치 경로를 사용합니다.

전체 경로로는 버전이 나오고 claude --version만 실패한다면 다음 명령으로 PATH에 설치 폴더가 있는지 확인합니다.

폴더 경로가 출력되면 이미 등록된 것입니다. 아무 출력이 없고 맥 기본 셸인 zsh를 사용한다면 아래 두 줄을 한 번 실행합니다.

>>는 기존 파일 뒤에 내용을 추가합니다. 같은 줄을 반복해서 넣지 않습니다. 다른 셸에서는 설정 파일이 달라지므로 공식 PATH 안내를 따릅니다. 수정 뒤 새 터미널에서 claude --version이 정상 출력되는지 확인합니다.

아래 그림은 실행 파일이 있고 PATH만 빠진 경우의 설명입니다. 모든 command not found 오류가 이 경우에 해당하지는 않습니다.

"EACCES" 또는 "permission denied"

• 상황: npm install -g로 설치 중 권한 오류로 중단
• 원인: npm이 사용자 소유가 아닌 폴더에 쓰기 시도. sudo로 우회 시 소유권이 꼬여 다음 문제로 이어지기 쉬워 공식적으로 비권장
• 대응법: 오류에 나온 경로가 무엇인지 먼저 확인합니다. npm 전역 설치가 필요하지 않다면 네이티브 방식이 대안입니다. 네이티브 설치에서도 막히면 해당 폴더의 소유자와 쓰기 권한을 확인합니다. ~/.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

macOS가 앱 실행을 차단하는 경고

앱을 더블클릭할 때 나오는 경고와 터미널에서 claude를 실행할 때 나오는 오류를 구분합니다. 어느 앱 파일에서 나온 경고인지, 공식 다운로드 파일인지 먼저 확인합니다. 데스크톱 앱은 공식 설치 안내에 따라 응용 프로그램 폴더에 배치하고 실행합니다.

경고 문장만으로 앱 이동 보호가 유일한 원인이라고 단정하지 않습니다. 격리 속성을 일괄 삭제하는 xattr 명령을 해결책처럼 먼저 실행하지 말고, 경고 전문과 macOS 버전으로 공식 지원 안내를 확인합니다. 터미널 명령을 원하는 경우에는 앱 삭제보다 독립 CLI 설치 여부를 먼저 확인합니다.

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

• 상황: 설치나 실행 시 dyld로 시작하는 오류 또는 Abort trap: 6 발생
• 가능한 원인: macOS 버전이나 하드웨어와 실행 파일의 비호환입니다. 특히 libicucore의 특정 심벌을 찾지 못하는 오류는 지원 사양보다 오래된 macOS에서 발생할 수 있습니다
• 대응법: 애플 메뉴의 ‘이 Mac에 관하여’에서 macOS 버전과 칩을 확인합니다. CLI는 macOS 13.0 이상을 요구합니다. 그보다 낮다면 운영체제 지원 조건을 먼저 해결해야 하며, 같은 실행 파일을 받는 다른 설치 방법으로는 비호환 문제가 없어지지 않습니다. 사양이 맞아도 오류가 나면 문구 전체를 기준으로 확인합니다

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

"'claude' is not recognized"

새 PowerShell에서도 명령을 찾지 못하면 먼저 파일을 확인합니다.

False라면 이 경로에 실행 파일이 없습니다. 설치가 완료됐는지, WinGet 등 다른 설치 방식을 사용했는지부터 확인합니다. True이고 전체 경로로는 버전이 나오면 사용자 PATH에서 해당 폴더를 찾습니다.

등록되어 있지 않을 때만 다음 두 줄을 한 번 실행합니다. 기존 PATH를 유지한 채 새 경로를 추가하는 명령입니다.

터미널을 새로 열어 claude --version을 확인합니다. VS Code 안의 터미널에서만 안 되면 VS Code도 완전히 종료하고 다시 엽니다. 전체 경로로 실행해도 오류가 나면 PATH 외의 원인을 확인합니다.

"'irm' is not recognized"

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

"The token '&&' is not valid"

• 상황: 설치 명령이 문법 오류로 실행되지 않음
• 원인: Windows PowerShell 5.1처럼 &&를 지원하지 않는 셸에 CMD용 명령을 넣었을 수 있습니다. PowerShell 7은 &&를 지원하므로 모든 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에서 실행. Windows PowerShell 5.1의 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의 env 항목 안에 CLAUDE_CODE_GIT_BASH_PATH를 넣습니다. 실제 bash.exe 경로를 확인하고 공식 Windows 설정 예시에 따라 기존 설정을 유지하며 추가합니다

"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 설치 도중 파일 접근 오류로 실패
• 원인: 이전 설치 시도가 아직 실행 중이거나, 백신 프로그램이 다운로드 중인 파일을 검사하며 점유 중인 상태
• 대응법: 본인이 진행 중인 설치나 업데이트가 끝났는지 확인하고 파일 검사가 끝날 때까지 기다립니다. 관련 없는 모든 터미널이나 작업을 종료하지 않습니다. 계속 같은 오류가 나면 공식 잠금 오류 안내를 따릅니다.

공식 안내에서 정리하는 대상은 설치의 임시 다운로드 폴더입니다. 경로를 확인하지 않고 .claude 전체나 개인 다운로드 폴더를 삭제하면 안 됩니다. 먼저 다음 명령으로 대상이 어떤 파일인지 확인합니다.

폴더가 없으면 삭제할 것도 없습니다. 진행 중인 설치가 없고 공식 오류 조건과 일치할 때만 안내된 임시 파일 정리를 진행하고, 이후 설치를 한 번 다시 시도합니다. 해결 여부는 새 터미널의 claude --version으로 확인합니다.

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

WSL은 윈도우에서 리눅스 환경을 사용하는 기능입니다. 리눅스 명령은 WSL 터미널에, wsl 관리 명령은 Windows PowerShell에 입력합니다. Windows에 설치한 프로그램과 WSL 안의 프로그램은 같은 설치로 취급하지 않습니다.

"bash: claude: command not found"

• 상황: 설치 후 claude 미실행
• 가능한 원인: 실행 파일 부재 또는 PATH 누락입니다. macOS 항목처럼 파일 존재와 전체 경로 실행 결과부터 확인합니다
• 대응법: bash를 쓰며 설치 경로가 PATH에 빠진 경우에만 ~/.bashrc에 다음 줄을 한 번 추가합니다

WSL에서 "exec: node: not found"

• 상황: npm 방식으로 설치 후 claude 실행 시 node 미발견 오류
• 원인: WSL이 리눅스용 Node 대신 Windows에 설치된 Node를 참조 중인 상태. which node 결과가 /mnt/c/로 시작하면 이 경우
• 대응법: which node와 which npm으로 실제 경로를 확인합니다. npm 방식을 유지한다면 WSL 안에서 Linux용 Node.js 22 이상을 사용합니다. 네이티브 설치를 쓰면 Node.js가 필수가 아닙니다. 다른 npm 패키지에도 영향을 줄 수 있는 플랫폼 강제 설정은 원인을 확인하기 전에 넣지 않습니다

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

• 상황: 설치는 완료됐으나 실행 시 실행 파일 형식 오류 발생
• 가능한 원인: 공식 문서에는 WSL1의 실행 파일 호환성 문제가 보고되어 있습니다. 다른 환경에서도 같은 문구가 나올 수 있어 버전부터 확인합니다
• 대응법: PowerShell에서 wsl -l -v로 배포판 이름과 VERSION을 확인합니다. WSL1의 해당 문제라면 배포판 자료를 백업하고 WSL2 요구 조건을 확인한 뒤 wsl --set-version <배포판이름> 2에서 이름을 실제 값으로 바꿔 전환합니다. WSL2에서 같은 오류가 나면 이 변환 명령을 반복하지 않습니다

"Killed" 또는 "exit code 137"

• 상황: 저사양 서버(VPS)에서 설치 도중 Killed 한 줄과 함께 중단
• 가능한 원인: 메모리 부족으로 프로세스가 강제 종료됐을 수 있습니다. 종료 코드 137만으로 메모리 부족을 확정할 수는 없습니다.
• 대응법: free -h로 메모리 상태를 확인하고 서버 로그의 메모리 부족 기록을 확인합니다. 공식 문서의 약 512MB는 설치할 때 필요한 여유 메모리 안내이며, 실행 사양인 RAM 4GB 이상과 다른 수치입니다.

스왑은 디스크 일부를 보조 메모리로 쓰는 기능입니다. 이미 있는 /swapfile을 덮어쓰거나 운영 중인 서버에 바로 추가하지 않습니다. 우선 사용하지 않는 본인 작업을 종료하고, 관리자와 기존 스왑 및 디스크 여유를 확인한 뒤 공식 메모리 오류 안내를 적용합니다. 메모리가 확보되면 설치를 다시 시도하고 버전 출력을 확인합니다.

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

• 상황: 설치 후 실행 시 공유 라이브러리 미발견 오류
• 원인: 시스템에 맞지 않는 실행 파일 변형이 설치됐거나, Alpine 같은 musl 계열 배포판에 필요한 패키지 부재
• 대응법: 공유 라이브러리는 프로그램 실행에 필요한 공통 기능 파일입니다. cat /etc/os-release와 ldd --version으로 리눅스 배포판과 라이브러리 종류를 확인합니다. Alpine 환경에서 필요한 패키지가 없을 때는 관리 권한으로 apk add libgcc libstdc++ ripgrep을 적용합니다. 다른 배포판에 같은 명령을 실행하지 않으며, 실제 시스템과 내려받은 실행 파일의 종류가 맞는지 확인합니다

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

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

• 상황: npm 방식(npm install -g @anthropic-ai/claude-code)으로 설치 시도 중 npm 부재 또는 Node 버전 미달 오류
• 원인: 현재 공식 npm 설치 요구 조건은 Node.js 22 이상입니다. npm 자체가 없다면 Node.js와 npm 설치 상태부터 확인합니다
• 대응법: npm 방식이 필요하지 않으면 네이티브 설치가 대안입니다. npm 방식을 유지한다면 Node.js 22 이상을 준비하고 node --version과 npm --version으로 확인합니다. EBADENGINE 경고만으로 설치 전체가 실패했다고 판단하지 말고 최종 오류와 claude --version을 함께 확인합니다

"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는 통신 상대를 확인할 때 신뢰하는 인증서 기관을 뜻합니다. 인증서 검증을 끄는 옵션으로 오류만 숨기지는 않습니다

"OAuth error: Invalid code"

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

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

• claude doctor 실행: 실행 파일이 정상 동작할 때 설치와 설정 진단을 확인합니다. 명령을 못 찾으면 파일과 PATH부터 확인합니다
• 중복 설치 확인: macOS/Linux는 which -a claude, Windows는 where.exe claude로 실제 실행 경로를 봅니다. 사용할 설치가 정상 작동하는지 확인한 뒤 불필요한 설치만 해당 설치 방식의 제거 명령으로 정리합니다
• 오류 문구 그대로 검색: 공식 GitHub 이슈에서 동일 문구로 검색 시 알려진 문제인지 확인 가능
• 데스크톱 앱 우회: 터미널 설치가 계속 막히면 그래픽 화면으로 쓰는 Claude Code 데스크톱 앱(macOS, Windows)이 대안

자주 묻는 질문

설치가 끝났는데 claude 명령을 찾지 못하는 이유가 뭔가요?

파일이 없거나 PATH가 빠졌거나 다른 실행 파일이 먼저 잡혔을 수 있습니다. 터미널을 새로 열고, 파일 존재와 전체 경로 실행 결과를 확인한 뒤 해당 원인에 맞게 수정합니다. VS Code에서 안 되는 경우는 따로인데, VS Code가 시작할 때 PATH를 읽기 때문에 설정을 고친 뒤 에디터를 완전히 껐다 켜야 반영됩니다.

오류 문구가 한국어로 나오는데 같은 오류인가요?

같은 오류를 운영체제가 번역해 보여 주는 것입니다. 예를 들어 "이 파일을 다른 응용 프로그램에서 사용 중입니다"는 영문 "The process cannot access the file"과 같은 상황이고 대응도 같습니다. 검색할 때는 한국어 문구와 영어 문구를 모두 넣어 보면 찾을 확률이 올라갑니다.

npm으로 설치한 것과 네이티브 설치가 같이 있으면 문제가 되나요?

서로 다른 버전이 실행되거나 업데이트 경로가 달라질 수 있습니다. 경로가 여러 개라는 사실만으로 손상됐다고 판단하지는 않습니다. 남길 설치의 전체 경로로 --version을 확인한 뒤 사용하지 않는 설치만 정리합니다. npm 설치를 제거하기로 했다면 npm uninstall -g @anthropic-ai/claude-code를 사용합니다.

여기에 없는 오류를 만나면 어떻게 하나요?

claude가 실행될 때는 claude doctor로 진단합니다. 실행 자체가 안 되면 파일과 PATH 확인부터 진행합니다. 그다음 오류 문구를 그대로 공식 저장소 이슈에서 검색해 알려진 문제인지 확인합니다. 터미널 설치가 계속 막히면 그래픽 화면으로 쓰는 데스크톱 앱이 우회 경로입니다.

해결했는지 마지막으로 확인합니다

한 가지 원인을 수정한 뒤 새 터미널에서 claude --version을 실행합니다. 버전이 나오면 실행 확인은 통과입니다. 로그인 오류였다면 로그인 단계까지 다시 확인해야 하며, 버전 출력만으로 인증 성공을 판단하지 않습니다.

오류가 그대로라면 같은 명령을 반복하지 말고 이전 오류와 새 오류를 비교합니다. 질문할 때는 ‘Windows PowerShell에서 네이티브 설치 후 버전 확인 시 command not found’처럼 환경, 설치 방식, 실패 단계와 문구를 함께 적습니다. 이 정보가 있어야 다음 확인 대상을 좁힐 수 있습니다.

Sources

• Claude Code 공식 문서: 설치 및 로그인 문제 해결
• Claude Code 공식 문서: 설치 가이드
• Claude 고객센터: 설치와 인증 문제 해결

3줄 요약

1. 설치 오류는 문구와 발생 단계에 따라 원인이 다르므로 실행한 명령과 마지막 오류부터 확인합니다.

2. 명령을 찾지 못할 때는 설치 파일과 직접 실행 결과를 확인하고 필요한 경우에만 PATH를 수정합니다.

3. 한 가지 원인을 수정한 뒤 새 터미널의 버전 출력과 원래 막혔던 단계를 다시 확인합니다.