윈도우에서 Claude Code WSL 설치하기, 처음부터 끝까지

윈도우에서 Claude Code를 WSL로 세팅하는 전 과정을 정리했습니다. WSL 설치부터 Node.js, 인증, 첫 명령어 실행까지 약 40분 소요되며 자주 막히는 지점과 해결법을 함께 다룹니다.

요즘 "바이브 코딩"이라는 말이 자주 들립니다. 코드를 한 줄도 안 써본 사람도 AI에게 말로 시켜서 프로그램을 만드는 흐름인데요, 그 중심에 있는 도구 중 하나가 바로 Claude Code입니다. 다만 윈도우 사용자라면 시작부터 막히는 지점이 하나 있습니다. Claude Code가 윈도우에서 직접 돌아가지 않고, WSL이라는 리눅스 환경 위에서 써야 한다는 점입니다. 이 글은 WSL이 뭔지도 모르는 분이 처음부터 끝까지 따라 할 수 있도록 정리한 가이드입니다. 명령어 한 줄씩 풀어 설명하니 부담 없이 따라오셔도 됩니다.

Claude Code와 WSL이 뭐길래

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 도구입니다. ChatGPT처럼 대화창에 프롬프트만 넣는 게 아니라, 내 컴퓨터 폴더 안의 파일을 직접 읽고 고치고 새로 만들 수 있다는 게 핵심입니다. "이 폴더의 엑셀 파일들을 하나로 합쳐줘" 같은 작업을 시키면 알아서 코드를 짜고 실행까지 해줍니다.

문제는 이 도구가 macOS와 리눅스 환경을 우선 지원한다는 점입니다. 윈도우에서 직접 설치하려고 하면 권한 오류나 경로 문제로 자주 막힙니다. 그래서 마이크로소프트가 만든 WSL을 씁니다.

WSL(Windows Subsystem for Linux)은 한 줄로 말하면 윈도우 안에서 리눅스를 돌릴 수 있게 해주는 마이크로소프트 공식 기능입니다. 가상머신처럼 무겁지 않고, 윈도우 키 누르면 그냥 우분투(Ubuntu, 가장 널리 쓰이는 리눅스 배포판) 창이 뜹니다. 비유하자면 윈도우 안에 작은 리눅스 방을 하나 만드는 셈입니다.

구분	윈도우 직접 설치	WSL 사용 (권장)
공식 지원	베타 수준	완전 지원
설치 난이도	자주 막힘	한 번 세팅 후 안정적
파일 접근	윈도우 폴더 그대로	윈도우 폴더도 접근 가능
속도	느릴 수 있음	네이티브에 가까움

💡 글 작성 시점 기준으로 Anthropic 공식 문서도 윈도우 사용자에게 WSL 사용을 권장합니다.

설치 전에 준비할 것들

본격적으로 들어가기 전에 환경을 한번 점검하겠습니다. 아래 항목을 확인해주세요.

• [ ] 윈도우 10 (빌드 19041 이상) 또는 윈도우 11
• [ ] 관리자 권한이 있는 사용자 계정
• [ ] 인터넷 연결 (설치 중 약 2~3GB 다운로드)
• [ ] 여유 디스크 공간 10GB 이상
• [ ] Anthropic 계정 (없으면 가입 필요, 무료)

윈도우 버전은 윈도우키 + R 누르고 winver라고 치면 확인됩니다. 윈도우 10이라도 2020년 이후로 업데이트했다면 대부분 통과합니다.

전체 흐름은 이렇게 됩니다.

[1단계] WSL 설치 (우분투 자동 포함)
   ↓
[2단계] 우분투에서 Node.js 설치
   ↓
[3단계] Claude Code 설치
   ↓
[4단계] Anthropic 계정 인증
   ↓
[5단계] 첫 명령어 실행

WSL 설치 단계

WSL 설치는 명령어 한 줄로 끝납니다. 단, 관리자 권한이 필요합니다.

윈도우 시작 메뉴에서 "PowerShell"을 검색한 뒤, "관리자 권한으로 실행"을 꼭 선택해주세요. 그냥 클릭하면 권한 부족으로 실패합니다. 검은 창이 뜨면 아래 명령을 입력합니다.

wsl --install

이 명령은 WSL과 우분투를 한 번에 설치하는 마이크로소프트 공식 명령입니다. 진행되는 동안 약 5~10분 정도 걸리고, 끝나면 컴퓨터 재부팅을 요구합니다. 재부팅하면 자동으로 우분투 설정 창이 뜨는데, 처음 한 번 사용자 이름과 비밀번호를 정해야 합니다.

💡 비밀번호는 입력해도 화면에 점이나 별표가 안 뜹니다. 고장 난 게 아니라 리눅스의 보안 정책입니다. 그냥 입력하고 Enter 누르세요.

여기서 정한 비밀번호는 앞으로 시스템 설정을 바꿀 때 자주 쓰입니다. 잊어버리지 않게 메모해두는 걸 추천드립니다.

설정이 끝나면 username@DESKTOP-XXXX:~$ 같은 초록색 글씨가 뜹니다. 이게 우분투 터미널입니다. 이 창이 앞으로 우리의 작업 공간입니다. 윈도우 시작 메뉴에서 "Ubuntu"를 검색하면 언제든 다시 열 수 있습니다.

Node.js 설치 — Claude Code의 토대

Claude Code는 Node.js 위에서 돌아갑니다. Node.js는 자바스크립트라는 프로그래밍 언어를 컴퓨터가 실행할 수 있게 해주는 엔진이라고 보시면 됩니다. Claude Code 자체가 자바스크립트로 만들어졌기 때문에 이 엔진이 먼저 깔려있어야 합니다.

우분투에 Node.js를 설치하는 방법은 여러 가지인데, nvm이라는 도구로 까는 걸 추천합니다. nvm은 Node.js 버전을 손쉽게 갈아끼울 수 있게 해주는 관리자입니다. 나중에 다른 버전이 필요할 때 편합니다.

우분투 터미널에 아래 명령을 차례로 붙여넣습니다.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

이 명령은 인터넷에서 nvm 설치 스크립트를 받아서 바로 실행하는 명령입니다. 끝나면 터미널 창을 한 번 닫고 다시 엽니다 (이게 중요합니다, 안 그러면 다음 명령이 안 먹힙니다).

다시 연 우분투 창에 이렇게 입력합니다.

nvm install 20

숫자 20은 Node.js 버전입니다. Claude Code는 공식 문서 기준으로 Node.js 18 이상을 요구하는데, 안정적인 LTS 버전인 20을 쓰는 게 무난합니다. 1~2분 기다리면 설치가 끝납니다.

설치 확인은 아래 명령으로 합니다.

node --version

v20.xx.x 같은 버전 숫자가 뜨면 성공입니다. 만약 command not found가 뜨면 터미널을 다시 한번 껐다 켜보세요. 저도 이 부분에서 한참 헤맸습니다.

Claude Code 설치와 인증

이제 본 게임입니다. 우분투 터미널에 다음 명령을 입력합니다.

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

npm은 Node.js와 함께 설치되는 자바스크립트 패키지 설치 도구입니다. -g는 "내 컴퓨터 어디서나 쓸 수 있게 전역으로 설치하라"는 뜻이고, @anthropic-ai/claude-code가 실제 설치할 패키지 이름입니다.

설치가 끝나면 아무 폴더에서나 claude라는 명령을 쓸 수 있게 됩니다. 한번 실행해봅니다.

claude

처음 실행하면 인증 화면이 뜹니다. 안내에 따라 브라우저가 열리고, Anthropic 계정으로 로그인하면 됩니다. 계정이 없으면 그 자리에서 가입할 수 있습니다 (이메일만 있으면 됩니다).

여기서 한 가지 짚고 갈 점이 있습니다. Claude Code는 유료 서비스입니다.

플랜	비용 (글 작성 시점)	특징
Pro	월 $20	일반 사용자 대상, 사용량 제한 있음
Max	월 $100 ~ $200	헤비 사용자, 한도 대폭 확장
API 종량제	사용량만큼	토큰 단위 과금

가볍게 써볼 거라면 Pro로 시작해도 충분합니다. 프롬프트 한두 번 돌려보고 맞는지 확인한 다음 결정하셔도 늦지 않습니다.

첫 명령어 실행해보기

인증이 끝났으면 작업할 폴더 하나를 만들어 들어갑니다.

mkdir my-first-project
cd my-first-project
claude

mkdir은 새 폴더 만들기, cd는 그 폴더로 들어가기 명령입니다. 그 안에서 claude를 치면 Claude Code가 그 폴더를 작업 공간으로 인식합니다.

이제 채팅처럼 자연어로 시키기만 하면 됩니다. 예를 들어 이런 식으로요.

간단한 할 일 목록을 저장하는 파이썬 스크립트를 만들어줘. 
명령줄에서 추가, 삭제, 보기 기능을 쓸 수 있게 해줘.

Claude Code가 잠시 생각하더니 파일을 만들고, 코드를 작성하고, 필요하면 실행까지 해줍니다. 중간중간 "이 파일을 수정해도 될까요?"라고 묻는데, y를 누르면 진행되고 n을 누르면 멈춥니다.

블로그 글 쓰시는 분이라면 "이 폴더 안 마크다운 파일들의 제목만 뽑아서 목차로 만들어줘" 같은 요청도 잘 처리합니다. 엑셀 작업이 잦은 분은 "이 csv 파일에서 특정 열만 골라 새 파일로 저장하는 스크립트 만들어줘"가 자주 쓰는 패턴입니다.

윈도우 폴더와 연결하기

이 부분은 비전공자가 가장 많이 헷갈리는 지점입니다. WSL은 우분투 안에 자기만의 파일 시스템을 갖고 있어서, 평소에 쓰던 C:\Users\내이름\Documents 같은 윈도우 폴더와 따로 놉니다. 그러면 윈도우 바탕화면 파일을 어떻게 작업하느냐, 두 가지 방법이 있습니다.

방법 1: 우분투 터미널에서 윈도우 폴더 접근. 윈도우의 C 드라이브는 우분투 안에서 /mnt/c/로 보입니다.

cd /mnt/c/Users/내이름/Documents

방법 2: WSL 안에 작업 폴더를 두고, 윈도우 탐색기로 접근. 우분투 터미널에서 explorer.exe .이라고 치면 (점 앞에 공백 있음) 현재 폴더가 윈도우 탐색기로 열립니다.

💡 속도와 안정성 면에서는 방법 2가 권장됩니다. 윈도우 폴더를 WSL에서 자주 접근하면 속도가 눈에 띄게 느려진다는 보고가 많습니다.

자주 막히는 부분과 해결법

직접 세팅하면서, 그리고 주변에서 따라 한 분들이 자주 걸린 지점만 골라봤습니다.

증상	원인	해결
wsl --install이 "지원되지 않음"	윈도우 버전이 낮음	윈도우 업데이트 먼저
node: command not found	nvm 설치 후 터미널 재시작 안 함	우분투 창 껐다 켜기
claude 실행 시 권한 에러	sudo 없이 npm 전역 설치 시도	nvm으로 설치하면 자동 해결
인증 페이지가 안 열림	WSL이 브라우저 못 부름	터미널에 뜬 URL을 직접 복사해 윈도우 브라우저에 붙여넣기
응답이 매우 느림	윈도우 폴더(/mnt/c/)에서 작업 중	WSL 홈 디렉토리(~)로 옮겨서 작업

가상화 기능 관련 오류도 종종 나옵니다. BIOS에서 가상화(VT-x 또는 AMD-V)가 꺼져 있으면 WSL이 안 깔립니다. 메인보드 제조사마다 BIOS 진입 키가 달라서(보통 F2, F10, Del), 컴퓨터 부팅 시 화면 하단을 잘 보시면 안내가 뜹니다. 거기 들어가서 Virtualization Technology 항목을 Enabled로 바꿔주면 됩니다.

마무리

여기까지 따라오셨다면 WSL, Node.js, Claude Code 세 가지가 한 몸처럼 돌아가는 환경이 만들어진 겁니다. 처음 한 번이 어렵지 다음부턴 우분투 창 열고 claude 한 줄이면 끝납니다.

당장 뭘 해볼지 고민된다면, 평소 컴퓨터로 반복하던 작업 하나를 골라 시켜보세요. 폴더 정리, 파일명 일괄 변경, 엑셀 데이터 합치기 같은 잡일이 가장 좋은 출발점입니다. 코드를 몰라도 결과물이 바로 나오니 효용이 즉각 느껴지거든요. 그러면서 자연스럽게 명령어 몇 개와 폴더 구조 감각이 쌓입니다. 막히면 Claude Code 자체에 "방금 한 게 무슨 뜻이야?"라고 물어보면 친절히 알려줍니다. 이게 의외로 가장 빠른 학습법이었습니다.