Claude Code Windows 설치 오류 해결: PowerShell 명령부터 PATH까지

PowerShell에 irm https://claude.ai/install.ps1 | iex를 붙여 넣었는데 빨간 글씨만 잔뜩 나왔다면, 대부분은 공식 문서에 이미 나와 있는 경우입니다. 메시지를 그대로 찾아서 맞는 명령 하나만 다시 실행하면 풀려요. 이 글은 Windows에서 Claude Code CLI를 설치하다 나는 오류를 메시지별로 모으고 원인과 다시 실행할 명령을 붙였습니다.

9월 가톨릭대 이틀 부트캠프에서 코딩을 처음 해 보는 대학생 60여 명에게 Codex 데스크톱 앱만 쓰도록 안내했습니다. 학생들이 가장 많이 막힌 곳은 코딩이 아니라 설치였고, Windows PC에서 특히 많이 막혔어요. 그때 설치한 건 Claude Code가 아니라 Codex 앱이었지만, 처음 쓰는 사람에게 Windows 설치가 첫 고비라는 점은 Claude Code도 같습니다.

설치 전체 흐름(Mac·Linux 포함, 로그인과 첫 실행)은 Claude Code 설치 방법에 있고, 이 글은 Windows에서 막힌 경우만 다룹니다. 인용한 공식 문서는 2026년 10월 8일에 원문으로 다시 확인했습니다.

설치 전에 세 가지만 확인

1. 64비트 Windows인가. Claude Code는 Windows 10 1809 이상 또는 Windows Server 2019 이상에서 돌아가고, 64비트 운영체제가 필요합니다. 메모리는 4GB 이상, 프로세서는 x64나 ARM64입니다.

2. 유료 계정이 있는가. Pro, Max, Team, Enterprise 또는 Console 계정이 필요합니다. 무료 Claude.ai 플랜에는 Claude Code가 포함되지 않습니다. 무료 플랜이면 설치는 되는데 로그인에서 막혀요.

3. 지금 연 창이 PowerShell인가 CMD인가. 둘은 비슷해 보이지만 설치 명령이 다릅니다. 줄 앞이 PS C:\Users\이름>이면 PowerShell, PS 없이 C:\Users\이름>이면 CMD입니다. 터미널 안내 문서는 Win + X를 누르고 Windows PowerShell(또는 Terminal)을 고르라고 안내합니다. 관리자 권한으로 열 필요는 없습니다.

셸별 설치 명령

PowerShell 명령에서 irm은 설치 파일을 받아 오고 iex는 받은 내용을 실행합니다. 설치가 끝나면 "Claude Code successfully installed!"가 보입니다. 그다음 창을 새로 열고 버전을 확인하세요.

claude --version

2.1.211 (Claude Code)처럼 버전 번호가 나오면 설치는 끝난 겁니다. 설치에 쓴 창은 예전 PATH(프로그램 위치 목록)를 그대로 들고 있어서, 같은 창에서는 claude를 못 찾을 수 있어요.

증상별로 찾기

공식 문서의 메시지는 영어 기준입니다. PowerShell 버전과 시스템 언어에 따라 문구가 달라질 수 있으니 비슷한 줄을 찾으세요. 처음 설치할 때 만나는 순서대로 놓았습니다.

아래에서 해결 명령을 순서대로 적었습니다.

명령이 아예 안 먹힐 때: 셸을 잘못 고른 경우

표의 위쪽 다섯 줄은 모두 다른 셸이나 다른 운영체제용 명령을 붙여 넣어서 생깁니다. 설치 페이지에 명령이 여러 개 나란히 있어서 처음엔 자주 헷갈리는 부분이에요.

CMD에서 irm을 못 찾는다고 나오면 방법이 두 가지입니다. 시작 메뉴에서 "PowerShell"을 검색해 열고 PowerShell 명령을 실행하거나, CMD에 그대로 있으면서 CMD 명령을 실행합니다.

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

PowerShell에서 curl이 -fsSL을 모른다고 나오는 건 PowerShell 안의 curl이 실제 curl 프로그램이 아니라 Invoke-WebRequest의 별칭이기 때문입니다. Mac용 명령을 고칠 필요 없이 PowerShell 명령으로 바꾸면 됩니다.

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

32비트 오류는 64비트 PC에서도 나옵니다. 시작 메뉴에 Windows PowerShell과 Windows PowerShell (x86) 두 개가 있는데, x86 쪽은 32비트로 실행되거든요. 오류가 난 창에서 다음을 입력해 보세요.

[Environment]::Is64BitOperatingSystem

True가 나오면 운영체제는 문제가 없습니다. 창을 닫고 x86이 없는 Windows PowerShell을 열어 다시 설치합니다. False가 나오면 32비트 Windows라서 Claude Code를 설치할 수 없습니다.

설치 도중 오류: 네트워크·보안 설정

웹 페이지가 돌아온 경우. PowerShell이 HTML 태그나 CSS를 인용하며 파싱 오류를 내면 설치 주소가 스크립트 대신 웹 페이지를 보낸 겁니다. 페이지에 "App unavailable in region"이 보이면 Claude Code를 쓸 수 없는 국가에서 접속한 것이고, 지원 국가 목록을 확인해야 합니다. 그렇지 않다면 일시적인 문제일 수 있으니 몇 분 뒤 다시 해 보고 안 되면 WinGet으로 설치합니다. -OutFile install.ps1로 파일을 받아도 같은 웹 페이지가 저장되니 도움이 안 됩니다.

winget install Anthropic.ClaudeCode

서버에 닿는지 확인하기. 공식 문서의 연결 확인 명령입니다. PowerShell의 curl은 별칭이라 curl.exe로 정확히 적어야 합니다.

curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

첫 줄에 HTTP/1.1 200 OK가 나오면 서버에는 닿습니다. 403은 대개 프록시나 네트워크 필터가 막았거나 지원하지 않는 지역에서 접속한 경우이고, 5xx는 일시적인 서비스 문제라 잠시 뒤 다시 하면 됩니다. 아무것도 안 나오거나 시간이 초과되면 네트워크가 연결을 막고 있는 겁니다. 회사망이라면 IT팀에 프록시 주소를 받아 같은 창에서 설정한 뒤 설치합니다(주소는 예시).

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

TLS 오류. Could not create SSL/TLS secure channel은 오래된 Windows 10에서 주로 나옵니다. TLS 1.2를 켜는 줄을 먼저 실행하고 이어서 설치합니다.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

CMD에서 CRYPT_E_NO_REVOCATION_CHECK나 CRYPT_E_REVOCATION_OFFLINE이 나오면 서버에는 닿았지만 회사 방화벽 등이 인증서 폐기 확인을 막은 경우입니다. 직접 실행하는 curl에만 옵션을 붙이면 됩니다.

curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

이 옵션은 폐기 확인 서버에 닿지 않는 것만 넘어가고, 폐기된 인증서는 그대로 거부합니다. PowerShell 설치 명령이나 WinGet은 curl을 쓰지 않아서 이 문제를 피해 갑니다. 회사 프록시가 TLS를 검사하는 환경이라면 프록시의 CA 인증서를 Windows 인증서 저장소에 넣어 달라고 IT팀에 요청해야 PowerShell 설치가 됩니다.

파일을 쓸 수 없다는 오류. Failed to download binary: The process cannot access the file ...은 설치 프로그램이 %USERPROFILE%\.claude\downloads에 쓰지 못한 경우입니다. 앞서 실행한 설치가 아직 돌고 있거나, 백신이 받다 만 파일을 검사 중일 때 생깁니다. 설치 중인 다른 PowerShell 창을 닫고 백신 검사가 끝나길 기다린 다음 실행합니다.

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

설치는 됐는데 claude를 못 찾을 때: PATH

위의 PowerShell·CMD 명령으로 설치하는 방식을 네이티브 설치라고 부릅니다. 네이티브 설치는 실행 파일을 %USERPROFILE%\.local\bin\claude.exe에 둡니다. Windows는 PATH라는 목록에 있는 폴더에서만 명령을 찾기 때문에 이 폴더가 목록에 없으면 다음처럼 나옵니다.

• CMD: 'claude' is not recognized as an internal or external command
• PowerShell: claude : The term 'claude' is not recognized as the name of a cmdlet

먼저 창을 닫고 새로 열어서 다시 해 보세요. 그래도 안 되면 PowerShell에서 PATH에 그 폴더가 있는지 봅니다.

$env:PATH -split ';' | Select-String '\.local\\bin'

아무것도 안 나오면 사용자 PATH에 추가합니다. 관리자 권한은 필요 없습니다.

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

창을 다시 열고 claude --version을 실행합니다. CMD만 쓴다면 echo %PATH% | findstr /i "local\bin"으로 확인하고, Windows 설정의 환경 변수 화면에서 사용자 PATH에 %USERPROFILE%\.local\bin을 추가합니다.

claude.exe가 아예 없을 때. 잘 쓰다가 업데이트 직후 갑자기 못 찾는다면 PATH 문제가 아닐 수 있습니다. Windows에서 업데이트할 때 Claude Code는 기존 claude.exe를 claude.exe.old.숫자 이름의 백업으로 바꿔 두고 새 파일을 넣는데, 이 단계가 실패하면 백업만 남습니다. 가장 최근 백업을 원래 이름으로 되돌립니다.

Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

백업 파일이 없거나 되돌려도 안 되면 설치 명령을 다시 실행합니다.

설치가 두 벌일 때. 네이티브와 WinGet, npm을 섞어 설치하면 버전이 엇갈릴 수 있습니다. where.exe claude로 잡히는 경로를 보고 하나만 남기세요. 공식 문서는 네이티브 설치를 권장합니다. WinGet 설치를 지우려면 winget uninstall Anthropic.ClaudeCode, npm은 npm uninstall -g @anthropic-ai/claude-code입니다.

claude를 쳤더니 Desktop 앱이 열릴 때. 예전 버전의 Claude Desktop은 WindowsApps 폴더에 Claude.exe를 등록해서 CLI보다 먼저 잡히는 경우가 있습니다. Claude Desktop을 최신 버전으로 업데이트하면 풀립니다.

running scripts is disabled: npm으로 설치했을 때만

이 오류는 Node.js의 npm으로 설치하거나, npm으로 설치한 claude를 실행할 때 나옵니다.

npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system.

PowerShell의 실행 정책이 npm이 만든 .ps1 실행 파일을 막는 겁니다. Microsoft 문서에 따르면 Windows 클라이언트에서 아무 정책도 정하지 않았을 때 적용되는 값은 Restricted이고, 이 정책은 개별 명령은 허용하지만 스크립트 파일은 실행하지 않습니다. 공식 PowerShell 설치 명령(irm ... | iex)은 받은 내용을 파일로 저장하지 않고 바로 실행해서 이 정책의 영향을 받지 않습니다.

해결은 세 가지 중 하나입니다.

1. 현재 사용자에게만 로컬 스크립트 실행을 허용합니다. CurrentUser 범위라 관리자 권한이 필요 없습니다.

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

2. 정책을 바꾸지 않고 npm.cmd, claude.cmd처럼 .cmd로 끝나는 실행 파일을 부릅니다. 같은 일을 하고 실행 정책의 대상이 아닙니다.
3. npm을 지우고 PowerShell 설치 명령으로 네이티브 설치를 합니다. 처음 설치하는 분이라면 이쪽이 가장 단순합니다.

회사 PC는 그룹 정책으로 실행 정책이 정해져 있을 수 있습니다. Microsoft 문서도 정책 변경 명령이 성공해도 더 높은 범위의 정책 때문에 실제 적용 값이 안 바뀔 수 있다고 적고 있어요. 이럴 땐 3번이 맞습니다.

Git for Windows는 꼭 깔아야 하나요

CLI 설치에는 필요 없습니다. 설치 문서는 Git for Windows를 선택 사항으로 둡니다. 없으면 Claude Code가 PowerShell 도구로 명령을 실행하고, 있으면 Git Bash로 Bash 도구를 씁니다. 설치를 권하는 건 Bash 도구와 Monitor 도구가 Git Bash를 쓰기 때문입니다.

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell이 나왔다면 두 셸을 모두 못 찾은 겁니다. PowerShell의 기본 위치는 C:\Windows\System32\WindowsPowerShell\v1.0\이니 이 폴더를 PATH에 넣거나, PowerShell 7을 설치합니다. Git for Windows를 설치한다면 설치 중 "Add to PATH"를 고르고 터미널을 다시 엽니다.

Git이 이미 있는데 못 찾는다면 where.exe git으로 위치를 찾고, 그 설치의 bin\bash.exe 경로를 settings.json의 env에 넣습니다.

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

파일 이름은 bash.exe, sh.exe, bash, sh 중 하나여야 합니다. Git for Windows의 git-bash.exe처럼 다른 이름을 넣으면 이 설정을 무시하고 Git Bash를 자동으로 찾습니다. 경로가 맞는데도 안 되면 회사 보안 프로그램이 막고 있을 수 있습니다. 이때는 IT팀에 claude.exe와 그 하위 프로세스(cmd.exe, bash.exe) 허용을 요청해야 합니다.

WSL을 쓴다면

Windows에서 Claude Code를 쓰는 방법은 네이티브와 WSL(Windows 안에서 Linux를 돌리는 기능) 두 갈래입니다. 표의 샌드박스는 Claude Code가 실행하는 명령을 격리하는 기능입니다.

WSL에서는 WSL 터미널 안에서 Linux 설치 명령(curl -fsSL https://claude.ai/install.sh | bash)을 실행하고, 실행도 WSL 안에서 합니다. PowerShell에 설치한 것과는 별개라 둘을 섞지 않습니다. WSL에서 claude가 cannot execute binary file: Exec format error를 내면 WSL 1의 알려진 문제입니다. PowerShell에서 배포판을 WSL 2로 바꾸는 게 가장 깔끔한 해결입니다(<DistroName> 자리에 배포판 이름).

wsl --set-version <DistroName> 2

WinGet으로 설치했다면 업데이트는 직접

네이티브 설치는 백그라운드에서 스스로 업데이트하고 다음 실행부터 적용됩니다. 바로 올리려면 claude update입니다. WinGet 설치는 기본이 수동 업데이트라서 가끔 직접 올려야 합니다.

winget upgrade Anthropic.ClaudeCode

Claude Code가 실행 중이면 Windows가 실행 파일을 잠가서 업그레이드가 실패할 수 있습니다. 이때는 Claude Code를 종료한 뒤 위 명령을 다시 실행하세요. 공식 문서에는 WinGet에 새 버전이 올라오기 전에 업데이트 알림이 먼저 뜰 수 있다는 알려진 문제도 적혀 있습니다. 실패하면 조금 기다렸다 다시 하면 됩니다. 환경 변수 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE를 1로 두면 Claude Code가 이 업그레이드를 대신 실행합니다.

winget 자체를 못 찾는 경우도 있습니다. Microsoft 문서에 따르면 WinGet은 App Installer에 들어 있습니다. 그런데 App Installer가 설치되지 않았거나, 새 PC에 처음 로그인한 직후라 등록이 아직 끝나지 않았을 수 있습니다. PATH에 잡히지 않는 사례도 문서에 적혀 있어요. 이럴 때는 WinGet을 먼저 고치기보다 PowerShell 설치 명령을 쓰는 편이 빠릅니다.

설치 상태가 궁금하면 claude doctor를 실행하세요. 세션을 열지 않고 설치 상태, 설정 파일 오류, 마지막 업데이트 결과를 보여 줍니다. 네이티브 설치를 지울 때는 PowerShell에서 다음 두 줄을 실행합니다.

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

로그인에서 막힐 때

설치 후 claude를 실행하면 브라우저 창이 열리고 거기서 로그인합니다. 브라우저가 열리지 않으면 로그인 화면에서 c를 눌러 로그인 주소를 복사하고 브라우저에 직접 붙여 넣습니다.

WSL 2처럼 브라우저가 로그인 뒤 터미널로 자동으로 돌아오지 못하는 환경에서는 브라우저가 로그인 코드를 보여 줍니다. 이 코드를 터미널의 Paste code here if prompted 자리에 붙여 넣으면 됩니다.

붙여 넣기가 안 먹히면 Windows Terminal에서는 마우스 오른쪽 클릭이나 Shift+Insert를 써 보세요. 그래도 안 되면 claude auth login으로 다시 로그인합니다. 붙여 넣은 코드를 따로 읽는 방식이라 네이티브 Windows에서 붙여 넣기가 안 될 때도 쓸 수 있습니다.

터미널이 계속 막히면: Desktop 앱의 Code 탭

설치 명령이 계속 막히면 터미널 없이 시작하는 길도 있습니다. Claude Desktop 앱의 Code 탭입니다.

• Desktop 앱에는 Claude Code가 들어 있어서 Node.js나 CLI를 따로 설치하지 않아도 됩니다. Windows용은 x64와 ARM64 설치 파일이 있습니다.
• Code 탭은 Pro, Max, Team, Enterprise 플랜이 필요합니다. 클릭했을 때 업그레이드 안내가 뜨면 유료 플랜이 없는 상태입니다.
• Git은 세션마다 작업 폴더를 따로 만드는 worktree 기능을 쓸 때만 필요합니다. 1.49585.0 이전 Windows 버전은 로컬 세션마다 Git을 요구했으니, worktree를 안 쓰는데 "Git is required"가 뜨면 앱을 업데이트하세요.
• 설치 중 다른 설치가 진행 중이라는 오류가 나는데 실제로는 아무것도 안 돌고 있다면, Desktop 문서는 설치 프로그램을 관리자 권한으로 실행해 보라고 안내합니다.

Desktop 앱과 터미널 CLI는 설치가 따로입니다. Code 탭으로 시작했다가 나중에 터미널에서 claude를 쓰고 싶어지면 그때 위의 설치 명령을 실행하면 됩니다. 둘 중 무엇으로 시작할지는 Claude Desktop Code 탭 vs 터미널 CLI에 비교해 두었습니다. Codex로 시작하고 싶다면 부트캠프에서 쓴 방식 그대로 Codex 데스크톱 앱 설치와 사용법을 보세요.

그래도 안 되면

1. claude --version은 되는데 다른 게 이상하면 claude doctor의 결과를 먼저 봅니다.
2. 세션을 열 수 있다면 Claude Code 안에서 /feedback으로 알립니다.
3. 설치 자체가 안 되면 GitHub 이슈에서 같은 오류를 찾아보고, 없으면 운영체제, 실행한 설치 명령, 오류 전체를 적어 새로 올립니다.
4. 구독이 인식되지 않거나 조직이 비활성화됐다는 식의 계정 문제는 claude.ai(Console 계정은 platform.claude.com)에 로그인해 왼쪽 아래 이니셜을 누르고 Get help로 문의합니다.

설치가 끝났다면 Claude Code 사용법: 처음 세션에서 익힐 6가지 핵심에서 첫 작업을 해 보세요.

출처와 확인 (2026-10-08)

• Claude Code: Advanced setup (시스템 요구 사항, 셸별 설치 명령, Windows 설정 표, Git for Windows, WinGet 업데이트, claude doctor, 삭제)
• Claude Code: Troubleshoot installation and login (증상별 오류 메시지와 해결 명령, PATH, 실행 정책, Git Bash 경로, WSL 1, 로그인)
• Claude Code: Terminal guide (PowerShell 여는 법, 설치 완료 문구, Windows 문제 해결)
• Claude Code: Tools reference (Windows의 PowerShell 도구)
• Claude Code: Desktop 빠른 시작 (Windows x64·ARM64 설치 파일, Code 탭 플랜, CLI 별도 설치)
• Claude Code: Desktop (Git 요구 조건, Windows 문제 해결)
• Microsoft: about_Execution_Policies (Windows 클라이언트 기본 Restricted, RemoteSigned, CurrentUser 범위)
• Microsoft: WinGet (App Installer에 포함)