클로드코드 설치가 안 될 때: 윈도우·맥 점검법
npm install -g @anthropic-ai/claude-code에서 오류가 나거나, 설치 후 claude를 입력했는데 명령을 찾지 못하는 경우가 있습니다. 에러 문구에 따라 확인할 곳이 다르지만, npm 문제라면 먼저 설치 방식을 바꾸는 게 빠릅니다.
npm 대신 네이티브 설치부터
현재 공식 문서에서 권장하는 방식은 네이티브 설치 스크립트입니다. Node.js가 없어도 실행할 수 있습니다.
맥·리눅스·WSL에서는 다음 명령을 사용합니다.
curl -fsSL https://claude.ai/install.sh | bash
윈도우 PowerShell에서는 이 명령입니다.
irm https://claude.ai/install.ps1 | iex
CMD(명령 프롬프트)를 열었다면 PowerShell 명령이 아니라 CMD 전용 설치 명령을 써야 합니다.
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
EBADENGINE이 뜬 경우
npm 패키지 v2.1.198부터는 Node.js 22 이상을 요구합니다. 다만 공식 문서에 따르면 낮은 버전에서 EBADENGINE 경고가 나와도 설치 자체는 완료될 수 있습니다. 실행 파일이 네이티브 바이너리라 실행할 때 Node.js에 의존하지 않기 때문입니다.
우선 claude --version을 실행해 실제로 설치됐는지 확인하세요. 설치되지 않았다면 node -v로 버전을 보고 Node.js 22 이상으로 올리거나, 위의 네이티브 설치로 전환하면 됩니다.
EACCES: permission denied가 뜬 경우
npm 전역 설치 권한이 막힌 상황입니다. 이때 sudo npm install -g를 붙이는 방법은 공식 문서에서도 피하라고 안내합니다. 대신 네이티브 설치를 사용하세요.
네이티브 설치에서도 같은 권한 오류가 난다면 ~/.local의 소유권을 현재 계정으로 돌린 뒤 다시 설치합니다.
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local
윈도우에서 명령 자체가 먹지 않는다면
Windows 10 1809 이상과 Windows Server 2019 이상은 Claude Code를 네이티브로 지원합니다. 관리자 권한이나 WSL이 꼭 필요한 것은 아닙니다.
'irm'은(는) 내부 또는 외부 명령이 아닙니다가 나오면 PowerShell 명령을 CMD에서 실행한 것입니다.'&&' 토큰이 유효한 문 구분 기호가 아닙니다가 나오면 CMD 명령을 PowerShell에서 실행했을 가능성이 큽니다.- 프롬프트가
PS C:\로 시작하면 PowerShell이고,C:\만 보이면 CMD입니다.
WSL을 선택했다면 WSL 터미널 안에서 맥·리눅스용 curl 명령을 실행해야 합니다. 네이티브 윈도우에서 Git for Windows를 설치하면 Bash 도구를 쓸 수 있지만 필수는 아닙니다. 설치하지 않은 환경에서는 PowerShell이 셸 도구로 사용됩니다.
설치는 됐는데 claude를 못 찾는다면
네이티브 실행 파일은 맥·리눅스에서 ~/.local/bin/claude, 윈도우에서 %USERPROFILE%\.local\bin\claude.exe에 놓입니다. command not found나 'claude'은(는) 인식되지 않습니다가 보인다면 이 폴더가 PATH에 들어 있는지 확인하세요.
맥의 기본 zsh에서는 다음과 같이 추가할 수 있습니다.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
리눅스나 WSL의 bash를 쓴다면 ~/.zshrc 대신 ~/.bashrc에 넣습니다. 윈도우는 터미널을 완전히 닫았다가 다시 열어 보고, 계속 인식하지 못하면 사용자 PATH에 %USERPROFILE%\.local\bin을 추가한 뒤 새 터미널을 여세요.
403 또는 Failed to fetch version
회사 프록시나 방화벽이 설치 파일 서버인 downloads.claude.ai를 막을 때 자주 보이는 오류입니다. Claude를 지원하지 않는 국가나 지역에서도 403이 날 수 있으므로 해외망이나 VPN을 쓰는 중이라면 접속 위치도 확인해야 합니다.
회사 네트워크라면 IT팀에서 프록시 주소를 받아 환경 변수를 설정합니다.
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
휴대폰 테더링처럼 다른 네트워크에서 설치를 시도해 보면 회사망 차단인지 구분할 수 있습니다.
마지막으로 claude doctor를 실행하면 설치 상태와 설정을 진단할 수 있습니다. npm판과 네이티브판이 함께 남아 있다면 ls ~/.local/bin/claude와 npm ls -g @anthropic-ai/claude-code로 확인한 뒤 하나만 유지하세요. 공식 권장은 네이티브 설치입니다.
설치는 끝났는데 로그인에서 멈춘다면 계정도 확인해야 합니다. Claude Code는 Pro, Max, Team, Enterprise 또는 API(Console) 계정이 필요하고 무료 Claude.ai 플랜에서는 사용할 수 없습니다. 오류가 계속되면 공식 설치 문제 해결 문서에서 화면에 나온 문구를 찾아보세요.