클로드 코드 npm 설치 오류, 네이티브 설치로 정리하는 순서

Claude Code npm 설치 오류가 뜨면 보통 계정부터 의심하게 된다. 그런데 내 기준에서는 설치 경로부터 보는 편이 훨씬 빠르다. 예전에 npm으로 설치한 claude와 새 네이티브 설치 파일이 PATH 안에서 섞이면, 로그인은 멀쩡해도 터미널이 엉뚱한 실행 파일을 잡는다.

특히 최근 1년 안에 npm 방식으로 Claude Code를 깔아둔 사람은 한 번쯤 이 정리를 해두는 게 낫다고 봅니다. 문제는 새 설치 명령을 다시 치는 게 아니라, 예전 설치 흔적을 그대로 둔 채 같은 이름의 실행 파일을 또 만드는 쪽에 있다. 이 글은 그 부분만 잘라서 본다.

먼저 어떤 claude가 잡히는지 본다

Claude Code npm 설치 오류는 설치가 아예 안 된 경우보다, 설치된 위치가 2곳 이상인 경우가 더 헷갈린다. 예를 들어 PowerShell에서 claude를 쳤는데 npm 전역 경로가 먼저 잡히면, 네이티브 설치를 해도 계속 예전 문제가 반복될 수 있다.

여기서 여러 줄이 나오면 충돌 가능성이 있다. Native Installer가 만든 Windows 실행 파일은 보통 사용자 폴더 아래의 .local\bin\claude.exe 쪽에 있다. 반면 npm 전역 설치는 Node.js 전역 bin 경로 쪽에서 잡히는 경우가 많죠.

npm 패키지가 남아 있는지도 바로 확인한다. 이 명령은 삭제가 아니라 조회라서 먼저 쳐도 부담이 없다.

패키지명이 보이면 예전 전역 설치가 남아 있다는 뜻이다. 안 보이는데도 문제가 남으면 PATH나 .claude\local 쪽을 의심해야 한다. 이 순서를 추천합니다. 새로 설치부터 누르면 원인이 더 흐려진다.

npm 전역 설치는 따로 지운다

npm 전역 설치가 확인되면 아래 명령으로 제거한다. 프로젝트 폴더를 지우는 명령이 아니라 컴퓨터에 전역으로 깔린 Claude Code npm 패키지만 빼는 명령이다.

예를 들어 1년 전에 npm으로 설치했고, 최근 네이티브 설치를 한 번 더 했다면 이 명령이 먼저다. 다만 Node.js 자체를 지우는 건 추천하지 않습니다. 다른 개발 프로젝트가 npm을 쓰고 있을 수 있기 때문이다.

Windows에서 예전 로컬 설치 흔적이 남아 있는지도 볼 수 있다. 아래 첫 줄은 폴더 존재 확인이고, 둘째 줄은 실제 삭제다.

함정은 여기다. 오류가 난다고 아무 폴더나 지우면 다음에 더 피곤해진다. where.exe claude와 npm 조회에서 확인된 흔적만 정리하는 게 안전합니다.

셸에 맞는 네이티브 설치 명령을 고른다

정리가 끝났으면 네이티브 설치로 다시 잡는다. Windows PowerShell에서는 아래 명령을 쓴다.

CMD 창에서는 PowerShell 명령이 아니라 CMD용 명령을 써야 한다.

macOS, Linux, WSL에서는 아래처럼 설치한다.

예를 들어 프롬프트가 PS C:\로 시작하는데 CMD용 && 명령을 붙이면 문법 오류가 난다. 반대로 CMD에서 irm을 치면 명령을 모른다고 나온다. 설치 파일이 나쁜 게 아니라 창을 잘못 고른 경우가 꽤 많다.

PATH 문제는 새 터미널에서 확인한다

설치가 끝났는데도 claude를 못 찾는다면 PATH 문제일 가능성이 높다. Windows에서는 네이티브 실행 파일이 실제로 생겼는지 먼저 본다.

파일은 있는데 명령이 안 잡히면 사용자 PATH에 %USERPROFILE%\.local\bin이 빠졌을 수 있다. PowerShell에서는 아래처럼 추가할 수 있다.

대신 PATH를 바꾼 뒤에는 같은 터미널에서 바로 판단하면 안 됩니다. 새 창을 열어야 바뀐 PATH가 적용된다. 여기서 바로 확인할 건 2개다.

claude --version은 실행 파일이 잡혔는지 보는 용도고, claude doctor는 설치 상태와 설정 문제를 보는 용도다. 이 2개가 통과하면 Claude Code npm 설치 오류는 대부분 설치 경로 쪽에서 정리된 셈이죠.

로그인 오류까지 한꺼번에 보지 않는다

설치가 끝난 뒤 claude를 실행하면 브라우저 로그인이 필요할 수 있다. Claude Code는 Claude Pro, Max, Team, Enterprise, Console 계정이나 지원되는 API provider 구성이 필요하다. 하지만 설치 명령이 실패한 것과 로그인 권한이 막힌 것은 다른 문제다.

나는 이 둘을 한 화면에서 같이 보지 않는 걸 추천합니다. 먼저 실행 파일 충돌을 정리하고, 그 다음 계정 로그인을 보는 순서가 덜 꼬인다. 오히려 처음부터 로그인 문제로 몰고 가면 npm 전역 설치 흔적을 놓치기 쉽다.

마지막으로 다시 한 번만 확인하면 된다. where.exe claude로 잡히는 경로를 보고, npm -g ls @anthropic-ai/claude-code에서 예전 전역 설치가 사라졌는지 본다. 그 다음 claude doctor를 돌린다. 여기까지 맞으면 네이티브 설치로 넘어가는 작업은 끝났다고 봐도 된다.

이번 문제는 새 기능을 배우는 일이 아니라 바닥을 치우는 일이다. Native Installer로 옮기면 npm 전역 권한 문제를 덜 만나고, 업데이트 경로도 단순해진다. Claude Code를 계속 쓸 생각이라면 이 정리는 한 번 해두는 편이 좋다.