클로드 코드(Claude Code) Windows 설치: PowerShell 한 줄·오류 6가지

Windows 11 테스트 환경에서 claude --version을 쳤더니 2.1.150 (Claude Code)가 나왔습니다. 그런데 %USERPROFILE%\.local\bin에는 예전에 네이티브로 깐 2.1.81이 그대로 남아 있었어요.

그 폴더가 PATH에 없어서, claude를 치면 나중에 npm으로 깐 쪽이 실행되고 있었던 거죠. claude --version은 숫자만 보여 줄 뿐 어느 설치본인지는 말해 주지 않거든요.

클로드 코드(Claude Code)는 Anthropic이 만든 터미널용 코딩 에이전트입니다. 프로젝트 폴더에서 말로 작업을 시키면 파일을 읽고 고치고 명령을 실행하죠.

설치 자체는 어렵지 않습니다. 64비트 PowerShell에서 irm https://claude.ai/install.ps1 | iex를 실행하고, 새 창에서 claude --version으로 확인한 뒤, 프로젝트 폴더에서 claude를 실행해 브라우저로 로그인하면 바로 일을 시킬 수 있어요. 관리자 권한도 WSL도 필요 없습니다.

다만 무료 플랜으로는 쓸 수 없고 Claude Pro 이상 구독이나 Console(API) 계정이 있어야 합니다.

막히는 곳은 대개 그다음입니다. 어느 셸에서 쳤는지, PATH에 들어갔는지, 설치본이 둘인지. 그래서 설치 순서와 함께 그런 곳을 오류 문구별로 모아 뒀습니다.

2026년 9월 8일 Windows 11 · Windows PowerShell 5.1 테스트 환경에서 직접 실행한 결과이고, 9월 28일과 10월 16일에 같은 환경에서 버전과 진단 결과를 다시 확인했습니다. 실행 결과는 네이티브와 npm 설치본의 것이고, WinGet·CMD 설치와 요구사항은 공식 문서 기준입니다.

설치 전에 볼 것: 계정, WSL, Git

Windows 10 1809 이상, RAM 4GB 이상(x64 또는 ARM64), 인터넷 연결이면 설치할 수 있습니다. 실제로 걸리는 건 대개 계정이에요.

무료 Claude.ai 플랜에는 Claude Code가 들어 있지 않습니다. Pro·Max·Team·Enterprise 구독이나 선불 크레딧을 넣은 Claude Console 계정이 필요하고, 없으면 설치는 돼도 로그인에서 멈춥니다. 요금은 Claude 요금 페이지에서 확인하세요.

WSL은 필요 없습니다. Claude Code는 Windows에서 바로 돕니다. 단, 명령 실행을 격리하는 샌드박스는 WSL 2에서만 됩니다(WSL 1은 지원하지 않음).

Git for Windows도 없어도 돼요. 있으면 Claude Code가 셸 명령을 Git Bash로, 없으면 PowerShell로 실행하니 나중에 깔아도 됩니다.

설치 방법은 넷인데, 특별한 이유가 없다면 저는 첫 줄을 권합니다.

방법	명령	업데이트
네이티브(PowerShell)	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	기본은 수동
npm	npm install -g @anthropic-ai/claude-code	v2.1.198부터 Node.js 22 이상

Node.js가 이미 있다면 npm으로 깔아도 됩니다. 그래도 제가 네이티브를 권하는 이유가 있어요.

npm 설치본은 PowerShell 실행 정책에 걸릴 수 있고(아래 오류 4번), 관리자 PowerShell로 전역 설치하면 권한 문제가 생깁니다. 무엇보다 두 방식을 함께 깔면 어느 쪽이 실행되는지 헷갈리는데, 테스트 환경이 실제로 그 상태였습니다(오류 6번).

설치에서 첫 작업까지

1. 64비트 PowerShell을 엽니다

Win + X를 누르고 Windows PowerShell 또는 터미널을 엽니다. 프롬프트 앞에 PS가 있어야 해요.

PS C:\Users\YourName>    ← PowerShell
C:\Users\YourName>       ← CMD

시작 메뉴의 Windows PowerShell (x86)은 32비트라서 Claude Code가 돌지 않습니다. (x86)이 없는 쪽을 여세요.

2. 설치 명령 한 줄을 실행합니다

관리자 권한 없이 그대로 붙여 넣고 Enter를 누릅니다.

irm https://claude.ai/install.ps1 | iex

irm이 설치 스크립트를 내려받고 iex가 실행합니다. 끝나면 Claude Code successfully installed!가 나오고, 실행 파일은 %USERPROFILE%\.local\bin\claude.exe에 놓이며 이 폴더가 PATH에 자동으로 추가됩니다.

3. 새 창에서 버전을 확인합니다

설치 전에 열어 둔 창은 바뀐 PATH를 모릅니다. 창을 새로 열고 확인하세요.

claude --version

2.1.150 (Claude Code)

숫자 (Claude Code) 모양이면 정상입니다. 최신인지 궁금하면 npm에 올라온 버전과 비교하면 돼요. 9월 28일과 10월 16일에 다시 확인했을 때는 이랬습니다.

확인	9월 28일	10월 16일
설치본 claude --version	2.1.281	2.1.296
최신 npm view @anthropic-ai/claude-code version	2.1.283	2.1.301

설치 경로나 설정이 의심되면 claude doctor를 실행합니다. 9월 28일(2.1.281)에는 결과가 터미널에서 직접 실행해야 보이고 파이프로 넘기면 아무것도 출력하지 않았는데, 10월 16일 2.1.296에서는 claude doctor | Out-String으로 받아도 결과가 그대로 나왔고 종료 코드는 0이었습니다(설정에 따라 달라지는 줄은 줄였습니다).

Claude Code doctor

Running: npm-global (2.1.296)
Platform: win32-x64
Config install method: global
Search: OK (bundled)
…
No installation issues found.

이 명령은 현재 폴더의 .mcp.json에 적힌 서버를 실제로 띄워 점검하므로 믿을 수 있는 폴더에서만 실행하세요.

4. 프로젝트 폴더에서 claude를 실행해 로그인합니다

cd C:\Users\YourName\projects\my-app
claude

첫 실행이면 브라우저가 열립니다. Claude 계정으로 로그인하고 허용을 누르면 터미널에 Login successful이 뜹니다.

• 브라우저가 안 열리면 터미널에서 c를 눌러 로그인 URL을 복사합니다.
• 브라우저가 코드를 보여 주면 터미널의 Paste code here if prompted 자리에 붙여 넣습니다.
• 인증 정보는 %USERPROFILE%\.claude\.credentials.json에 저장됩니다. 남과 공유하거나 저장소에 커밋하지 마세요.
• 계정을 바꿀 때는 세션 안에서 /login, 로그아웃은 /logout입니다.

환경 변수 ANTHROPIC_API_KEY가 있으면 그 키를 쓸지 한 번 묻습니다. 여기서 승인하면 구독이 있어도 API 키가 우선해요. 구독으로 쓰려는데 API 요금이 나간다면 이 변수부터 지우세요.

5. 코드를 바꾸지 않는 질문으로 시작합니다

로그인이 끝나면 같은 창에서 바로 대화가 시작됩니다. 처음엔 “이 프로젝트가 뭐 하는 건지 설명해 줘”처럼 읽기만 하는 질문이 좋습니다. 그다음 “README에 설치 방법 절을 추가해 줘” 같은 작은 수정을 시키면, 파일을 고치기 전에 바뀔 내용을 보여 주고 승인을 받아요.

권한 방식은 이 정도만 알아 두면 됩니다.

• Pro·Max·Team 플랜의 대화형 세션은 Auto 모드로 시작해, 위험도 낮은 작업은 알아서 하고 위험한 작업만 묻습니다. 다른 플랜은 매번 묻는 모드로 시작합니다.
• Shift+Tab으로 언제든 모드를 바꿉니다.
• 파일을 아예 건드리지 않게 하려면 claude --permission-mode plan으로 시작합니다.

claude                      # 대화형 세션 시작
claude "테스트 코드를 정리해 줘"   # 첫 지시를 함께 넘김
claude -p "이 폴더를 한 문장으로 설명해 줘"   # 결과만 출력하고 종료 (스크립트용)

-p는 폴더 신뢰 확인 창을 건너뛰므로 믿을 수 있는 폴더에서만 씁니다. 세션 안에서는 /help(명령 목록), /clear(대화 초기화), /exit(종료)를 씁니다.

Windows PowerShell 5.1에서 claude -p 결과를 변수로 받거나 한글을 파이프로 넘길 때 글자가 깨진다면 PowerShell 인코딩 문제이고, 프로필 네 줄로 한글 깨짐을 고치는 방법에 해결법이 있습니다.

Git Bash를 쓰는데 Claude Code가 Bash를 못 찾는다면(Git을 기본 위치 C:\Program Files\Git가 아닌 곳에 깐 경우) %USERPROFILE%\.claude\settings.json에 경로를 적습니다. JSON이라 역슬래시를 두 번씩 써요.

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Windows에서 자주 막히는 곳

1~5번은 오류 문구를 그대로 검색해 오신 분을 위한 것이고, 6번은 테스트 환경에서 실제로 겪은 상황입니다.

1. ‘claude’ is not recognized as the name of a cmdlet

%USERPROFILE%\.local\bin이 PATH에 없거나, 설치 후 창을 새로 열지 않은 경우입니다. 먼저 새 창을 열어 보세요. 그래도 같으면 PATH에 있는지 보고, 없으면 사용자 PATH에 추가한 뒤 창을 다시 엽니다.

$env:PATH -split ';' | Select-String '\.local\\bin'
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

첫 줄에서 결과가 나오면 이미 등록된 것이니 아래 두 줄은 실행하지 않아도 됩니다.

2. ‘irm’ is not recognized as an internal or external command

CMD에서 PowerShell용 명령을 실행하면 이렇게 나옵니다. PowerShell을 열어 다시 실행하거나, 위 표의 CMD용 명령을 쓰면 됩니다.

3. The token ‘&&’ is not a valid statement separator

반대로 PowerShell에서 CMD용 명령을 실행한 경우예요. Windows PowerShell 5.1에는 &&가 없거든요. PowerShell용 한 줄을 쓰면 됩니다.

macOS·Linux용 curl -fsSL ... | bash를 붙여 넣었을 때 나는 'bash' is not recognized나 A parameter cannot be found that matches parameter name 'fsSL'도 같은 원인입니다.

4. running scripts is disabled on this system (PSSecurityException)

npm 설치본이 만드는 claude.ps1이 실행 정책에 막힌 경우입니다. 9월 28일과 10월 16일에 Get-Command claude -All을 보니 두 번 다 claude.ps1 → claude.cmd → claude 순이었는데, PowerShell은 이 중 .ps1을 먼저 실행해요. 네이티브 설치는 이 정책과 상관없습니다.

고치는 방법은 아래 중 하나를 고르면 됩니다.

• Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser로 현재 사용자의 정책을 바꿉니다.
• claude 대신 claude.cmd로 실행합니다.
• 네이티브 설치로 갈아탑니다.

현재 정책은 Get-ExecutionPolicy -List로 봅니다. 테스트 환경은 CurrentUser가 이미 RemoteSigned라 npm 설치본도 그대로 실행됐습니다.

5. Claude Code does not support 32-bit Windows

64비트 Windows에서 Windows PowerShell (x86) 창을 열면 이 문구가 나옵니다. (x86)이 붙지 않은 Windows PowerShell이나 터미널 앱을 여세요.

설치 스크립트(install.ps1)를 실행하지 않고 내용만 받아 보니, 이 문구는 Windows가 아니라 지금 도는 PowerShell 프로세스가 64비트인지([Environment]::Is64BitProcess)를 보고 냅니다. 같은 64비트 Windows에서 C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe(x86 창)로 이 값을 찍으면 False, System32 쪽 PowerShell에서는 True였어요. Windows가 64비트여도 x86 창이면 막히는 이유입니다.

6. 설치본이 두 개라 어느 쪽이 실행되는지 모를 때

맨 앞에 적은 상황입니다. 예전에 네이티브로 깐 2.1.81이 .local\bin에 남아 있었고, 나중에 npm으로 깐 2.1.150이 %APPDATA%\npm에 있었습니다.

.local\bin이 PATH에 없어서 claude를 치면 npm 쪽이 실행됐고요. 아래 세 줄로 확인했습니다.

Get-Command claude -All | Select-Object Source
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
& "$env:USERPROFILE\.local\bin\claude.exe" --version

C:\Users\YourName\AppData\Roaming\npm\claude.ps1
C:\Users\YourName\AppData\Roaming\npm\claude.cmd
C:\Users\YourName\AppData\Roaming\npm\claude
True
2.1.81 (Claude Code)

해결은 하나만 남기는 겁니다. 공식 권장은 네이티브예요. npm 쪽은 npm uninstall -g @anthropic-ai/claude-code로, 네이티브 쪽은 아래 삭제 명령으로 지웁니다.

Claude Desktop 앱이 claude 명령을 가로채는 경우도 보고돼 있는데, 그때는 Desktop 앱을 최신으로 올리면 됩니다.

npm으로 설치한 뒤 claude가 claude.exe의 버전이 실행 중인 Windows 버전과 호환되지 않습니다로 실패한다면 실행 파일 자리에 자리표시자만 남은 경우일 수 있습니다. 파일 크기로 가르는 법은 설치 단계별 오류 해결의 Windows 절에 직접 재현한 출력과 함께 있습니다.

업데이트와 삭제

명령은 설치 방식마다 다릅니다.

설치 방식	업데이트	삭제
네이티브	자동, 바로 하려면 claude update	아래 두 줄
WinGet	winget upgrade Anthropic.ClaudeCode	winget uninstall Anthropic.ClaudeCode
npm	npm install -g @anthropic-ai/claude-code@latest	npm uninstall -g @anthropic-ai/claude-code

npm 설치본에 npm update -g는 쓰지 마세요. 처음 설치할 때의 버전 범위를 따르기 때문에 최신 릴리스로 올라가지 않을 수 있습니다. 올렸는데 버전이 그대로라면 설치 방식별 업데이트 명령과 안 될 때 보는 순서를 보세요.

네이티브 설치본을 지우는 PowerShell 명령입니다.

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

설치하면 생기는 자리는 실행 파일 %USERPROFILE%\.local\bin\claude.exe, 버전 파일 %USERPROFILE%\.local\share\claude\versions, 설정과 인증 정보 %USERPROFILE%\.claude입니다.

어느 방식으로 지우든 설정과 인증 정보가 든 %USERPROFILE%\.claude 폴더는 남으니, 완전히 지우려면 그 폴더도 따로 지워야 합니다.

마치며

설치 명령은 한 줄인데, 막히는 곳은 대개 그 뒤였습니다. PATH, 셸 착각(PowerShell·CMD·x86), 설치본 중복이요. 그중 설치본 중복은 오류 하나 없이 엉뚱한 쪽이 돌고 있어서 문제가 있다는 것조차 알아채기 어렵습니다.

그래서 저는 설치를 마치면 새 창에서 claude --version과 함께 Get-Command claude -All도 한 번 쳐 보길 권합니다. 구독으로 쓸 생각이라면 셸에 ANTHROPIC_API_KEY가 남아 있지 않은지도 같이 보시고요.

그다음엔 작업할 프로젝트 루트에 CLAUDE.md를 만들어 빌드·테스트 명령과 지켜야 할 규칙을 적어 두세요. 무엇을 적어야 효과가 있는지는 CLAUDE.md 작성법에 예제와 함께 있습니다.