Claude Code를 설치했는데 아무것도 되지 않는다면 — command not found 메시지, 로그인 화면의 403 오류, 또는 터미널이 설치 명령을 아예 알아듣지 못하는 상황 — 이 글이 그 문제를 순서대로 짚어 드립니다. 공식 문서(code.claude.com)에 기재된 진단 흐름을 바탕으로, 사전 지식 없이도 따라 할 수 있도록 정리했습니다. 예상 소요 시간은 문제 유형에 따라 5~15분입니다.
시작 전 준비물 확인
- 계정: Claude.ai 계정 또는 Anthropic API 키 (어느 쪽이든 로그인에 사용)
- 운영체제: macOS, Linux, 또는 Windows(Git for Windows bash 또는 PowerShell 필요). 32비트 Windows는 지원하지 않습니다.
- 터미널: macOS·Linux는 기본 터미널, Windows는 PowerShell 또는 Git Bash
- 인터넷:
downloads.claude.ai에 접근 가능해야 합니다
용어 빠른 풀이
- PATH — 경로 환경 변수: 터미널이 명령어 파일을 찾아보는 폴더 목록입니다. 여기 등록되지 않은 폴더의 명령어는
command not found로 나타납니다. - OAuth — 공개 인증 프로토콜: 비밀번호를 직접 전달하지 않고 '허가 토큰'으로 로그인하는 방식입니다.
- curl — 커맨드라인 다운로드 도구: 터미널에서 웹 주소로 파일을 내려받거나 서버 응답을 확인하는 명령어입니다.
- TLS/SSL — 전송 암호화: 인터넷 구간에서 데이터를 암호화하는 기술입니다. 회사 네트워크에서 자체 인증서를 쓰는 경우 오류가 날 수 있습니다.
1단계: 네트워크 연결 확인
Claude Code 설치 파일은 downloads.claude.ai에서 내려받습니다. 먼저 이 서버에 실제로 도달할 수 있는지 확인하세요.
macOS · Linux 터미널에서:
curl -sI https://downloads.claude.ai/claude-code-releases/latestWindows PowerShell에서: curl이 다른 명령으로 연결되어 있으므로 반드시 아래처럼 입력합니다.
curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest이렇게 보이면 성공: 첫 줄에 HTTP/2 200이 표시됩니다.
오류가 나온다면: Could not resolve host 또는 연결 시간 초과는 네트워크(방화벽, 프록시, VPN)가 해당 주소를 차단하고 있다는 뜻입니다. 회사·학교 네트워크라면 IT 담당자에게 downloads.claude.ai 허용을 요청하세요.
2단계: 설치 스크립트가 HTML을 반환할 때
설치 명령을 실행했을 때 터미널에 syntax error near unexpected token '<' 같은 메시지가 뜬다면, 설치 스크립트 대신 HTML 페이지(오류 페이지)가 내려받아진 것입니다. 공식 문서에 따르면 이는 지역 제한으로 서버 접근이 차단되었을 때 발생합니다. Claude Code는 일부 국가에서 이용이 제한될 수 있으므로, 지원 국가 목록을 공식 페이지에서 확인하세요.
3단계: command not found: claude — PATH 문제 해결
설치는 완료됐지만 claude를 입력하면 command not found가 뜨는 경우, 설치 폴더가 PATH에 등록되지 않은 것입니다.
- 새 터미널 창을 열어 다시 시도하세요. 설치 후 PATH 변경이 현재 열린 터미널에는 적용되지 않습니다. 새 창을 열면 해결되는 경우가 많습니다.
- 그래도 안 된다면, 설치 디렉터리가 PATH에 있는지 확인해야 합니다. 어느 폴더에 설치됐는지는 설치 로그 마지막 줄에서 확인하거나, 아래 명령으로 찾을 수 있습니다.
경로가 출력되면 이미 등록된 것입니다. 아무것도 나오지 않으면 다음 단계로 넘어갑니다.which claude # macOS · Linux where claude # Windows PowerShell - macOS · Linux에서 PATH에 폴더를 추가하려면 셸 설정 파일(
~/.zshrc또는~/.bashrc)을 열어 아래 줄을 추가합니다. [설치경로] 부분은 실제 설치 폴더로 바꿉니다.
저장 후export PATH="$PATH:[설치경로]"source ~/.zshrc(또는source ~/.bashrc)를 실행하거나 터미널을 재시작합니다. - Windows PowerShell에서는 설치 디렉터리를 시스템 PATH에 추가한 뒤 새 PowerShell 창을 열어 다시 시도하세요. 경로 추가 방법은 화면에서 시스템 환경 변수 편집을 검색해 확인합니다.
4단계: curl 오류 유형별 대처
curl: (56) Failure writing output to destination— 파일을 저장할 공간이 없거나 쓰기 권한이 없습니다. 디스크 여유 공간과 폴더 권한을 확인하세요.- TLS 또는 SSL 연결 오류 — CA 인증서(서버 신뢰 목록)가 오래됐거나 회사 프록시가 끼어 있는 경우입니다. Linux라면
sudo apt-get install --reinstall ca-certificates(Ubuntu/Debian 기준) 명령으로 인증서를 갱신해 보세요. 명령어는 배포판마다 다를 수 있으므로 화면의 정확한 패키지 관리자 명칭을 확인하세요. curl: (22) The requested URL returned error: 403— 설치 스크립트가 403 오류를 반환한 경우로, 공식 문서에 따르면 대부분 지역 제한 또는 네트워크 차단입니다.
5단계: Homebrew 설치 오류 (macOS)
Cask 'claude-code' is unavailable: No Cask with this name exists 메시지가 뜬다면 Homebrew의 캐시가 오래된 것입니다. 아래 명령으로 업데이트 후 재시도하세요.
brew update
brew install --cask claude-code6단계: Windows 설치 오류
'bash' is not recognized as the name of a cmdlet— PowerShell에서 bash용 명령을 실행했을 때 납니다. Claude Code 공식 문서에 따르면 Windows에서는 Git for Windows의 bash 또는 PowerShell 전용 설치 명령을 사용해야 합니다. 정확한 명령어는 공식 설치 페이지(code.claude.com)에서 확인하세요.The process cannot access the file because it is being used by another process— 이전 설치 시도의 임시 파일이 잠긴 것입니다. 다운로드 폴더에서 관련 임시 파일을 삭제한 뒤 재시도하세요.- PowerShell 설치 완료 후에도
claude를 못 찾는 경우 — 설치 디렉터리를 PATH에 추가하고 새 PowerShell 창을 열어야 합니다. - 32비트 Windows: Claude Code는 32비트 Windows를 지원하지 않습니다. 시작 메뉴에서 PowerShell을 검색할 때
(x86)이 붙은 항목이 아닌 일반 PowerShell을 사용해야 합니다.
7단계: 로그인·인증 오류
OAuth 오류 또는 로그인 후 403 Forbidden
설치는 됐지만 로그인 단계에서 막힌다면 아래 순서로 점검하세요.
- 로그인 재설정: 공식 문서에 따르면 로그인 정보를 초기화한 뒤 다시 시도하는 것이 가장 빠른 방법입니다. 터미널에서 아래 명령을 실행하세요.
claude logout claude login - 403 Forbidden: 계정이 정상이라면 조직 단위에서 접근이 비활성화됐을 수 있습니다. 구독이 활성 상태인지 claude.com에서 확인하세요. 조직 계정이라면 관리자에게 문의하세요.
- WSL2·SSH·컨테이너 환경에서 OAuth 로그인 실패: 브라우저 리다이렉트가 불가능한 환경입니다. 공식 문서는 이 경우 API 키 방식 인증으로 전환할 것을 안내합니다. 정확한 설정 방법은 code.claude.com의 인증 섹션을 확인하세요.
- Bedrock · Vertex · Foundry 자격증명 오류(
Could not load credentials from any providers등): 클라우드 제공자의 자격증명 설정이 빠진 것입니다. 각 플랫폼의 자격증명 파일 또는 환경 변수를 점검하세요.
8단계: Linux 특수 상황
- 메모리 부족 서버에서 설치 중단(
Killed): 저용량 Linux 서버에서 컴파일 중 프로세스가 강제 종료되는 것입니다. 공식 문서는 스왑 공간을 추가하는 것을 권장합니다. 스왑 추가 명령은 배포판마다 다르므로 화면에서 확인하세요. - musl/glibc 바이너리 불일치(
Error loading shared library): Alpine Linux 등 musl 기반 배포판과 glibc용 바이너리가 맞지 않는 경우입니다. 공식 문서에서 배포판에 맞는 바이너리 변형을 확인하세요. Illegal instruction: CPU가 바이너리가 요구하는 명령어 집합을 지원하지 않습니다. 아키텍처 호환 여부를 확인하세요.
그래도 해결되지 않는다면
위 항목으로 해결되지 않을 때는 두 가지 방법이 있습니다.
- Claude Code 데스크톱 앱 사용: 공식 문서에 따르면 터미널 없이 그래픽 인터페이스로 설치·사용할 수 있는 데스크톱 앱을 macOS와 Windows용으로 제공합니다. 터미널 설치가 계속 막힌다면 이 방법이 가장 빠릅니다.
- 공식 문서 에러 레퍼런스 확인: code.claude.com의 Error reference 페이지에서 500, 529(과부하), 429, 기타 4xx·5xx 오류 코드별 안내를 확인할 수 있습니다.