윈도우에서 Claude Code는 '설치 명령을 어느 셸에 붙여넣었는가'부터 꼬이기 시작합니다. PowerShell·CMD·Git Bash·WSL 네 갈래 길에서 무엇을 골라야 하는지 결정 기준을 먼저 세우고, 네이티브 설치와 WSL2 설치를 각각 처음부터 끝까지 따라갑니다. irm not recognized, 실행 정책 차단, PATH 미등록, WSL에서 node not found, 회사 프록시 TLS 오류까지 — 실제로 가장 많이 막히는 지점 12가지를 공식 문서 기준으로 정리했습니다.
맥에서는 터미널 하나, 설치 명령 하나면 끝나는 일이, 윈도우에서는 시작부터 갈림길입니다. PowerShell, CMD, Git Bash, WSL — 터미널이 네 종류이고, 설치 명령이 셸마다 다르고, 인터넷에서 복사한 명령이 어느 셸용인지 구분이 안 되기 때문입니다. 실제로 윈도우 사용자가 겪는 오류의 절반은 Claude Code 자체가 아니라 "맥/리눅스용 명령을 PowerShell에 붙여넣어서" 생깁니다.
이 글은 그 갈림길을 먼저 정리합니다. 어느 길을 갈지 결정한 다음, 각 경로의 설치를 처음부터 끝까지 따라가고, 마지막에 실제로 가장 많이 보고되는 오류 12가지의 해결법을 정리했습니다. 2026년 8월 30일 기준 공식 설치 문서와 문제 해결 문서를 따릅니다.
2025년 말부터 Claude Code는 WSL 없이 윈도우에서 네이티브로 돌아갑니다. 그래서 이제 선택지는 둘입니다.
| 기준 | 네이티브 윈도우 | WSL 2 (Ubuntu) |
|---|---|---|
| 설치 난이도 | 쉬움 — PowerShell 명령 한 줄 | WSL 설치 + 리눅스 환경 구성 필요 |
| 어울리는 프로젝트 | .NET, 윈도우 전용 도구, PowerShell 스크립트 | Node·Python 웹 개발, Docker, Bash 스크립트 |
| 셸 도구 | PowerShell (Git for Windows 설치 시 Bash) | 진짜 리눅스 Bash |
| 샌드박스 격리 실행 | 미지원 | 지원 |
| 파일 성능 | 윈도우 파일은 빠름 | 리눅스 홈(~/) 안은 빠름. /mnt/c로 윈도우 파일을 건드리면 매우 느림 |
| 함정 | 실행 정책·PATH·백신 간섭 | 윈도우 Node가 끼어드는 PATH 오염 |
결정 기준은 하나로 요약됩니다. 작업할 프로젝트가 리눅스 서버에 배포되는 웹/백엔드라면 WSL2, 윈도우에서 돌아가는 것을 만든다면 네이티브입니다. 잘 모르겠다면 네이티브로 시작하세요. 더 간단하고, 나중에 WSL로 옮기는 것도 어렵지 않습니다.
~/project)에 두세요. /mnt/c/Users/...의 윈도우 폴더를 WSL에서 열면 파일 접근이 수십 배 느려지고, 경로·심링크·파일 감시가 전부 이상하게 동작합니다. 반대로 네이티브를 쓰면서 \\wsl.localhost\... 경로를 여는 것도 마찬가지입니다.| 필요한 것 | 확인 |
|---|---|
| Windows 10 1809 이상 / Windows 11 | 64비트만 지원. Win+R → winver |
| Claude 유료 계정 | Pro · Max · Team · Enterprise. 무료 플랜 불가 |
| Windows Terminal | Windows 11은 기본 내장. 10이면 Microsoft Store에서 설치 — 탭·유니코드·한글 렌더링이 구형 콘솔보다 훨씬 낫습니다 |
| 인터넷 | 회사망이면 claude.ai, downloads.claude.ai 허용 확인 |
그리고 시작 전에 이것 하나만 기억하세요. 지금 열린 창이 PowerShell인지 CMD인지 구분하는 법: 프롬프트가 PS C:\Users\you>처럼 PS로 시작하면 PowerShell, C:\Users\you>면 CMD입니다. 이 글의 명령은 특별한 표시가 없으면 전부 PowerShell 기준입니다.
윈도우의 공식 패키지 관리자 winget이 맥의 Homebrew 역할을 합니다. Windows 10 1709 이상이면 이미 들어 있습니다. PowerShell을 열고(관리자 권한 불필요):
winget install Git.Git GitHub.cli OpenJS.NodeJS.LTS Microsoft.VisualStudioCode
| 패키지 | 왜 |
|---|---|
| Git.Git (Git for Windows) | 버전 관리 + Git Bash 제공. Git Bash가 있으면 Claude Code가 Bash 도구를 쓸 수 있어서 리눅스식 명령·스크립트가 그대로 돌아갑니다. 없으면 PowerShell 도구로 동작 |
| GitHub.cli (gh) | PR 생성·저장소 클론 인증 |
| OpenJS.NodeJS.LTS | Node LTS + npm. Claude Code 자체는 Node가 필요 없지만(네이티브 바이너리) 대부분의 프로젝트가 필요 |
| VisualStudioCode | 에디터 + Claude Code 확장 |
설치가 끝나면 터미널을 완전히 닫고 새로 엽니다(PATH는 새 창부터 반영). 확인:
git --version
node -v # v24.x.x
npm -v
gh --version
Node 설치 프로그램을 nodejs.org에서 직접 받아도 되지만, winget으로 통일하면 나중에 winget upgrade --all 한 줄로 전부 업데이트됩니다. 프로젝트마다 Node 버전을 바꿔야 하면 winget install Schniz.fnm으로 fnm을 쓰세요.
윈도우 설치 실패 1위 원인이 여기입니다. 셸마다 명령이 다릅니다. 아래 표에서 자기 셸의 명령만 복사하세요.
| 지금 열린 창 | 설치 명령 |
|---|---|
PowerShell (프롬프트가 PS로 시작) | irm https://claude.ai/install.ps1 | iex |
| CMD | curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd |
| winget (대안) | winget install Anthropic.ClaudeCode — 단, 자동 업데이트 없음. winget upgrade Anthropic.ClaudeCode 수동 실행 |
맥 가이드에서 본 curl -fsSL ... | bash를 PowerShell에 붙여넣으면 A parameter cannot be found that matches parameter name 'fsSL' 오류가 납니다. PowerShell의 curl은 진짜 curl이 아니라 Invoke-WebRequest의 별칭이기 때문입니다.
PowerShell 설치가 권장인 이유는 백그라운드 자동 업데이트가 되기 때문입니다. 설치 위치는 %USERPROFILE%\.local\bin\claude.exe입니다.
claude --version
# 2.1.xxx (Claude Code)
claude doctor
claude를 못 찾으면 새 터미널을 열어보고, 그래도 안 되면 아래 문제 해결 ①을 보세요.
Git for Windows를 기본 경로(C:\Program Files\Git)에 설치했다면 Claude Code가 자동으로 찾아 Bash 도구를 씁니다. 다른 곳에 설치했다면 %USERPROFILE%\.claude\settings.json에 경로를 알려줍니다.
{
"env": {
"CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
}
}
주의: 반드시 bin\bash.exe여야 합니다. git-bash.exe(런처)를 지정하면 무시됩니다.
mkdir ~\project\hello-claude
cd ~\project\hello-claude
git init
claude
테마 선택 → Claude account with subscription 선택 → 브라우저 로그인 → 폴더 신뢰 확인(Yes) 순서로 진행됩니다. 이후 사용법(/init, 슬래시 명령, 단축키)은 맥 가이드의 7~9단계와 완전히 동일합니다.
리눅스 배포 환경과 동일하게 개발하고, 샌드박스 격리 실행까지 쓰고 싶다면 이쪽입니다.
관리자 권한 PowerShell에서:
wsl --install
이 한 줄이 가상화 기능 활성화 + WSL2 + Ubuntu 설치까지 처리합니다. 재부팅 후 Ubuntu 창이 열리면 리눅스용 사용자 이름과 비밀번호를 만듭니다(윈도우 계정과 별개).
이미 WSL이 있다면 버전만 확인하세요. Claude Code는 WSL1에서 Exec format error로 실행되지 않는 문제가 있어 반드시 WSL2여야 합니다.
wsl -l -v
# VERSION이 1이면:
wsl --set-version Ubuntu 2
WSL 최대의 함정이 여기입니다. WSL은 기본적으로 윈도우 PATH를 이어받기 때문에, WSL 안에서 npm을 치면 윈도우에 설치된 npm(/mnt/c/...)이 실행될 수 있습니다. 이 상태로 npm 글로벌 설치를 하면 exec: node: not found 같은 오류로 이어집니다.
Ubuntu 터미널에서 리눅스용 Node를 nvm으로 설치합니다.
# Ubuntu(WSL) 안에서
sudo apt update && sudo apt install -y git curl build-essential
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install --lts
그리고 반드시 확인합니다.
which node && which npm
# /home/you/.nvm/... 으로 시작해야 정상
# /mnt/c/... 로 시작하면 윈도우 Node가 잡힌 것
/mnt/c가 나온다면 ~/.bashrc 마지막에 nvm 로더가 있는지 확인하고(export NVM_DIR=... 세 줄), 그래도 우선순위가 밀리면 export PATH="(node -v)/bin:$PATH"를 추가합니다. 윈도우 PATH 상속 자체를 끄는 방법(appendWindowsPath = false)은 공식 문서가 권장하지 않습니다 — WSL에서 code ., explorer.exe 같은 윈도우 프로그램 호출이 전부 깨집니다.
WSL 안에서는 맥/리눅스와 동일합니다.
curl -fsSL https://claude.ai/install.sh | bash
echo 'export PATH="HOME/.local/bin:HOME/.local/bin:HOME/.local/bin:PATH"' >> ~/.bashrc
source ~/.bashrc
claude --version
mkdir -p ~/project && cd ~/project
git clone https://github.com/org/repo.git
cd repo && claude
VS Code는 윈도우 쪽에 설치하고, 확장에서 WSL(Remote - WSL)을 설치한 뒤 WSL 터미널에서 code .를 치면 됩니다. 에디터 UI는 윈도우에서, 파일·터미널·Claude Code는 전부 리눅스에서 도는 구성이 완성됩니다.
| 증상 | 원인 → 해결 |
|---|---|
① 'claude' is not recognized / The term 'claude' is not recognized | PATH에 설치 폴더가 없음. 먼저 새 터미널을 열어볼 것(설치한 창은 옛 PATH 유지). 그래도 안 되면 PowerShell에서 [Environment]::SetEnvironmentVariable('PATH', "env:USERPROFILE\.local\bin", 'User') 실행 후 재시작 |
② 'irm' is not recognized | CMD에서 PowerShell 명령을 실행함. PowerShell을 열거나 CMD용 install.cmd 명령 사용 |
③ The token '&&' is not a valid statement separator | PowerShell에서 CMD 명령을 실행함. irm https://claude.ai/install.ps1 | iex 사용 |
④ A parameter cannot be found that matches parameter name 'fsSL' / 'bash' is not recognized | 맥·리눅스 명령을 윈도우에 붙여넣음. PowerShell 설치 명령 사용 |
⑤ running scripts is disabled on this system | PowerShell 실행 정책이 npm의 .ps1 런처를 차단. Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 실행, 또는 npm 대신 PowerShell 설치 방식 사용 |
⑥ Claude Code does not support 32-bit Windows | 시작 메뉴의 Windows PowerShell (x86)을 연 것. x86이 안 붙은 PowerShell로 다시 실행 |
⑦ claude를 쳤는데 데스크톱 앱이 열림 | 구버전 Claude Desktop의 Claude.exe가 PATH 우선순위를 가로챔. Claude Desktop을 최신으로 업데이트 |
⑧ The process cannot access the file ... being used by another process | 이전 설치 잔여물이나 백신이 다운로드 파일을 잡고 있음. Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads" 후 재설치 |
⑨ 설치 시 TLS/SSL 오류 (Could not establish trust relationship, CRYPT_E_NO_REVOCATION_CHECK) | 회사 프록시의 TLS 검사. IT팀에 프록시 CA 인증서를 윈도우 인증서 저장소에 추가 요청. 설치 후에는 NODE_EXTRA_CA_CERTS 환경변수에 CA 파일 경로 지정. CMD의 curl 오류는 --ssl-revoke-best-effort 플래그 추가 |
⑩ WSL에서 cannot execute binary file: Exec format error | WSL1임. wsl --set-version Ubuntu 2로 WSL2 전환 |
⑪ WSL에서 exec: node: not found | 윈도우 Node가 PATH에 끼어듦. B-2대로 리눅스 Node 설치 후 which node가 /home/...인지 확인 |
| ⑫ Claude Code가 너무 느림 (WSL) | 프로젝트가 /mnt/c/...에 있음. ~/project로 옮기면 해결. 네이티브에서 느리면 Windows Defender 예외에 프로젝트 폴더와 %USERPROFILE%\.local 추가를 IT팀과 상의 |
여기 없는 오류는 claude doctor 출력과 함께 공식 문제 해결 페이지에서 오류 메시지로 찾으세요. 증상→해결 표로 정리되어 있습니다.
터미널 없이 쓰는 방법도 있습니다. Claude Code 데스크톱 앱은 GUI로 폴더를 열어 바로 시작할 수 있고, 설치 과정의 셸 문제를 전부 건너뜁니다. 다만 프로젝트가 Node를 쓴다면 결국 A-1의 도구 설치는 필요하므로, 이 글의 순서대로 환경을 갖춘 뒤 앱을 얹는 것을 권합니다.
윈도우에서 Claude Code가 어렵다는 말의 실체는 대부분 이 세 가지입니다. 셸에 맞지 않는 설치 명령, PATH 미반영(새 터미널 안 열기), WSL과 윈도우의 경계 섞기. 이 글의 순서 — 갈림길 결정 → winget/nvm으로 도구 설치 → 자기 셸의 명령으로 설치 → 새 터미널에서 확인 — 만 지키면 맥과 다를 것 없이 동작합니다.
설치가 끝난 뒤의 사용법은 OS와 무관하니, 맥에서 Claude Code 시작하기의 /init·슬래시 명령·단축키 부분을 이어서 보시면 됩니다.
