WSL에서 Claude Code 실행 안 될 때 해결법

트러블슈팅

WSL에서 Claude Code 설치가 안 된다면, Node.js 버전·npm 권한·네트워크·WSL 설정 네 가지를 순서대로 점검해보세요. 대부분 10분 안에 해결됩니다.

📌 3줄 요약

• WSL에서 Claude Code 설치 실패는 Node.js 미설치/구버전, npm 권한, 네트워크 차단, WSL 설정 네 가지 원인이 대부분입니다.
• nvm으로 Node.js 18 이상을 설치하고, npm 글로벌 경로를 사용자 디렉토리로 변경하면 권한 문제까지 한 번에 해결됩니다.
• WSL 2 + 리눅스 홈 디렉토리 조합이 가장 안정적인 실행 환경입니다.

📑 목차

• 1. WSL 환경에서 Claude Code가 안 되는 이유
• 2. Node.js 버전과 npm 설치 상태 점검하기
• 3. WSL 네트워크와 권한 문제 해결하기
• 4. Claude Code 정상 실행 확인과 추가 팁

WSL 환경에서 Claude Code가 안 되는 이유

Windows에서 Claude Code를 쓰려고 WSL(Windows Subsystem for Linux)을 설치한 분이 많습니다. WSL은 Windows 안에서 리눅스를 돌리는 기능인데, Claude Code가 공식적으로 리눅스 환경을 지원하기 때문입니다. Mac이나 리눅스 환경에서는 터미널에서 바로 설치하면 되지만, Windows 사용자는 WSL이라는 중간 단계를 하나 더 거쳐야 하는 셈입니다. 특히 공대생이라면 노트북에 Windows가 깔려 있는 경우가 대부분이라, WSL을 통한 설치가 사실상 표준 경로라고 볼 수 있습니다.

그런데 WSL을 설치하고 npm install -g @anthropic-ai/claude-code를 입력했는데 에러가 나는 경우가 자주 발생합니다. 원인은 크게 네 가지로 나뉩니다. Node.js 미설치 또는 버전 불일치, npm 권한 문제, 네트워크 차단, WSL 자체 설정 오류입니다. 이 네 가지가 개별로 발생하기도 하고, 두세 가지가 동시에 겹쳐서 나타나기도 합니다. 처음 WSL을 접하는 분일수록 에러 메시지를 보고 어디서부터 손대야 할지 막막할 수 있습니다.

 

문제는 에러 메시지만 보면 원인을 특정하기 어렵다는 점입니다. command not found, EACCES, ETIMEDOUT 같은 메시지가 뒤섞여 나올 수 있습니다. 영어로 된 에러 메시지를 구글에 검색해도 WSL 환경에 딱 맞는 해결법을 찾기 쉽지 않습니다. 일반 리눅스와 WSL은 네트워크, 파일 시스템 등에서 미묘한 차이가 있어서 같은 해결법이 통하지 않는 경우도 있습니다.

💬 제가 직접 WSL 환경을 여러 번 세팅해보니, 대부분의 문제는 아래 순서대로 점검하면 해결됩니다.

이 글에서는 각 원인별로 구체적인 확인 방법과 해결 명령어를 정리하겠습니다. 순서대로 따라 하면 초보자도 10분 안에 원인을 파악하고 해결할 수 있습니다.

Node.js 버전과 npm 설치 상태 점검하기

Claude Code를 실행하려면 Node.js 18 버전 이상이 필요합니다. WSL에 기본 설치된 Node.js가 없거나, 오래된 버전이 깔려 있으면 설치 자체가 실패합니다.

🔍 Node.js란? JavaScript를 터미널에서 실행할 수 있게 해주는 런타임 환경입니다. Claude Code가 내부적으로 JavaScript 기반으로 동작하기 때문에 Node.js가 반드시 있어야 합니다.

먼저 터미널에서 현재 Node.js 버전을 확인합니다.

 

node -v를 입력했을 때 버전이 표시되지 않으면 Node.js가 설치되지 않은 상태입니다. v16이나 v14처럼 낮은 버전이 나오면 업그레이드가 필요합니다. 간혹 node는 되는데 npm이 안 되는 경우도 있는데, 이때는 npm -v로 npm 설치 여부도 함께 확인해야 합니다.

🔍 nvm(Node Version Manager)이란? Node.js 버전을 쉽게 설치하고 전환할 수 있게 해주는 도구입니다. 여러 프로젝트에서 서로 다른 Node.js 버전이 필요할 때도 nvm으로 간편하게 전환할 수 있어서, 한번 설치해두면 두고두고 유용합니다.

Node.js를 WSL에 설치하는 가장 안정적인 방법은 nvm을 사용하는 것입니다. 설치 순서는 다음과 같습니다.

1

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash 명령어로 nvm을 설치합니다.

2

터미널을 닫았다가 다시 열어줍니다.

3

nvm install --lts 명령어로 최신 LTS 버전의 Node.js를 설치합니다.

4

node -v로 18 이상인지 확인합니다.

 

💡 nvm 설치 후 nvm: command not found가 나오는 경우가 있습니다. 이때는 source ~/.bashrc를 입력하거나, 터미널을 완전히 종료 후 다시 시작하면 됩니다. zsh을 사용하는 분이라면 ~/.bashrc 대신 ~/.zshrc에 nvm 설정이 들어가므로 source ~/.zshrc를 사용해야 합니다.

Node.js 설치가 확인되면 Claude Code를 다시 설치합니다. npm install -g @anthropic-ai/claude-code를 입력하고 에러 없이 완료되는지 확인합니다. 설치가 정상적으로 끝나면 added X packages 같은 메시지가 출력됩니다.

💬 제가 직접 써보니, WSL에서는 시스템 패키지 매니저(apt)로 Node.js를 설치하면 버전이 낮은 경우가 많았습니다. sudo apt install nodejs로 설치하면 v12 같은 구버전이 깔리는 경우가 흔합니다. nvm을 쓰는 게 가장 깔끔한 방법이었습니다.

WSL 네트워크와 권한 문제 해결하기

Node.js 버전이 정상인데도 설치가 실패하면 네트워크나 권한 문제일 가능성이 높습니다. npm 설치 시 EACCES 에러가 나오면 권한 문제, ETIMEDOUT이나 ENOTFOUND가 나오면 네트워크 문제입니다. 이 두 가지는 에러 메시지의 영문 키워드로 구분할 수 있으니, 에러가 뜨면 메시지를 꼼꼼히 읽어보는 것이 중요합니다.

권한 문제부터 살펴보겠습니다.

⚠️ sudo npm install -g로 해결하는 분이 있는데, 이 방법은 권장되지 않습니다. sudo를 붙이면 루트 권한으로 패키지가 설치되어, 이후 실행이나 업데이트 시에도 계속 sudo가 필요해지는 악순환이 생깁니다. 보안 측면에서도 불필요하게 높은 권한을 주는 것은 좋은 습관이 아닙니다.

대신 npm의 글로벌 설치 경로를 사용자 디렉토리로 변경하는 것이 안전합니다. mkdir ~/.npm-global && npm config set prefix '~/.npm-global' 명령어를 입력합니다.

그 다음 ~/.bashrc 파일 맨 아래에 export PATH=~/.npm-global/bin:$PATH를 추가합니다. source ~/.bashrc를 실행한 뒤 다시 설치를 시도하면 권한 에러 없이 진행됩니다. 이 설정은 한 번만 해두면 이후 모든 npm 글로벌 패키지 설치에 적용되므로, 처음 환경을 세팅할 때 미리 해두는 것을 추천합니다.

네트워크 문제는 회사나 학교 네트워크에서 자주 발생합니다. 프록시(proxy)나 방화벽이 npm 레지스트리 접속을 차단하는 경우입니다. 특히 대학교 캠퍼스 와이파이는 보안 정책이 엄격한 경우가 많아서, 외부 패키지 저장소 접속이 막혀 있을 수 있습니다.

ping registry.npmjs.org 명령어로 연결 상태를 확인할 수 있습니다. 응답이 오지 않으면 DNS 설정을 변경해야 합니다.

🔍 WSL의 DNS 설정은 /etc/resolv.conf 파일에서 관리됩니다. 이 파일을 열어 nameserver 8.8.8.8로 변경하면 구글 DNS를 사용하게 되어 대부분 해결됩니다. 구글 DNS 외에 1.1.1.1(Cloudflare DNS)을 사용해도 동일한 효과를 볼 수 있습니다.

 

⚠️ WSL은 재시작할 때마다 /etc/resolv.conf 파일을 자동으로 덮어쓸 수 있습니다. 영구 적용하려면 /etc/wsl.conf 파일에 [network] 섹션을 추가하고 generateResolvConf = false를 넣어야 합니다. 이 설정을 하지 않으면 WSL을 재시작할 때마다 DNS 설정이 초기화되어, 같은 문제가 반복적으로 발생합니다.

💬 제가 직접 써보니, 학교 와이파이에서 이 네트워크 문제를 겪는 경우가 특히 많았습니다. DNS 변경만으로 해결되는 경우가 절반 이상이니 꼭 먼저 시도해보시길 바랍니다.

Claude Code 정상 실행 확인과 추가 팁

설치가 완료되면 claude 명령어를 입력해서 정상 실행되는지 확인합니다. 처음 실행 시 API 키 입력 화면이 나오면 설치에 성공한 것입니다. Claude Code는 첫 실행 시 인증 과정을 거치는데, 이 화면이 뜬다는 것은 프로그램 자체가 정상적으로 로드되었다는 의미입니다.

 

만약 claude 입력 시 여전히 command not found가 나온다면 경로 설정을 확인해야 합니다. which claude 또는 npm list -g --depth=0 명령어로 패키지가 실제로 설치되었는지 점검합니다. which claude에서 경로가 출력되면 설치는 되어 있지만 PATH에 해당 경로가 없는 상황이고, 아무것도 출력되지 않으면 설치 자체가 안 된 상황입니다.

설치는 되었는데 경로가 잡히지 않는 경우, ~/.bashrc에 npm 글로벌 경로가 올바르게 추가되어 있는지 확인합니다. echo $PATH 명령어로 현재 경로 목록을 출력해볼 수 있습니다. 출력된 경로 목록 중에 .npm-global/bin이 포함되어 있어야 claude 명령어가 인식됩니다.

WSL 환경에서 Claude Code를 안정적으로 사용하기 위한 추가 팁도 정리하겠습니다.

1

WSL 버전은 반드시 WSL 2를 사용합니다.

PowerShell에서 wsl --list --verbose 명령어로 현재 WSL 버전을 확인할 수 있습니다. VERSION 열에 1이 표시되면 WSL 1을 사용 중인 것이므로 업그레이드가 필요합니다. WSL 1은 리눅스 커널이 아닌 변환 계층(translation layer)을 사용하기 때문에 호환성 문제가 발생할 수 있습니다. wsl --set-version Ubuntu 2 명령어로 WSL 2로 전환할 수 있습니다. 전환 과정에서 시간이 조금 걸릴 수 있는데, 완료될 때까지 기다렸다가 다시 WSL을 실행하면 됩니다.

2

Windows 측 경로(/mnt/c/)에서 작업하지 않습니다.

Claude Code 프로젝트는 리눅스 홈 디렉토리(~/projects/ 등)에 두는 것이 좋습니다. /mnt/c/에서 작업하면 파일 읽기·쓰기 속도가 10배 이상 차이 나는 경우도 있어서, Claude Code의 응답 속도에도 영향을 줍니다.

3

WSL 멈춤 시 재시작합니다.

WSL을 장시간 사용하지 않으면 자동으로 종료될 수 있습니다. wsl --shutdown 후 다시 시작하면 깨끗한 상태에서 재실행됩니다. 간혹 WSL이 멈추거나 반응이 없을 때도 이 명령어로 완전히 종료한 뒤 재시작하면 대부분 정상으로 돌아옵니다.

💬 제가 직접 써보니, WSL 2 + 리눅스 홈 디렉토리 조합이 가장 안정적이었습니다. 이 두 가지만 지켜도 대부분의 실행 오류를 사전에 방지할 수 있었습니다.

✍️ 마치며

WSL에서 Claude Code가 안 될 때 가장 많은 원인은 Node.js 버전 문제와 npm 권한 문제입니다. nvm으로 최신 LTS를 설치하고, 글로벌 경로를 사용자 디렉토리로 잡으면 대부분 해결됩니다. 네트워크 문제는 DNS를 8.8.8.8로 변경하는 것만으로도 절반 이상 해결되고, WSL 2와 리눅스 홈 디렉토리를 사용하면 안정성까지 확보할 수 있습니다. 에러가 나더라도 당황하지 말고, 이 글의 순서대로 하나씩 점검해보세요.

#ClaudeCode #WSL설치오류 #WSL2 #NodeJS설치 #nvm #npm권한오류 #Windows개발환경 #공대생코딩