Claude Code Windows 설치 방법: PowerShell 공식 경로와 오류 확인

핵심 요약: Windows에서 Claude Code CLI를 시작할 때는 현재 공식 설치 문서의 Windows 항목을 먼저 확인하고, 자신이 연 터미널이 PowerShell인지 구분하세요. 설치 명령 실행, 버전 확인, 계정 인증, 프로젝트 작업은 각각 다른 단계입니다. 이 글은 공식 경로를 정리한 안내이며 특정 PC에서 설치를 완료했다는 사용 후기가 아닙니다.

1. Windows 직접 실행과 WSL 중 환경 선택하기

공식 설치 안내는 Windows에서 직접 실행하는 방식과 WSL 안에서 실행하는 방식을 안내합니다. Windows 도구와 폴더를 중심으로 작업한다면 Windows 직접 실행을 검토하고, Linux 환경의 프로젝트라면 WSL 조건을 확인하세요. 여기서는 PowerShell에서 직접 설치하는 경로를 설명합니다.

2026년 10월 3일 확인한 문서는 Git for Windows를 선택 사항으로 안내합니다. 설치하지 않은 환경에서는 PowerShell 도구를 사용하는 설명이 있습니다. 따라서 “Git Bash가 없으면 설치 자체가 불가능하다”는 오래된 글의 표현을 현재 조건으로 받아들이지 마세요. 필요한 도구와 시스템 요구 사항은 공식 문서의 현재 내용을 기준으로 비교합니다.

2. 설치 전에 터미널과 공식 주소 확인하기

Windows Terminal은 여러 셸을 열 수 있는 프로그램입니다. 같은 창이어도 PowerShell과 명령 프롬프트는 다른 명령을 사용합니다. 아래 명령은 PowerShell용이므로 PowerShell 탭을 열었는지 확인하세요. 보통 프롬프트 앞의 PS 표시가 구분에 도움이 됩니다.

설치 명령은 공식 사이트의 스크립트를 내려받아 실행하는 형태입니다. 글에 적힌 문자열만 신뢰하기보다 공식 Quickstart의 Windows PowerShell 항목과 주소가 같은지 확인한 뒤 사용하세요. 회사나 학교에서 관리하는 PC라면 해당 환경의 설치 정책도 적용됩니다. 오류를 피하려고 모르는 설정을 한꺼번에 바꾸지 않는 편이 좋습니다.

3. PowerShell 설치 명령 실행하기

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

위 명령은 확인일 기준 공식 문서에 안내된 네이티브 설치 명령입니다. 실제 실행 결과는 인터넷 연결, 운영체제, 조직 정책 등 환경에 따라 확인해야 합니다. 실행 후 출력되는 안내를 읽고, 실패 메시지가 있으면 그대로 기록하세요. 끝에 버전 문자열이 보였는지와 오류가 없었는지를 구분해서 살펴봅니다.

공식 문서에는 WinGet 설치 경로도 있습니다. 여러 설치 방법을 동시에 시도하기보다 먼저 선택한 방법과 설치 결과를 기록하면 문제를 좁히기 쉽습니다. 이 글의 기본 흐름은 위 PowerShell 네이티브 설치 경로이며, 다른 방법을 선택하면 업데이트와 관리 절차도 해당 공식 항목에서 확인하세요.

4. 새 터미널에서 버전 확인 후 프로젝트 열기

설치가 끝나면 새 PowerShell 창을 열고 다음 명령으로 실행 파일을 찾을 수 있는지 확인합니다.

claude --version

버전이 표시되는 것과 Claude 계정 인증이 완료되는 것은 서로 다른 상태입니다. 이어서 실제 작업할 프로젝트 폴더로 이동하고 claude를 실행해 안내에 따라 인증합니다. 사용할 수 있는 계정과 인증 방식은 공식 문서에서 확인하세요. 비밀번호나 인증 코드는 공개 글이나 질문에 붙이지 않습니다.

cd "C:\경로\내프로젝트"
claude

위 경로는 예시입니다. 실제 폴더로 바꾸고, 프로젝트를 모르는 상태라면 처음에는 “구조와 실행 방법만 설명하고 아직 파일은 수정하지 마”라고 요청하세요. 버전 확인은 설치 상태를 확인하는 단계이고, 프로젝트의 빌드나 테스트 성공까지 증명하는 단계는 아닙니다.

5. 흔한 오류를 한 가지씩 확인하기

• irm을 찾을 수 없음: 명령 프롬프트에서 PowerShell용 명령을 실행한 것인지 확인합니다.
• claude를 찾을 수 없음: 새 터미널을 열었는지 확인하고, 설치 출력과 PATH 안내를 비교합니다.
• 403 또는 다운로드 오류: 출력한 오류와 실행 환경을 기록하고 공식 설치 문제 문서의 해당 항목을 확인합니다.
• 명령은 실행되지만 인증 실패: 설치 오류와 계정 인증 문제를 나눠 점검합니다.

정확한 원인을 확인하려면 공식 설치·로그인 문제 해결 문서에서 오류 문구를 찾아보세요. 질문할 때는 운영체제, 터미널 종류, 설치 방법, 오류 문구를 제공하되 개인 경로와 계정 정보는 필요한 범위로 가립니다. 설정 폴더 삭제나 재설치를 먼저 반복하면 기존 상태를 파악하기 어려워질 수 있습니다.

6. 설치 방법을 고를 때 프로젝트 위치부터 보기

명령이 짧다는 이유만으로 설치 방법을 바꾸기보다, 평소 프로젝트를 어디서 실행하는지 먼저 적어 보세요. 예를 들어 C 드라이브의 폴더를 Windows 개발 도구로 관리한다면 PowerShell 네이티브 경로가 자연스럽습니다. 반면 Linux 배포판 안에서 의존성을 설치하고 실행하는 프로젝트라면 그 배포판의 WSL 터미널에서 작업을 이어 가는 편이 환경을 설명하기 쉽습니다.

WinGet 경로를 선택했다면 공식 문서에 나온 winget install Anthropic.ClaudeCode를 해당 설치 경로의 안내와 함께 사용하세요. 확인일 기준 네이티브 설치는 자동 업데이트를 제공하며, WinGet 설치는 기본적으로 별도 업데이트가 필요합니다. WinGet의 수동 명령은 winget upgrade Anthropic.ClaudeCode입니다. 설치 방법과 업데이트 방법을 한 줄로 적어 두면 나중에 버전 문제를 질문할 때 도움이 됩니다.

설치에 쓰는 셸과 Claude Code가 작업 명령을 실행하는 셸도 구분하세요. PowerShell로 설치했다는 이유만으로 모든 작업이 항상 PowerShell을 사용한다고 단정할 수는 없습니다. Git for Windows 설치 여부 등 현재 환경이 영향을 주므로, 오류가 나온 명령의 실제 실행 환경을 함께 살펴야 합니다.

7. 실행 파일이 보이지 않을 때 읽기 전용으로 확인하기

아래는 설치 상태를 조사하는 명령 예시이며, 이 글에서 실행한 결과가 아닙니다. 먼저 새 PowerShell에서 claude --version을 시도한 뒤, 실행 파일을 찾지 못할 때만 진단 범위를 넓히세요. 네이티브 설치의 기본 경로는 공식 문제 해결 문서에서 확인한 사용자 폴더 아래의 경로입니다. 다른 설치 방식이라면 같은 위치에 파일이 없다는 것만으로 실패라고 판단하지 않습니다.

Get-Command claude -ErrorAction SilentlyContinue
where.exe claude
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

파일은 있는데 명령을 찾지 못한다면 설치 출력의 PATH 안내와 현재 창의 상태를 비교할 수 있습니다. 반대로 파일 자체가 없다면 다운로드와 설치 단계의 오류부터 돌아봅니다. PATH를 고치기 전에 공식 문서의 해당 항목을 읽고 어떤 사용자 경로를 추가하는지 파악하세요. 기존 PATH 전체를 임의의 문자열로 덮어쓰는 방식은 원인을 더 복잡하게 만들 수 있습니다.

명령이 실행된다면 claude doctor로 설치와 설정 진단을 요청할 수 있습니다. 공식 문서는 이 명령을 세션을 시작하지 않는 읽기 전용 진단으로 안내합니다. 진단에 표시된 제안도 자신의 설치 방식과 일치하는지 보고 적용하세요. 버전 출력만 가능한 상태와 실제 세션을 사용할 수 있는 상태는 계속 분리해 기록합니다.

8. 가상 오류 사례를 진단 요청으로 바꾸기

가상의 상황을 가정해 보겠습니다. PowerShell에서 네이티브 설치를 시도했고 새 창에서도 명령을 찾지 못하지만, 위 Test-Path 결과는 True입니다. 이는 설명용 상황이며 특정 PC의 관찰 결과가 아닙니다. 이때 “설치가 안 돼요” 대신 다음처럼 상태를 나눠 질문하면 파일 유무와 검색 경로를 따로 검토할 수 있습니다.

Windows 직접 실행 환경이며 PowerShell을 사용 중입니다.
설치 방법: 공식 PowerShell 네이티브 명령.
설치 출력: [민감한 값은 가린 실제 마지막 오류·안내]
새 창의 claude --version: [실제 출력]
Get-Command / where.exe: [실제 출력 또는 출력 없음]
기본 파일 위치 Test-Path: [실제 True 또는 False]
이 기록에서 관찰된 사실과 가능한 원인을 나눠 설명해 주세요.
현재 상태를 바꾸지 않는 다음 진단 한 가지부터 제안해 주세요.
재설치·설정 삭제는 원인과 영향이 설명되기 전에는 제안만 해 주세요.

다운로드 오류가 발생했다면 이 양식의 파일 확인보다 오류 코드와 설치 주소, 네트워크 환경을 먼저 제시합니다. 인증 오류라면 버전이 출력된다는 사실과 로그인 단계의 메시지를 추가하세요. 같은 “실패”라도 어느 단계인지에 따라 필요한 정보가 달라집니다. 질문에 인증 토큰이나 전체 환경 변수 목록을 붙일 필요는 없습니다.

9. 첫 프로젝트 실행과 이후 업데이트 기록하기

1. 실제로 존재하는 프로젝트 폴더 경로를 확인합니다. 공백이 있으면 경로를 따옴표로 감쌉니다.
2. 그 폴더로 이동하고 현재 수정 중인 파일이 있는지 확인합니다. 설치 확인을 위해 임의의 프로젝트 파일을 지우지 않습니다.
3. Claude Code를 시작해 인증 안내를 따르고, 처음에는 구조와 실행 절차를 설명해 달라고 요청합니다.
4. 사용할 명령을 확인한 뒤 작은 작업 한 가지를 정합니다. 설치 완료 기록에 빌드 완료까지 합쳐 쓰지 않습니다.

현재 프로젝트의 설명 파일과 실행 설정을 읽어 줘.
어떤 종류의 프로젝트인지, 시작 명령과 검증 명령의 근거 파일을 알려 줘.
파일 수정과 의존성 설치는 아직 하지 마.
모르는 명령을 추측하지 말고, 확인할 파일이나 질문을 제시해 줘.

업데이트 뒤 문제가 생겼다면 설치 방식, 이전에 기록한 버전, 현재 버전, 실패한 명령을 함께 적으세요. “업데이트 때문에 고장났다”는 원인 결론보다 “업데이트 이후 이 입력에서 이 오류가 보였다”는 관찰이 진단의 출발점입니다. 같은 프로젝트의 다른 명령이 정상인지도 분리하면 조사할 범위를 줄일 수 있습니다.

터미널을 바꿨더니 결과가 다르면 어떻게 하나요?

먼저 두 창의 종류와 실행 파일 경로를 비교하세요. Windows PowerShell과 WSL은 폴더 표현과 설치 위치가 다를 수 있습니다. 두 창에서 같은 이름의 명령을 입력했다는 사실만으로 같은 설치를 실행했다고 판단하지 않습니다. 원래 사용할 환경을 정한 뒤 그 환경의 경로와 버전부터 기록하세요.

자주 묻는 질문과 실수 해결

관리자 창이 필요한가요? 확인일 기준 공식 Windows 네이티브 안내는 관리자 실행이 필요하지 않다고 설명합니다. 환경별 정책은 별도로 확인하세요. WSL도 PowerShell 명령을 쓰나요? WSL 내부 설치는 공식 문서의 Linux·WSL 경로를 따라야 합니다. 설치 성공을 어떻게 기록하나요? 실제 표시된 버전과 인증 상태, 아직 확인하지 않은 프로젝트 동작을 구분해 남기세요.

공식 출처와 확인일

• Advanced setup
• Quickstart
• Troubleshoot installation and login

공식 문서 확인일: 2026년 10월 3일. 화면과 제공 조건은 이후 바뀔 수 있습니다.