# Claude Code CLI 설치 방법: Windows·macOS·Linux·WSL과 PATH 오류 해결

> 출처: https://retn.kr/docs/ai-coding/claude-code-install/ · 수정 2026-10-30 · 리텐션 주식회사

macOS·Linux·WSL은 터미널에서 curl -fsSL https://claude.ai/install.sh | bash 를, Windows는 PowerShell에서 irm https://claude.ai/install.ps1 | iex 를 실행합니다. 설치가 끝나면 새 터미널 창을 열고 claude --version 으로 확인합니다. claude를 찾을 수 없다고 나오면 설치 폴더(~/.local/bin, Windows는 %USERPROFILE%\.local\bin)를 PATH에 추가하고 창을 다시 엽니다.

이 문서는 터미널을 처음 여는 사람을 기준으로 썼습니다. 운영체제별 설치 명령, 설치 확인, PATH 설정, 자주 나는 오류 순서로 정리했습니다. 명령어는 2026-10-30에 [[claude-code|Claude Code]] 공식 문서와 대조했습니다. PowerShell·터미널 화면은 2026-04-27에 직접 설치하면서 찍었습니다(v2.1.119). Git for Windows 화면은 2026-08에 찍었습니다(Git 2.55.0.3).

:::note
터미널을 쓰지 않으려면 Claude Code 데스크톱 앱을 씁니다. [claude.com/download](https://claude.com/download)에서 macOS·Windows용을 받습니다. 데스크톱 앱에는 이 문서의 명령어가 필요 없습니다.
:::

## Claude Code CLI 설치 방법

Claude Code CLI는 터미널에 명령 한 줄을 붙여넣어 설치합니다. [[cli]]는 마우스 대신 글자로 명령을 입력하는 방식입니다. 운영체제와 터미널 종류에 맞는 명령 하나만 실행합니다.

**macOS, Linux, WSL** (터미널)

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

**Windows PowerShell** (줄 앞에 `PS C:\`가 보이는 창)

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

**Windows CMD** (줄 앞에 `PS` 없이 `C:\`만 보이는 창)

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

설치가 끝나면 새 터미널 창을 엽니다. 그 창에서 `claude --version`을 실행합니다. `2.1.312 (Claude Code)`처럼 버전 번호가 나오면 설치된 것입니다. 운영체제별 자세한 순서는 아래 섹션에 있습니다.

## 설치 전에 확인할 것

Table: Claude Code 시스템 요구사항 (2026-10-30 공식 문서 기준)
| 항목 | 요구사항 |
|---|---|
| macOS | 13.0 이상 |
| Windows | Windows 10 1809 이상 또는 Windows Server 2019 이상, 64비트 |
| Linux | Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상 |
| 하드웨어 | RAM 4GB 이상, x64 또는 ARM64 프로세서 |
| 셸 | Bash, Zsh, PowerShell, CMD |
| 네트워크·위치 | 인터넷 연결, Anthropic 지원 국가(한국 포함) |

- **계정**: Claude Pro, Max, Team, Enterprise 계정 또는 Claude Console 계정이 필요합니다. 무료 claude.ai 플랜으로는 Claude Code를 쓸 수 없습니다. 구독은 [claude.com/pricing](https://claude.com/pricing)에서 합니다.
- **Node.js**: 기본 설치에는 Node.js가 필요 없습니다. npm으로 설치할 때만 Node.js 22 이상이 필요합니다.
- **관리자 권한**: Windows에서는 관리자로 실행하지 않아도 됩니다. macOS·Linux에서는 명령 앞에 `sudo`를 붙이지 않습니다. 설치 스크립트는 `sudo` 실행을 거부합니다.

## Windows에서 설치

Windows에는 두 가지 방법이 있습니다. 네이티브 설치는 PowerShell이나 CMD에서 바로 설치합니다. WSL 설치는 Windows 안의 Linux에서 설치합니다. 처음이면 네이티브 설치를 씁니다. WSL은 [WSL에서 설치](#wsl에서-설치)를 봅니다.

### 1단계: Git for Windows 설치 (선택, 권장)

Git for Windows는 선택 사항입니다. 설치하면 Claude Code가 Git Bash로 명령을 실행합니다. 설치하지 않으면 Claude Code가 PowerShell로 명령을 실행합니다. 공식 문서는 네이티브 Windows에서 Git for Windows 설치를 권장합니다. [[git|Git]]을 직접 배울 필요는 없습니다. 이미 Git이 있으면 이 단계를 건너뜁니다.

:::steps
1. 브라우저에서 [git-scm.com/downloads/win](https://git-scm.com/downloads/win)을 엽니다.
2. "Click here to download"를 클릭합니다. 다운로드가 자동으로 시작됩니다.
3. 브라우저 다운로드 목록에서 `Git-*-64-bit.exe` 파일을 클릭합니다.
4. Windows 보안 확인 창이 나오면 "예"를 누릅니다.
5. 설치 화면에서 Install(또는 Next)을 눌러 기본값으로 진행합니다. "Adjusting your PATH environment" 화면이 나오면 권장 옵션을 그대로 둡니다.
6. 마지막 화면에서 Finish를 클릭합니다.
:::

![Git for Windows 페이지에서 Click here to download를 클릭하고 브라우저 다운로드 목록의 Git-2.55.0.3-64-bit.exe 파일을 확인하는 화면](/images/docs/claude-code-install/git-for-windows-download.webp "① Click here to download 클릭 → ② 다운로드 목록에서 Git-*-64-bit.exe 클릭")

![Git 2.55.0.3 설치 첫 화면에서 Install 버튼을 클릭하는 화면](/images/docs/claude-code-install/git-for-windows-install.webp "설치 첫 화면에서 Install을 클릭합니다.")

![Git Setup Wizard 설치 완료 화면에서 Finish 버튼을 클릭하는 화면](/images/docs/claude-code-install/git-for-windows-finish.webp "마지막 화면에서 Finish를 클릭해야 설치가 끝납니다.")

:::warning
설치 중간에 창을 닫지 않습니다. Finish를 누른 뒤에 PowerShell을 새로 엽니다. 이미 열려 있던 PowerShell 창은 Git을 찾지 못합니다.
:::

### 2단계: PowerShell 열기

PowerShell은 Windows에 기본으로 들어 있는 명령 입력 창입니다. 명령을 한 줄 붙여넣고 Enter를 누르면 실행됩니다.

:::steps
1. 키보드의 Windows 키를 누르거나 화면 왼쪽 아래 시작 버튼을 클릭합니다.
2. `powershell`을 입력합니다. 검색창이 자동으로 열립니다.
3. "Windows PowerShell"을 클릭합니다. "(x86)"이 붙은 항목은 열지 않습니다.
:::

`Win + X`를 누르고 메뉴에서 "Windows PowerShell" 또는 "터미널"을 골라도 됩니다. 관리자 권한으로 실행할 필요는 없습니다.

![Windows 시작 메뉴에 powershell을 입력했을 때 검색 결과 첫 번째로 Windows PowerShell 앱이 표시되는 화면](/images/docs/claude-code-install/win-powershell-search.webp "시작 메뉴에 powershell 입력 → 첫 번째 결과 클릭")

PowerShell 창에는 줄 앞에 `PS C:\Users\이름>`이 보입니다. `PS` 없이 `C:\Users\이름>`만 보이면 CMD입니다. CMD에서는 3단계의 CMD 명령을 씁니다.

### 3단계: 설치 명령 붙여넣기

아래 명령을 복사해 PowerShell에 붙여넣고 Enter를 누릅니다.

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

PowerShell에 붙여넣는 방법은 두 가지입니다.

1. 마우스 오른쪽 버튼을 한 번 클릭합니다. 대부분의 환경에서 동작합니다.
2. `Ctrl + V`를 누릅니다. 일부 오래된 콘솔 설정에서는 동작하지 않을 수 있습니다.

`irm`은 설치 스크립트를 내려받고, `iex`는 그 스크립트를 실행합니다. 두 부분을 모두 붙여넣어야 설치됩니다.

실행하면 먼저 `Setting up Claude Code...`가 나옵니다. 다운로드 중에는 진행 표시가 없습니다. 창을 닫지 말고 기다립니다. 2026-04-27에 직접 설치했을 때(v2.1.119)는 이 단계에서 `Installing Claude Code native build latest...`가 표시됐고, 30초~2분이 걸렸습니다. 설치가 끝나면 `Claude Code successfully installed!`와 `Installation complete!`가 나옵니다.

![PowerShell에 irm 명령어를 입력한 직후 Setting up Claude Code...와 Installing Claude Code native build latest... 메시지가 표시된 화면](/images/docs/claude-code-install/win-install-running.webp "설치가 시작된 직후 화면 (2026-04-27, v2.1.119)")

CMD 창이라면 아래 명령을 씁니다.

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

### 4단계: PATH 경고 확인

설치가 끝난 화면은 두 가지 중 하나입니다.

- **경우 A**: `Setup notes:` 경고 없이 `Installation complete!`만 보입니다. PowerShell 창을 닫고 새 PowerShell 창을 연 뒤 5단계로 갑니다.
- **경우 B**: `Setup notes:` 아래에 `Native installation exists but C:\Users\이름\.local\bin is not in your PATH.`가 보입니다. 설치 폴더가 PATH에 없다는 뜻입니다. 설치 프로그램은 이 경고만 출력하고 PATH를 바꾸지 않습니다. 아래 두 줄을 PowerShell에 붙여넣고 Enter를 누릅니다.

![설치 완료 후 Setup notes에 C:\Users\이름\\.local\bin is not in your PATH 경고가 표시된 화면](/images/docs/claude-code-install/win-setup-notes-warning.webp "노란 Setup notes 경고가 보이면 경우 B입니다.")

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

이 명령은 사용자 PATH 끝에 `%USERPROFILE%\.local\bin`을 추가합니다. 한 번만 실행하면 됩니다.

:::warning
PATH를 바꾼 뒤에는 PowerShell 창을 X 버튼으로 닫고 새 창을 엽니다. 이미 열려 있던 창은 예전 PATH를 계속 씁니다. 같은 창에서 `claude`를 입력하면 여전히 찾지 못합니다. VS Code 같은 편집기 안의 터미널이라면 편집기를 종료했다가 다시 엽니다.
:::

:::toggle{title="명령이 막힌 환경이라면: 화면에서 PATH 추가하기"}
회사 PC처럼 위 명령이 막힌 환경에서는 시스템 속성 화면에서 추가합니다. 설치 프로그램의 경고 문구도 같은 순서를 안내합니다.

1. 시작 메뉴에서 `sysdm`을 입력하고 "시스템 속성" 또는 "고급 시스템 설정 보기"를 클릭합니다.
2. "고급" 탭에서 "환경 변수"를 클릭합니다.
3. "사용자 변수"에서 `Path`를 선택하고 "편집"을 클릭합니다.
4. "새로 만들기"를 클릭하고 `%USERPROFILE%\.local\bin`을 입력합니다.
5. 열린 창을 모두 "확인"으로 닫습니다.
6. PowerShell을 닫고 새로 엽니다.

![시작 메뉴에 sysdm을 입력했을 때 시스템 속성이 검색되는 화면](/images/docs/claude-code-install/win-sysdm-search.webp "시작 메뉴에 sysdm 입력")

![시스템 속성의 환경 변수에서 사용자 변수 Path 편집 창에 .local\bin 경로를 추가한 화면](/images/docs/claude-code-install/win-env-variables-gui.webp "사용자 변수 Path에 %USERPROFILE%\\.local\bin 추가")
:::

### 5단계: 설치 확인과 첫 실행

새로 연 PowerShell 창에서 PATH를 확인합니다.

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

`C:\Users\이름\.local\bin`이 출력되면 PATH가 맞습니다. 아무것도 나오지 않으면 4단계를 다시 합니다.

버전을 확인하고 Claude Code를 실행합니다.

```powershell
claude --version
claude
```

처음 실행하면 브라우저가 열리고 로그인 화면이 나옵니다. 로그인 순서는 [첫 실행과 로그인](#첫-실행과-로그인)에 있습니다.

## macOS·Linux에서 설치

### 1단계: 터미널 열기

터미널은 macOS와 Linux의 명령 입력 창입니다.

:::steps
1. macOS에서는 `Cmd + Space`를 눌러 Spotlight를 엽니다.
2. `터미널`(영문 macOS는 `Terminal`)을 입력합니다.
3. Enter를 누릅니다.
:::

Linux에서는 대부분 `Ctrl + Alt + T`를 누르거나 앱 메뉴에서 "Terminal"을 찾습니다.

![macOS Spotlight 검색에 터미널을 입력했을 때 첫 번째 결과로 터미널 앱이 표시되는 화면](/images/docs/claude-code-install/mac-spotlight.webp "Cmd + Space → 터미널 입력 → Enter")

### 2단계: 설치 명령 붙여넣기

아래 명령을 복사해 터미널에 붙여넣고 Enter를 누릅니다. macOS는 `Cmd + V`, Linux는 `Ctrl + Shift + V`로 붙여넣습니다.

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

명령 앞에 `sudo`를 붙이지 않습니다. Claude Code는 내 홈 폴더에 설치됩니다. 다운로드 중에는 진행 표시가 없으므로 창을 열어 둔 채 기다립니다. 끝나면 `Claude Code successfully installed!`와 `Installation complete!`가 나옵니다.

### 3단계: PATH 확인

설치가 끝난 뒤 `Setup notes:`에 `Native installation exists but ~/.local/bin is not in your PATH.`가 보이면 PATH 설정이 필요합니다. `command not found: claude`가 나와도 같습니다. 먼저 설치 폴더가 PATH에 있는지 확인합니다.

```bash
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
```

`/Users/이름/.local/bin` 또는 `/home/이름/.local/bin`이 나오면 PATH가 맞습니다. 아무것도 나오지 않으면 아래 두 줄을 실행합니다. macOS의 기본 셸인 Zsh용입니다.

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

첫 줄은 설정을 저장하고, 둘째 줄은 지금 창에 적용합니다. `echo` 명령은 성공하면 아무것도 출력하지 않습니다.

:::toggle{title="Linux 또는 Bash를 쓴다면"}
대부분의 Linux 배포판은 Bash가 기본입니다. `~/.bashrc`에 추가합니다.

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

macOS에서 Bash를 쓴다면 `~/.bashrc` 대신 `~/.bash_profile`에 추가합니다. macOS 터미널은 Bash를 로그인 셸로 시작하고 `~/.bashrc`를 읽지 않습니다.

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile
```

어떤 셸을 쓰는지 모르면 `echo $0`을 실행합니다.
:::

:::warning
PATH를 바꾼 뒤에는 터미널 창을 닫고 새로 엽니다. `source`로 지금 창에도 적용되지만, 새 창에서 확인하는 편이 확실합니다.
:::

### 4단계: 설치 확인과 첫 실행

```bash
claude --version
claude
```

`claude --version`이 버전 번호를 출력하면 설치가 끝난 것입니다. `claude`를 실행하면 브라우저가 열리고 로그인 화면이 나옵니다.

![macOS 터미널에서 claude --version과 claude를 실행한 뒤 Welcome back 메시지와 가재 모양 캐릭터가 보이는 환영 화면](/images/docs/claude-code-install/mac-claude.webp "가재 모양 캐릭터와 Welcome 메시지가 보이면 성공입니다 (2026-04-27, v2.1.119).")

## WSL에서 설치

WSL은 Windows 안에서 Linux를 실행하는 기능입니다. Linux 도구로 작업하거나 샌드박스로 명령을 실행하려면 WSL 2를 씁니다.

:::steps
1. 시작 메뉴에서 WSL 배포판(예: Ubuntu)을 열어 Linux 터미널을 띄웁니다.
2. 그 Linux 터미널에서 macOS·Linux용 명령을 실행합니다. PowerShell이나 CMD에서 실행하지 않습니다.
3. PATH는 [macOS·Linux에서 설치](#macoslinux에서-설치)의 3단계 Bash 방법으로 확인합니다.
4. 같은 WSL 터미널에서 `claude`를 실행합니다.
:::

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

WSL에는 Git for Windows가 필요 없습니다. WSL2에서 로그인 브라우저가 열리지 않으면 [첫 실행과 로그인](#첫-실행과-로그인)의 방법을 씁니다.

## 첫 실행과 로그인

:::steps
1. 터미널에서 `claude`를 실행합니다.
2. 브라우저가 열리면 Claude 계정으로 로그인합니다.
3. 브라우저가 자동으로 열리지 않으면 터미널에서 `c`를 누릅니다. 로그인 주소가 클립보드에 복사됩니다. 브라우저 주소창에 붙여넣습니다.
4. WSL2, SSH, 컨테이너처럼 브라우저가 다른 컴퓨터에서 열리면 브라우저에 표시된 코드를 복사합니다. 터미널의 `Paste code here` 프롬프트에 붙여넣습니다.
5. 터미널에 환영 화면과 가재 모양 캐릭터가 보이면 준비가 끝난 것입니다.
:::

로그인에는 Pro, Max, Team, Enterprise 또는 Console 계정이 필요합니다. 무료 계정으로는 로그인해도 Claude Code를 쓸 수 없습니다. `ANTHROPIC_API_KEY` 환경 변수가 설정돼 있으면 Claude Code가 그 키를 쓸지 묻습니다. 키를 승인하면 Claude Code는 로그인 화면을 건너뛰고 그 키를 씁니다.

환영 화면이 나오면 한국어로 바로 질문할 수 있습니다.

![PowerShell 안의 Claude Code 환영 화면에서 한국어로 질문하고 답변을 받는 화면](/images/docs/claude-code-install/win-claude-chat-demo.webp "설치가 끝나면 터미널 안에서 한국어로 대화할 수 있습니다 (2026-04-27).")

처음 쓸 때 알아 둘 조작입니다.

- 메시지를 입력하고 Enter를 누르면 보냅니다.
- 터미널에서는 마우스로 항목을 클릭할 수 없습니다. 화살표 키로 움직입니다.
- Claude가 작업하는 중에 멈추려면 `Esc`를 누릅니다.
- 끝내려면 `exit`를 입력합니다.
- 쓸 수 있는 명령을 보려면 `/help`를 입력합니다.

처음에는 아무 폴더에서 실행해도 됩니다. 실제 작업은 작업할 폴더에서 터미널을 열고 `claude`를 실행합니다.

## claude 명령어를 찾을 수 없을 때

설치는 끝났는데 `claude`가 실행되지 않으면 대부분 PATH 문제입니다. PATH는 터미널이 프로그램을 찾는 폴더 목록입니다. 설치 프로그램은 `claude`를 macOS·Linux에서는 `~/.local/bin/claude`에, Windows에서는 `%USERPROFILE%\.local\bin\claude.exe`에 둡니다.

Table: 운영체제별 오류 메시지
| 환경 | 오류 메시지 |
|---|---|
| macOS | `zsh: command not found: claude` |
| Linux | `bash: claude: command not found` |
| Windows 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` |

아래 순서로 확인합니다.

:::steps
1. 파일이 있는지 확인합니다. macOS·Linux는 `ls -la ~/.local/bin/claude`, PowerShell은 `Test-Path "$env:USERPROFILE\.local\bin\claude.exe"`를 실행합니다.
2. 파일이 없으면(`No such file or directory` 또는 `False`) 설치가 안 된 것입니다. 설치 명령을 다시 실행합니다.
3. 파일이 있으면 PATH에 폴더를 추가합니다. Windows는 [Windows 4단계](#4단계-path-경고-확인), macOS·Linux는 [macOS·Linux 3단계](#3단계-path-확인)를 따릅니다.
4. 터미널 창을 모두 닫고 새로 엽니다. VS Code 같은 편집기 안의 터미널이라면 편집기를 종료했다가 다시 엽니다.
5. `claude --version`을 다시 실행합니다.
:::

CMD에서는 `echo %PATH% | findstr /i "local\bin"`으로 PATH를 확인합니다. 출력이 없으면 Windows 4단계의 화면 방법으로 `%USERPROFILE%\.local\bin`을 추가합니다.

Windows에서 Claude Code가 업데이트된 직후 `'claude' is not recognized`가 나오면 `claude.exe`가 백업 이름으로 남았을 수 있습니다. PowerShell에서 가장 최근 백업을 원래 이름으로 되돌립니다.

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

백업 파일이 없으면 설치 명령을 다시 실행합니다.

## 자주 나는 설치 오류

### irm이 인식되지 않거나 && 오류가 날 때

다른 셸용 명령을 붙여넣은 경우입니다.

Table: Windows에서 셸과 명령이 맞지 않을 때
| 오류 메시지 | 원인 | 해결 |
|---|---|---|
| `'irm' is not recognized` | CMD에서 PowerShell 명령을 실행함 | PowerShell을 열거나 CMD용 명령을 씀 |
| `The token '&&' is not a valid statement separator` | PowerShell에서 CMD 명령을 실행함 | PowerShell용 `irm` 명령을 씀 |
| `A parameter cannot be found that matches parameter name 'fsSL'` | PowerShell에서 macOS·Linux 명령을 실행함 | PowerShell용 `irm` 명령을 씀 |
| `'bash' is not recognized as the name of a cmdlet` | Windows에서 macOS·Linux 명령을 실행함 | PowerShell용 `irm` 명령을 씀 |
| 설치 스크립트 글자만 출력되고 설치되지 않음 | 명령의 앞부분(`irm`)만 실행함 | `iex`까지 포함한 한 줄 전체를 실행함 |

명령은 [Claude Code CLI 설치 방법](#claude-code-cli-설치-방법)에 셸별로 있습니다.

### Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

Claude Code가 Git Bash와 PowerShell을 둘 다 찾지 못했다는 뜻입니다. Git for Windows는 선택 사항이므로 PowerShell만 찾아도 동작합니다.

- **PowerShell을 PATH에서 못 찾는 경우**: 기본 위치는 `C:\Windows\System32\WindowsPowerShell\v1.0\`입니다. 이 폴더를 PATH에 추가하거나 PowerShell 7을 설치합니다.
- **Git for Windows를 쓰려는 경우**: [Windows 1단계](#1단계-git-for-windows-설치-선택-권장)대로 설치하고 터미널을 다시 엽니다.
- **Git은 있는데 못 찾는 경우**: PowerShell에서 `where.exe git`으로 Git 위치를 찾습니다. 그 설치의 `bin\bash.exe` 경로를 `settings.json`의 `CLAUDE_CODE_GIT_BASH_PATH`에 넣습니다.

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

### Claude Code does not support 32-bit Windows

64비트 컴퓨터에서도 "Windows PowerShell (x86)"을 열면 이 오류가 납니다. 같은 창에서 아래 명령을 실행합니다.

```powershell
[Environment]::Is64BitOperatingSystem
```

`True`가 나오면 운영체제는 64비트입니다. 창을 닫고 "(x86)"이 없는 "Windows PowerShell"을 열어 설치 명령을 다시 실행합니다. `False`가 나오면 32비트 Windows입니다. Claude Code는 64비트 운영체제가 필요합니다.

### Windows 버전 요구사항 오류가 날 때

2026-10-30 공식 문서의 최소 요구사항은 Windows 10 1809 이상 또는 Windows Server 2019 이상입니다. 빌드 17763이 Windows 10 1809입니다. 예전에 `requires Windows 10 version 2004 or later (build 19041+)` 오류를 봤다면 최신 설치 명령으로 다시 시도합니다. 같은 오류가 계속되면 오류 화면 전체를 [Claude에게 물어보기](#막혔을-때-claude에게-화면째-물어보기)로 보냅니다.

### 설치 스크립트가 HTML이나 403을 돌려줄 때

아래 오류는 설치 주소가 스크립트 대신 웹페이지나 오류를 돌려줬다는 뜻입니다.

- Bash·Zsh: `syntax error near unexpected token '<'`
- CMD: `< was unexpected at this time.`
- PowerShell: `System.Xml.XmlDocument` 또는 HTML 태그가 섞인 `ParserError`
- 공통: `curl: (22) The requested URL returned error: 403`

해결 순서입니다.

:::steps
1. 몇 분 기다렸다가 같은 명령을 다시 실행합니다. 일시적인 경우가 많습니다.
2. 다운로드 서버에 닿는지 확인합니다. 아래 명령의 첫 줄에 `200`이 나오면 정상입니다.
3. `403`이 나오면 회사 프록시나 방화벽이 막고 있을 가능성이 큽니다. IT 담당자에게 `downloads.claude.ai` 접속을 확인합니다.
4. 다른 설치 방법을 씁니다. macOS는 `brew install --cask claude-code`, Windows는 `winget install Anthropic.ClaudeCode`입니다.
:::

```bash
# macOS·Linux
curl -sI https://downloads.claude.ai/claude-code-releases/latest
```

```powershell
# Windows PowerShell (curl 대신 curl.exe)
curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest
```

Homebrew와 WinGet으로 설치한 Claude Code는 기본값으로는 자동 업데이트되지 않습니다. 업데이트 방법은 [업데이트와 설치가 두 개일 때](#업데이트와-설치가-두-개일-때)에 있습니다.

### App unavailable in region

Claude Code를 쓸 수 없는 국가에서 접속했다는 뜻입니다. 한국은 Anthropic 지원 국가 목록에 있습니다. 한국에서 이 메시지가 나오면 바로 위 섹션의 연결 확인 명령으로 `403` 여부를 봅니다. `403`은 프록시·네트워크 필터가 막거나 지원하지 않는 지역에서 접속할 때 나옵니다. 지원 국가 목록은 [Anthropic 지원 국가](https://www.anthropic.com/supported-countries)에서 확인합니다.

### 로그인했는데 API Error 400 This organization has been disabled가 날 때

구독이 활성 상태인데 `API Error: 400 ... "This organization has been disabled"`가 나오면 `ANTHROPIC_API_KEY` 환경 변수가 구독 로그인을 덮어쓰고 있습니다. 예전 회사나 프로젝트의 API 키가 남아 있을 때 자주 생깁니다.

```bash
# macOS·Linux
unset ANTHROPIC_API_KEY
claude
```

```powershell
# Windows PowerShell
Remove-Item Env:ANTHROPIC_API_KEY
claude
```

위 명령은 지금 창에서만 키를 지웁니다. 영구적으로 지우려면 macOS·Linux는 `~/.zshrc`, `~/.bashrc`, `~/.profile`에서 `export ANTHROPIC_API_KEY=...` 줄을 지웁니다. Windows는 PowerShell 프로필(`$PROFILE`)과 사용자 환경 변수에서 `ANTHROPIC_API_KEY`를 지웁니다. Claude Code 안에서 `/status`를 실행하면 어떤 로그인 방법을 쓰는지 보입니다.

### macOS에서 Keychain이 잠겨 로그인이 저장되지 않을 때

macOS에서 Claude Code는 로그인 정보를 Keychain에 저장합니다. SSH 접속 중이거나 Keychain 암호가 계정 암호와 다르면 Keychain에 쓰지 못합니다.

:::steps
1. `claude doctor`를 실행합니다. `macOS Keychain is not writable`로 시작하는 경고가 있는지 봅니다.
2. 경고가 있으면 아래 명령으로 Keychain 잠금을 풉니다. 암호를 물으면 Keychain 암호를 입력합니다.
3. `claude doctor`를 다시 실행해 경고가 사라졌는지 봅니다.
4. 그래도 남으면 Keychain Access 앱에서 `login` 키체인을 고르고 "편집 > 키체인 'login'의 암호 변경"으로 계정 암호와 맞춥니다.
5. Claude Code 안에서 `/logout` 후 `/login`을 실행합니다.
:::

```bash
security unlock-keychain ~/Library/Keychains/login.keychain-db
```

`/logout`은 저장된 MCP 서버 로그인과 플러그인 비밀값도 지웁니다. 로그인 후 다시 입력해야 합니다.

### 원인을 모를 때: claude doctor

셸에서 `claude doctor`를 실행합니다. 세션을 시작하지 않고 설치 상태, 설정 파일 오류, 수정 제안이 붙은 경고를 출력합니다. 마지막 자동 업데이트 결과도 보여 줍니다.

```bash
claude doctor
```

Claude Code가 실행된다면 안에서 `/doctor`를 입력해도 됩니다. 설치, 설정, 확장, 컨텍스트 사용량을 점검하고, 확인을 받은 뒤 적용할 수정 사항을 제안합니다.

그래도 풀리지 않으면 다음 섹션처럼 Claude에게 화면을 통째로 보여 줍니다.

## 막혔을 때 Claude에게 화면째 물어보기

어느 단계에서 멈췄든 터미널 화면 전체를 Claude 채팅에 붙여넣으면 됩니다. Claude가 내 운영체제와 화면 상태에 맞춰 PATH, 권한, 빠진 프로그램을 진단합니다.

:::steps
1. PowerShell이나 터미널 창의 글자를 처음부터 끝까지 선택해 복사합니다. Windows PowerShell은 마우스로 드래그한 뒤 오른쪽 클릭하면 복사됩니다. macOS는 `Cmd + A` 후 `Cmd + C`를 누릅니다.
2. 브라우저에서 [claude.ai](https://claude.ai)에 로그인해 새 채팅을 엽니다. Claude 데스크톱 앱을 써도 됩니다.
3. 아래 메시지와 복사한 화면을 함께 붙여넣고 보냅니다.
4. Claude가 알려 준 명령을 실행합니다.
5. 터미널 창을 닫고 새로 연 뒤 `claude --version`을 다시 실행합니다.
:::

```text
Claude Code CLI 설치하다 막혔어. 아래는 내가 PowerShell(또는 터미널)에서 본 화면 전체야.
어디서 멈췄고 어떻게 해결해야 하는지 알려줘.
---
[여기에 복사한 화면 통째로 붙여넣기]
```

설치가 끝난 뒤라면 터미널 안의 Claude Code에게도 한국어로 같은 질문을 할 수 있습니다.

## 업데이트와 설치가 두 개일 때

이 문서의 설치 명령으로 설치한 Claude Code는 백그라운드에서 자동으로 업데이트됩니다. 바로 업데이트하려면 `claude update`를 실행합니다.

Table: 설치 방법별 업데이트 명령
| 설치 방법 | 자동 업데이트 | 수동 업데이트 명령 |
|---|---|---|
| 설치 명령(curl, irm, install.cmd) | 예 | `claude update` |
| Homebrew | 아니요 | `brew upgrade claude-code` |
| WinGet | 아니요 | `winget upgrade Anthropic.ClaudeCode` |
| npm | 아니요 | `npm install -g @anthropic-ai/claude-code@latest` |

화면 아래에 `Update available! Run: winget upgrade Anthropic.ClaudeCode`가 보이는데 설치 명령으로도 설치했다면, Claude Code가 두 개 설치된 상태일 수 있습니다. 두 설치가 섞이면 `claude --version`과 실제 실행되는 버전이 다를 수 있습니다. 어떤 `claude`가 있는지 확인합니다.

```powershell
# Windows PowerShell
where.exe claude
```

```bash
# macOS·Linux
which -a claude
```

공식 문서는 설치 명령으로 설치한 쪽 하나만 남기도록 권장합니다. 나머지는 설치한 방법에 맞춰 지웁니다.

- WinGet으로 설치한 경우: `winget uninstall Anthropic.ClaudeCode`
- npm으로 설치한 경우: `npm uninstall -g @anthropic-ai/claude-code`
- Homebrew로 설치한 경우: `brew uninstall --cask claude-code`

## 설치한 다음에 볼 것

- 첫 작업을 따라 해 보려면 공식 [빠른 시작](https://code.claude.com/docs/ko/quickstart)을 봅니다.
- 비개발자가 Claude Code로 처음 일하는 방법은 [비개발자가 클로드코드로 코딩하는 법](/blog/claude-code-intro-for-non-developers/)에 있습니다.
- 사용량 한도에 걸렸을 때는 [클로드코드 리밋 걸렸을 때](/blog/claude-code-limit-extra-usage/)를 봅니다.