Claude Code Windows 설치 방법: PowerShell 설정부터 첫 작업까지

한 줄 결론: Windows PowerShell에서 irm https://claude.ai/install.ps1 | iex 한 줄을 실행하면 Claude Code가 설치되고, claude --version으로 확인한 뒤 프로젝트 폴더에서 claude를 실행해 브라우저로 로그인하면 바로 첫 작업을 시킬 수 있습니다. 무료 플랜으로는 쓸 수 없고 Pro 이상 구독(또는 Console API) 계정이 필요합니다.

3줄 요약:

• 설치는 PowerShell 한 줄이며 관리자 권한이 필요 없습니다. Windows 10 1809 이상, 4GB RAM 이상이면 됩니다.
• 로그인은 claude 실행 후 열리는 브라우저에서 하며, 인증 정보는 %USERPROFILE%\.claude\.credentials.json에 저장됩니다.
• Windows에서 막히는 지점은 거의 정해져 있습니다. PATH 미등록, PowerShell과 CMD 혼동, 설치본 중복. 아래 오류 절에 증상별 해결 순서를 적었습니다.

이 글은 2026년 9월 8일에 Windows 11 Pro(빌드 26200), Windows PowerShell 5.1 환경에서 직접 확인한 내용입니다. 명령 출력은 이 PC에서 실행한 결과를 그대로 옮겼고, 설치 명령과 요구사항은 Anthropic 공식 문서를 같은 날 다시 확인했습니다. Claude Code는 Anthropic이 만든 터미널용 코딩 에이전트로, 프로젝트 폴더에서 자연어로 작업을 지시하면 파일을 읽고 고치고 명령을 실행합니다. 참고로 이 사이트(빅베어로그)의 코드도 Claude Code로 만들었습니다.

설치 전에 확인할 것: 요구사항과 계정

공식 문서 기준 최소 요구사항은 다음과 같습니다.

항목	요구사항
운영체제	Windows 10 버전 1809 이상 또는 Windows Server 2019 이상
하드웨어	4GB 이상 RAM, x64 또는 ARM64
네트워크	인터넷 연결 필수
셸	PowerShell 또는 CMD (Git for Windows를 설치하면 Bash 도구도 사용)
계정	Claude Pro, Max, Team, Enterprise 구독 또는 Claude Console(API) 계정

두 가지를 먼저 확인하세요.

1. 계정: 공식 문서는 “무료 Claude.ai 플랜에는 Claude Code 접근이 포함되지 않는다”고 명시합니다. 구독이 없다면 설치해도 로그인 단계에서 멈춥니다. 요금은 바뀌므로 금액은 적지 않겠습니다. Claude 요금 페이지에서 현재 가격을 확인하세요.
2. Git for Windows: 필수는 아닙니다. 설치하면 Claude Code가 Bash 도구를 쓸 수 있고, 없으면 PowerShell을 셸 도구로 사용합니다. 나중에 깔아도 되니 지금은 건너뛰어도 됩니다.

WSL은 필요 없습니다. Claude Code는 Windows에서 네이티브로 실행됩니다. 다만 샌드박스 명령 실행은 네이티브 Windows에서 지원되지 않고 WSL 2에서만 됩니다. 이 글은 네이티브 기준입니다.

PowerShell인지 CMD인지 먼저 확인하기

Windows 설치 실패의 절반은 셸을 착각해서 생깁니다. Win + X를 누르고 Windows PowerShell 또는 터미널을 여세요. 프롬프트 앞에 PS가 붙어 있으면 PowerShell입니다.

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

공식 문서가 정리한 구분법도 같습니다. 'irm' is not recognized가 나오면 CMD에서 PowerShell 명령을 실행한 것이고, The token '&&' is not a valid statement separator가 나오면 PowerShell에서 CMD 명령을 실행한 것입니다.

한 가지 더, 시작 메뉴에 Windows PowerShell (x86) 항목이 따로 있는데 이건 32비트입니다. Claude Code는 32비트를 지원하지 않으므로 (x86)이 없는 쪽을 여세요.

설치: PowerShell 한 줄이면 끝납니다

공식 문서가 “권장(Recommended)“으로 표시한 방법은 네이티브 설치입니다. PowerShell에 아래 한 줄을 붙여 넣고 Enter를 누르세요. 관리자 권한은 필요 없습니다.

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

irm(Invoke-RestMethod)이 설치 스크립트를 내려받고 iex(Invoke-Expression)가 실행합니다. 끝나면 Claude Code successfully installed! 메시지가 나옵니다. 설치 파일은 %USERPROFILE%\.local\bin\claude.exe에 놓이고, 이 경로가 PATH에 자동으로 추가됩니다. 네이티브 설치본은 백그라운드에서 자동 업데이트됩니다.

다른 방법도 있습니다. 상황에 맞는 것을 하나만 고르세요.

방법	명령	특징
네이티브 (PowerShell)	irm https://claude.ai/install.ps1 | iex	공식 권장, 자동 업데이트
네이티브 (CMD)	curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd	CMD 사용자용
WinGet	winget install Anthropic.ClaudeCode	자동 업데이트 안 됨, winget upgrade로 갱신
npm	npm install -g @anthropic-ai/claude-code	v2.1.198부터 Node.js 22 이상 필요

npm 방식을 쓸 때 sudo나 관리자 PowerShell로 전역 설치하지 마세요. 권한 문제가 생깁니다. 그리고 두 방식을 함께 깔면 어느 쪽이 실행되는지 헷갈리는 문제가 생기는데, 이 PC가 정확히 그 상태였습니다. 아래 오류 절의 6번에서 다룹니다.

설치 확인: claude –version과 claude doctor

새 PowerShell 창을 열고(기존 창은 PATH 변경을 모릅니다) 버전을 확인합니다.

claude --version

이 PC의 실제 출력입니다.

2.1.150 (Claude Code)

숫자는 다르겠지만 숫자 (Claude Code) 형태면 정상입니다. 공식 문서는 claude doctor로 설치 경로와 설정 진단을 볼 수 있다고 안내합니다. 진단은 터미널에서 직접 실행할 때만 표시되고, 파이프로 넘기면 아무것도 출력하지 않았습니다. claude doctor는 현재 폴더의 .mcp.json에 적힌 서버를 실제로 띄워 점검하므로 신뢰하는 폴더에서만 실행하세요.

로그인: 브라우저 인증과 계정 선택

프로젝트 폴더로 이동한 뒤 claude를 실행하면 첫 실행에서 로그인 절차가 시작됩니다.

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

브라우저가 열리면 Claude 계정으로 로그인하고 허용을 누릅니다. 공식 문서에 적힌 세부 동작은 다음과 같습니다.

• 브라우저가 자동으로 열리지 않으면 터미널에서 c를 눌러 로그인 URL을 클립보드에 복사할 수 있습니다.
• 브라우저가 터미널로 돌아오지 못하고 코드를 보여 주면, 터미널의 Paste code here if prompted 프롬프트에 그 코드를 붙여 넣습니다.
• 성공하면 터미널에 Login successful이 표시됩니다.
• Windows에서 인증 정보는 %USERPROFILE%\.claude\.credentials.json에 저장되며 사용자 프로필 폴더의 접근 권한을 따릅니다. 이 파일을 다른 사람과 공유하거나 저장소에 커밋하면 안 됩니다.
• 계정을 바꾸려면 세션 안에서 /login, 완전히 지우려면 /logout을 입력합니다.

환경 변수 ANTHROPIC_API_KEY가 설정돼 있으면 브라우저 대신 그 키를 승인할지 한 번 묻고, 구독이 있어도 승인된 API 키가 우선합니다. 구독으로 쓰려는데 요금이 API로 청구된다면 이 변수를 확인하세요.

첫 작업 시키기: 프로젝트 폴더에서 claude 실행

로그인이 끝나면 같은 창에서 바로 대화형 세션이 시작됩니다. 공식 퀵스타트가 권하는 첫 질문은 코드를 바꾸지 않는 것입니다.

what does this project do?

한국어로 물어도 됩니다. “이 프로젝트가 뭐 하는 건지 설명해 줘”처럼 쓰면 폴더의 파일을 읽고 요약합니다. 그다음에 작은 수정을 시켜 보세요. 예를 들어 “README에 설치 방법 절을 추가해 줘”라고 하면 파일을 고치기 전에 변경 내용을 보여 주고 승인을 받습니다.

권한 방식은 알아 두는 게 좋습니다.

• Pro, Max, Team 플랜의 대화형 세션은 Auto 모드로 시작합니다. 위험도가 낮은 작업은 자동으로 진행하고 위험한 작업만 묻습니다. 다른 플랜은 매번 묻는 수동 모드로 시작합니다.
• Shift+Tab을 누르면 언제든 모드를 바꿀 수 있습니다.
• 파일을 절대 건드리지 않게 하려면 claude --permission-mode plan으로 시작하세요. 계획만 세우고 실행하지 않습니다.

자주 쓰는 실행 형태는 세 가지입니다.

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

-p(print) 모드는 작업 공간 신뢰 확인 창을 건너뛰므로 신뢰하는 폴더에서만 쓰세요. 세션 안에서는 /help로 명령 목록을, /clear로 대화 초기화를, /exit로 종료를 할 수 있습니다.

Git for Windows를 깔면 무엇이 달라지나

Claude Code는 셸 명령을 실행할 때 Bash 도구 또는 PowerShell 도구를 씁니다. Git for Windows가 있으면 Git Bash를 통해 Bash 도구를 사용하고, 없으면 PowerShell 도구를 사용합니다. 이 PC에는 Git 2.53이 C:\Program Files\Git에 설치돼 있어 Bash 도구가 동작합니다.

Git을 설치할 때 “Adjusting your PATH environment” 화면이 나오면 기본 권장 옵션을 그대로 두세요. Git을 다른 위치에 설치했거나 Claude Code가 Bash를 찾지 못하면 %USERPROFILE%\.claude\settings.json에 경로를 직접 적어 줄 수 있습니다.

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

실제 Git 위치는 PowerShell에서 Get-Command git | Select-Object Source로 확인합니다.

Windows에서 자주 나는 오류 6가지

증상, 원인, 해결 순서로 적었습니다. 이 중 6번은 이 PC에서 실제로 겪은 상황이고, 1번은 이 PC의 PATH에 .localin이 없는 것을 직접 확인한 뒤 공식 문서의 해결 절차를 옮긴 것입니다.

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

원인: 설치 폴더 %USERPROFILE%\.local\bin이 PATH에 없거나, 설치 후 PowerShell 창을 새로 열지 않았습니다.

해결: 먼저 새 창을 엽니다. 그래도 같다면 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용 명령(curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd)을 쓰세요.

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

원인: PowerShell에서 CMD용 명령을 실행했습니다. Windows PowerShell 5.1에는 &&가 없습니다.

해결: PowerShell용 한 줄 명령을 쓰세요. macOS·Linux용 curl -fsSL ... | bash를 PowerShell에 붙여 넣으면 '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 실행 스크립트가 PowerShell 실행 정책에 막힌 것입니다. irm ... | iex 네이티브 설치는 스크립트 파일이 아니라 이 정책의 영향을 받지 않습니다.

해결: 셋 중 하나를 고르세요.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

또는 claude 대신 claude.cmd로 실행하거나, 네이티브 설치로 갈아탑니다. 이 PC는 CurrentUser 정책이 RemoteSigned라 npm 설치본도 문제없이 실행됐습니다. 현재 정책은 Get-ExecutionPolicy -List로 볼 수 있습니다.

5. Claude Code does not support 32-bit Windows

원인: 64비트 Windows인데 Windows PowerShell (x86) 창을 열었습니다.

해결: (x86)이 붙지 않은 Windows PowerShell 또는 터미널 앱을 여세요.

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

이 PC의 실제 상황입니다. 예전에 네이티브로 설치한 2.1.81이 %USERPROFILE%\.local\bin\claude.exe에 남아 있고, 나중에 npm으로 설치한 2.1.150이 %APPDATA%\npm\claude.ps1로 잡혀 있었습니다. .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 앱을 최신으로 업데이트하라는 것이 공식 안내입니다.

업데이트와 삭제

네이티브 설치본은 자동으로 업데이트되고, 수동으로 확인하려면 claude update를 실행합니다. WinGet 설치본은 winget upgrade Anthropic.ClaudeCode, npm 설치본은 npm update -g @anthropic-ai/claude-code로 갱신합니다.

네이티브 설치본을 삭제하는 PowerShell 명령은 다음과 같습니다.

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

WinGet은 winget uninstall Anthropic.ClaudeCode, npm은 npm uninstall -g @anthropic-ai/claude-code입니다. 설정과 인증 정보가 든 %USERPROFILE%\.claude 폴더는 삭제 명령에 포함되지 않으니 완전히 지우려면 따로 지우세요.

자주 묻는 질문

WSL을 꼭 설치해야 하나요

아닙니다. Windows 10 1809 이상이면 네이티브로 실행됩니다. 샌드박스 명령 실행이나 Linux 전용 도구가 필요할 때만 WSL 2를 고려하면 됩니다. WSL 1은 지원되지 않습니다.

무료 플랜으로 쓸 수 있나요

공식 문서 기준으로 무료 Claude.ai 플랜은 Claude Code를 쓸 수 없습니다. Pro, Max, Team, Enterprise 구독이나 선불 크레딧을 넣은 Claude Console 계정이 필요합니다.

npm으로 설치해도 되나요

됩니다. 다만 v2.1.198부터 Node.js 22 이상이 필요하고, 실행 정책 오류(4번)가 날 수 있으며, 공식 권장은 네이티브 설치입니다. 이미 npm으로 쓰고 있다면 그대로 써도 문제는 없습니다.

관리자 권한이 필요한가요

네이티브 설치는 필요 없습니다. 사용자 프로필 폴더 아래에 설치되기 때문입니다. npm 전역 설치도 관리자 권한 없이 하는 것이 맞습니다.

설치 후 어디에 무엇이 생기나요

실행 파일은 %USERPROFILE%\.local\bin\claude.exe, 버전 파일은 %USERPROFILE%\.local\share\claude\versions, 설정과 인증 정보는 %USERPROFILE%\.claude 아래에 생깁니다. 프로젝트별 규칙은 프로젝트 루트의 CLAUDE.md에 적습니다.

참고한 공식 자료

• Claude Code 고급 설정(Advanced setup) — 요구사항, Windows 설치 방법 4가지, 업데이트·삭제 (확인일 2026-09-08)
• Claude Code 퀵스타트 — 첫 로그인, 권한 모드, 첫 질문 예시 (확인일 2026-09-08)
• 터미널 가이드(Terminal guide for new users) — PowerShell·CMD 구분, PATH 등록 명령 (확인일 2026-09-08)
• 인증(Authentication) — 로그인 절차, 인증 정보 저장 위치, API 키 우선순위 (확인일 2026-09-08)
• 설치·로그인 문제 해결 — 오류 메시지별 해결 표 (확인일 2026-09-08)

공식 문서 페이지에는 최종 수정일이 표시되지 않아 확인일을 기준으로 적었습니다. 한국어 번역 문서(code.claude.com/docs/ko/setup)도 있지만 영어 원문보다 갱신이 늦어 이 글은 영어 문서를 기준으로 했습니다.

다음에 할 일

설치가 끝났다면 프로젝트 루트에 CLAUDE.md를 만들어 규칙을 적는 것이 다음 순서입니다. 무엇을 적어야 효과가 있는지, 이 사이트를 만들 때 실제로 쓴 규칙 파일을 예로 다음 글에서 정리하겠습니다.