Windows + WSL 환경에서 Claude CLI 설치 매뉴얼

이 문서는 Windows에서 WSL을 설치하고, Ubuntu 24.04 LTS를 수동으로 등록한 후, WSL 내부에서 Node.js 및 Claude CLI(@anthropic-ai/claude-code)를 설치하는 방법을 설명한다. 모든 작업은 WSL 내부에서 root 사용자로 실행된다는 가정을 따른다.

---

1. WSL 설치 및 Ubuntu 24.04 수동 등록

1.1 WSL 활성화 및 기본 설정

PowerShell을 관리자 권한으로 실행한 뒤 아래 명령을 입력한다:

wsl --install

설치 완료 후 재부팅이 필요하다. 보통 Ubuntu 기본 배포판을 wsl --list --online으로 유효한 배포 목록 확인 후 wsl --install -d Ubuntu-24.04 등으로 쉽게 설치할 수 있다. 그러나 컴퓨터 사용 환경에 따라 (네트워크 방화벽) 불가능 할 수 있으므로, 여기서는 24.04 LTS를 수동 설치방법을 알아본다.

1.2 Ubuntu 24.04 LTS 이미지 다운로드

Ubuntu 24.04 LTS WSL용 .wsl 이미지 파일은 아래 URL에서 받을 수 있다. 해당 이미지는 Microsoft와 Canonical이 배포하는 공식 설치 파일이며, .tar.gz 형식이 아닌 WSL 전용 .wsl 파일이다. curl을 사용하여 직접 다운로드할 수 있다.

curl -L -o ubuntu-24.04.wsl https://releases.ubuntu.com/noble/ubuntu-24.04.wsl

해당 이미지의 SHA256 해시를 sha256sum ubuntu-24.04.wsl 명령어 등을 사용하여 확인한다.

다운로드한 .wsl 파일은 wsl --import 명령어로 바로 등록할 수 있다(압축 해제 불필요).

1.3 다운로드한 이미지 압축 해제 및 등록

예를 들어 /d/WSL/Ubuntu-24.04 디렉토리를 만든 뒤 다음을 수행:

mkdir /d/WSL/Ubuntu-24.04
cd /d/WSL/Ubuntu-24.04

# 다운로드한 .wsl 이미지 기준 등록
wsl --import Ubuntu-24.04 /d/WSL/Ubuntu-24.04 ./ubuntu-24.04.wsl

1.4 Ubuntu 24.04 실행 및 기본 설정

wsl -d Ubuntu-24.04

---

2. WSL 내부에서 기본 도구 설치

apt update && apt upgrade -y
apt install -y curl

---

3. Node.js 및 npm 설치

3.1 NodeSource 설치 스크립트 사용 (Node.js 22 기준)

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs

설치 확인:

node -v
npm -v

---

4. WSL 전용 npm 글로벌 경로 설정

4.1 사용자 전용 경로 생성 및 prefix 설정

mkdir -p ~/.npm-global/bin
npm config set prefix ~/.npm-global

---

5. bashrc 분리 설정 (다른 쉘, 예를 들어 Git Bash와 충돌 방지)

5.1 ~/.bashrc_wsl 파일 생성

vi ~/.bashrc_wsl

아래 내용 입력:

# claude 실행용 Node.js + npm 설정
export PATH=$HOME/.npm-global/bin:$PATH

# Windows 쪽 NPM 경로 제거
export PATH=$(echo $PATH | tr ':' '\n' | grep -v '/mnt/c/Users/<YOUR-WINDOWS-USERNAME>/AppData/Roaming/npm' | paste -sd:)

위에서 <YOUR-WINDOWS-USERNAME> 부분에 사용자의 윈도우 계정 이름을 넣어준다.
Windows 사용자 계정 이름을 정확히 모르겠다면 echo $USER 또는 PowerShell에서 $env:USERNAME으로 확인 가능하다.

5.2 ~/.bashrc에 분기 추가

vi ~/.bashrc

맨 아래에 다음을 추가:

# WSL 환경에서만 ~/.bashrc_wsl 실행
if grep -qi microsoft /proc/version; then
  [ -f "$HOME/.bashrc_wsl" ] && source "$HOME/.bashrc_wsl"
fi

변경 적용:

source ~/.bashrc

---

6. Claude CLI 설치

npm install -g @anthropic-ai/claude-code

설치 후 확인:

which claude

예상 출력:

/root/.npm-global/bin/claude

---

7. 실행 테스트

claude code

정상 실행되면 설치 완료.

---

부록: WSL 자동 진입 스크립트 예시 (PowerShell 또는 Git Bash용)

wsl-ubuntu.sh 파일 작성:

#!/bin/bash
wsl -d Ubuntu-24.04 --exec bash -l

실행 권한 부여:

chmod +x wsl-ubuntu.sh

이 스크립트를 실행하면 .bashrc 설정이 자동으로 반영된 WSL 세션에 진입한다.