💻
Claude Code CLI
Beginner-friendly Install Guide

터미널 한 번 안 켜본 사람도
혼자서 30분이면 끝

PowerShell이 뭔지 몰라도 OK. 화면 하나하나 캡처해두었으니 그대로 따라오세요. 막히면 마지막에 Claude한테 직접 물어보는 방법까지 알려드립니다.

1 Git for Windows 먼저 설치하기

PowerShell을 열기 전에 Git for Windows를 먼저 설치해야 합니다. Claude Code를 Windows에서 실행하려면 Git Bash 구성 요소가 필요합니다.

  1. Git for Windows 다운로드 페이지를 엽니다.
  2. 페이지에서 “Click here to download”를 클릭합니다. 다운로드가 자동으로 시작됩니다.
  3. 브라우저 오른쪽 위의 다운로드 목록에서 내려받은 Git-*-64-bit.exe 파일을 클릭합니다.
  4. Windows 보안 확인이 나오면 예를 누릅니다. 설치 첫 화면에서 Install을 클릭합니다.
  5. 설치가 진행되는 동안 기다립니다. 마지막 화면에서 반드시 Finish를 클릭해 설치를 끝냅니다. 창을 닫기만 하면 설치가 완료되지 않을 수 있습니다.
  6. 설치가 끝난 뒤에야 다음 단계의 PowerShell을 엽니다.
Git for Windows 페이지에서 Click here to download를 클릭하고 브라우저 다운로드 목록의 Git-2.55.0.3-64-bit.exe 파일을 확인하는 화면
① Click here to download 클릭 → ② 다운로드 목록에서 Git-*-64-bit.exe 클릭
Git 2.55.0.3 설치 첫 화면에서 Install 버튼을 클릭하는 화면
다운로드한 .exe 파일을 실행한 뒤, 설치 첫 화면에서 Install을 클릭합니다.
Git Setup Wizard 설치 완료 화면에서 Finish 버튼을 클릭하는 화면
설치가 끝나면 이 화면에서 반드시 Finish를 클릭합니다.
Finish까지 눌러야 진짜 설치 완료입니다

설치 중간에 창을 닫지 말고 마지막 화면까지 진행하세요. Finish를 누른 뒤에만 Git 설치가 끝납니다. 그 다음 PowerShell을 새로 열고 Step 2로 넘어가세요.

2 PowerShell 여는 법

PowerShell은 Windows에 기본으로 설치돼 있는 "검은 글자 입력 창"입니다. 이게 우리가 명령어를 입력할 곳이에요.

  1. 키보드 왼쪽 아래 ⊞ Windows 키를 누르거나, 화면 좌측 하단 시작 버튼을 클릭
  2. 그대로 키보드로 powershell 입력 (검색창이 자동으로 떠요)
  3. "Windows PowerShell" 항목을 클릭
Windows 시작 메뉴에 powershell을 입력했을 때 검색 결과 첫 번째로 'Windows PowerShell' 앱이 표시되는 화면
시작 메뉴에 powershell 입력 → 첫 번째 결과 클릭. 우클릭하면 "관리자 권한으로 실행" 도 가능하지만, 보통은 그냥 클릭으로 충분합니다.
처음 보면 무서워 보이지만

그냥 글자 입력하는 메모장이라고 생각하세요. 명령어 한 줄 붙여넣고 Enter 치면 끝입니다.

3 설치 명령어 한 줄 붙여넣기

PowerShell 창이 열렸다면, 아래 명령어를 복사해서 붙여넣고 Enter.

PowerShell — 한 줄 복사 후 붙여넣기
irm https://claude.ai/install.ps1 | iex
PowerShell 창에 붙여넣는 법

1순위 — 마우스 우클릭 한 번: 어떤 환경에서도 거의 항상 동작합니다.

2순위 — Ctrl+V: Windows 11과 최신 Windows 10에서는 잘 되지만, 일부 환경(콘솔 옵션이 꺼져 있거나 오래된 빌드)에서는 안 될 수 있습니다.

붙여넣은 후 Enter 한 번 더 눌러야 명령어가 실행됩니다.

실행하면 Setting up Claude Code... → Installing Claude Code native build latest... 메시지가 차례로 뜹니다.

PowerShell에 irm 명령어를 입력한 직후 'Setting up Claude Code...'와 'Installing Claude Code native build latest...' 메시지가 표시된 화면
설치가 시작된 직후 화면. 인터넷 속도에 따라 30초 ~ 2분 정도 걸립니다.
"Git for Windows가 필요합니다" 메시지가 뜨면

Git for Windows가 아직 설치되지 않았다면 Step 1로 돌아가 먼저 설치하세요. 설치가 끝난 뒤에는 PowerShell을 닫고 새로 열어 위 명령어를 다시 실행합니다.

4 PATH 자동 설정 확인

설치가 끝났을 때 화면에 두 가지 중 하나가 나옵니다.

설치 완료 후 'Setup notes'에 'C:\\Users\\...\\local\\bin is not in your PATH' 경고가 표시된 화면
이 노란 !! Setup notes 박스가 보이면 PATH 자동 추가가 안 된 케이스입니다.

케이스 A — Setup notes 경고가 안 보이고 그냥 Installation complete! 만 떴다면: 그대로 PowerShell을 X 버튼으로 닫고 새 PowerShell 창을 열어서 다음 단계(5)로.

케이스 B — !! Setup notes 와 ... is not in your PATH 메시지가 보이면: 아래 두 줄을 PowerShell에 그대로 붙여넣고 Enter.

PowerShell — PATH에 Claude Code 추가
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
⚠ 이 단계가 가장 중요합니다 — 창을 꼭 새로 여세요

위 명령어 실행 후에는 PowerShell 창을 X 버튼으로 완전히 닫고, 시작 메뉴에서 새 PowerShell 창을 다시 여세요. 같은 창에서 claude 입력하면 여전히 안 됩니다 — 이건 Windows 환경 변수의 동작 방식 때문이라 어쩔 수 없습니다.

위 두 줄이 안 먹는 환경(권한 제한 등)이라면 — GUI로 PATH 추가
  1. 시작 메뉴에서 sysdm 입력 → "시스템 속성" 또는 "고급 시스템 속성 보기" 클릭
    시작 메뉴에 sysdm 입력 시 시스템 속성이 검색되는 화면
  2. 고급 탭 → 환경 변수 버튼
  3. 사용자 변수 칸의 Path 선택 → 편집 → 새로 만들기 → %USERPROFILE%\.local\bin 입력 → 확인
    시스템 속성 → 환경 변수 → 사용자 변수 PATH 편집 창에서 .local\\bin 경로가 추가된 화면
  4. 모든 창 확인으로 닫고, PowerShell도 닫고 새로 열기

5 설치 검증 + Claude 첫 실행

새로 연 PowerShell 창에서 다음 두 줄을 차례로 입력하세요.

PATH가 잘 잡혔는지 확인
$env:PATH -split ';' | Select-String 'local\bin'

한 줄 이상 출력되면 OK. 아무것도 안 나오면 Step 4를 다시.

Claude 버전 확인 + 실행
claude --version
claude
PowerShell에서 irm 설치, PATH 검증, claude 실행까지 전체 흐름과 환영 화면(가재 모양 마스코트와 'Welcome back' 메시지)이 표시된 화면
전체 흐름. 마지막에 가재 모양 마스코트와 "Welcome back!" 메시지가 보이면 성공입니다.
무료 Claude.ai 계정으로는 사용할 수 없습니다

Claude Code를 사용하려면 Claude Max 5x 구독이 필요합니다. claude.ai/pricing에서 Max 5x를 구매하세요. 처음 claude 실행 시 브라우저가 열리면 로그인합니다.

1 터미널 여는 법

macOS의 "터미널(Terminal)"은 검은 글자 입력 창. 우리가 명령어를 입력할 곳입니다.

  1. 키보드 ⌘ Command + Space (Spotlight 검색 열기)
  2. 검색창에 터미널 입력
  3. Enter
macOS Spotlight 검색에서 '터미널'을 입력했을 때 첫 번째 결과로 터미널 앱 아이콘이 표시되는 화면
⌘+Space → 터미널 입력 → 첫 번째 결과 클릭 또는 Enter.
처음 보면 무서워 보이지만

그냥 글자 입력하는 메모장이라고 생각하세요. 명령어 한 줄 붙여넣고 Enter 치면 끝입니다.

2 설치 명령어 한 줄 붙여넣기

터미널이 열렸다면, 아래 명령어를 복사해서 붙여넣고 Enter.

Terminal — 한 줄 복사 후 붙여넣기
curl -fsSL https://claude.ai/install.sh | bash
터미널에 붙여넣는 법

⌘ Command + V 또는 마우스 우클릭 → 붙여넣기. 붙여넣은 뒤 Enter를 눌러 실행합니다.

3 PATH 자동 설정 확인

설치가 끝났는데 command not found: claude 같은 에러가 보이거나, ... is not in your PATH 경고가 뜬다면 아래 한 줄을 그대로 붙여넣고 Enter.

macOS / Linux — PATH에 Claude Code 추가
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Linux에서 기본 셸이 bash라면 ~/.zshrc 두 군데를 모두 ~/.bashrc 로 바꿔서 실행하세요.

⚠ 터미널 창을 새로 여세요

위 명령어 실행 후 현재 터미널 창을 닫고 새로 여세요. source 명령으로 같은 창에 적용은 됐지만, 새 창에서 다시 시작하는 게 가장 확실합니다.

4 설치 검증 + Claude 첫 실행

PATH 확인
echo $PATH | tr ':' '\n' | grep local/bin

한 줄 이상 출력되면 OK.

Claude 버전 확인 + 실행
claude --version
claude
macOS 터미널에서 claude 명령어 실행 후 'Welcome back' 메시지와 가재 마스코트가 그려진 환영 화면
가재 마스코트와 Welcome back!이 보이면 성공. 그대로 한국어로 질문 시작.
무료 Claude.ai 계정으로는 사용할 수 없습니다

Claude Code를 사용하려면 Claude Max 5x 구독이 필요합니다. claude.ai/pricing에서 Max 5x를 구매하세요. 처음 claude 실행 시 브라우저가 열리면 로그인합니다.

6 막혔다면 — Claude한테 직접 물어보기

위 단계대로 했는데 어디선가 멈췄나요? 화면을 통째로 복사해서 Claude 채팅에 붙여넣으면 Claude가 본인 환경에 맞춰 해결책을 알려줍니다. 가이드 문서보다 빠릅니다.

  1. PowerShell / 터미널 창에서 위에서부터 끝까지 마우스로 드래그해 전체 선택 → 우클릭으로 복사
    • Windows PowerShell은 드래그한 순간 자동 복사되는 경우가 많아요
    • macOS는 ⌘ + A 후 ⌘ + C
  2. 새 브라우저 탭에서 claude.ai 접속 → 로그인 → 새 채팅 시작
  3. 채팅창에 아래 메시지 + 복사한 화면 전체를 그대로 붙여넣기:
Claude 채팅에 보낼 메시지
Claude Code CLI 설치하다 막혔어. 아래는 내가 PowerShell(또는 터미널)에서 본 화면 전체야.
어디서 멈췄고 어떻게 해결해야 하는지 알려줘.
---
[여기에 복사한 화면 통째로 붙여넣기]

Claude가 본인 OS와 화면 상태에 맞춰 PATH 설정 / 권한 문제 / 누락된 의존성 등을 진단해 줍니다.

Claude가 알려준 명령어를 실행한 뒤에는

반드시 PowerShell / 터미널 창을 닫고 새로 연 다음 claude --version을 다시 시도하세요.

PowerShell 안의 Claude Code 환영 화면에서 한국어로 자유롭게 질문하고 답변받는 시연 화면
설치만 끝났다면 PowerShell/터미널의 Claude한테도 한국어로 그대로 물어볼 수 있습니다. 화면을 통째로 복사해 claude.ai 웹 채팅에 붙여넣는 방법(위 안내)도 동일하게 동작합니다.

7 자주 마주치는 함정

공식 문서의 트러블슈팅 페이지 중 일반 사용자가 자주 마주치는 케이스만 추렸습니다. 더 깊은 트러블슈팅은 공식 문서 — 문제 해결 참고.

'claude' is not recognized / command not found: claude

PATH 설정이 안 됐거나, 설정 후 창을 새로 안 연 것. Step 4를 다시. 그래도 안 되면 Step 6.

Claude Code on Windows requires git-bash

Git for Windows 설치 후 PowerShell 닫고 다시 열기.

Claude Code does not support 32-bit Windows

실제로는 64비트인데 시작 메뉴에서 "Windows PowerShell (x86)" 을 잘못 연 경우. 그냥 "Windows PowerShell" (x86 표시 없는 것)을 여세요.

로그인은 됐는데 API Error 400 ... organization disabled

ANTHROPIC_API_KEY 환경변수가 구독 OAuth를 덮어쓰는 함정.
PowerShell: Remove-Item Env:ANTHROPIC_API_KEY
macOS/Linux: unset ANTHROPIC_API_KEY
그 후 claude 다시 실행.

App unavailable in region

Anthropic 지원국 외 IP에서 발생. 한국에서 자주 — VPN으로 미국/일본 등 지원국으로 우회 후 재시도.

macOS Keychain 잠김

security: SecKeychainSearchCopyNext 같은 메시지가 뜨면
security unlock-keychain ~/Library/Keychains/login.keychain-db 실행 후 비밀번호 입력.

뭐가 잘못됐는지 도통 모르겠을 때

설치돼 있다면 claude doctor 실행. 또는 claude 진입 후 /doctor. 설치 상태·자동 업데이트·MCP 설정·플러그인 로딩 오류 등을 진단해 줍니다.

그래도 안 풀리면

위 Step 6의 "Claude한테 직접 물어보기"를 사용하세요. 화면 전체 복붙이 가장 빠릅니다.

막히면 언제든 Claude한테

이 가이드의 어느 단계에서든 막혔다면 PowerShell/터미널 화면을 통째로 복사해서 claude.ai 또는 Claude 데스크톱 앱의 새 채팅에 붙여넣고 "이거 어떻게 해" 라고 물어보세요. 본인 화면 그대로 보여주는 게 가장 빠른 해결책입니다.

설치 끝났나요? 다음은 사용해볼 차례

강의 자료 또는 우리 사이트의 다른 가이드도 함께 살펴보세요.

홈으로 공식 빠른 시작 →