# 설치 전에 깔아야 할 프로그램은 0개입니다 — 비개발자를 위한 클로드 코드 설치, 명령어 한 줄

클로드 코드 설치 방법을 맥·윈도우별로. 명령어 한 줄, Python·Node.js 없이 설치하고 오류까지.

- source: https://polroute.com/posts/claude-code-install-for-beginners/
- category: AI 워크플로우
- published: 2026-09-20

---

결론부터 말씀드립니다. Claude Code(클로드 코드) 설치는 명령어 한 줄이면 끝나고 그 전에 따로 깔아야 하는 프로그램은 하나도 없습니다.

맥이라면 이 줄입니다.

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

윈도우라면 이 줄입니다.

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

이 글을 찾아오신 분들이 진짜로 막히는 지점은 명령어 자체가 아니라 이 줄을 어디에 쳐야 하는지입니다. 대부분의 설치 가이드가 "터미널을 여세요"로 시작하는데, 터미널을 한 번도 열어본 적 없는 사람에게는 그 한 문장이 벽입니다.

그래서 이 글은 그 한 줄 앞에서 시작합니다. 검은 창이 무엇이고 어디서 여는지, 무엇이 나오면 성공인지까지 다룹니다.

> 2026년 9월 기준입니다. 명령어와 오류 메시지는 [공식 문서](https://code.claude.com/docs/en/quickstart)를 기준으로 삼았고 실행 결과는 필자의 맥(Claude Code v2.1.278)에서 직접 확인했습니다.

## 먼저 확인할 것 두 가지

설치를 시작하기 전에 확인할 게 두 가지 있습니다. 여기서 걸리면 명령어를 백 번 쳐도 안 됩니다.

**1. 내 컴퓨터가 되는지**

공식 문서가 명시한 최소 사양입니다.

| 항목 | 요구 사양 |
|---|---|
| 맥 | macOS 13.0 이상 |
| 윈도우 | Windows 10 1809 이상 (또는 Windows Server 2019 이상) |
| 리눅스 | Ubuntu 20.04+ / Debian 10+ / Alpine 3.19+ |
| 메모리 | 4GB 이상 |
| 프로세서 | x64 또는 ARM64 |

맥 버전은 화면 왼쪽 위 사과 메뉴 → '이 Mac에 관하여'에서 확인합니다. macOS 13은 2022년 10월에 나온 버전입니다.

이 표에서 눈여겨볼 건 없는 항목입니다. Python도 Node.js도 Git도 요구 사양에 없습니다.

**2. 내 계정으로 되는지**

이쪽이 실제로 더 많이 걸립니다. **무료 claude.ai 계정으로는 Claude Code를 쓸 수 없습니다.** 공식 문서에 이렇게 적혀 있습니다.

> The free claude.ai plan does not include Claude Code access.

필요한 것은 Pro, Max, Team, Enterprise 구독 중 하나, 또는 Claude Console 계정(API 크레딧 선결제)입니다. 설치는 무료 계정으로도 되지만 로그인 단계에서 막힙니다. 다 깔아놓고 나중에 알면 시간만 버리니 지금 확인해 두세요.

## 검은 창을 여는 법

터미널은 명령어를 글자로 입력하는 창입니다. 마우스로 클릭할 게 없고 타이핑한 다음 엔터를 치면 컴퓨터가 그 줄을 실행합니다. 그게 전부입니다.

**맥에서 여는 법**

1. `⌘ + 스페이스`를 누릅니다. 화면 가운데 검색창이 뜹니다.
2. `터미널`이라고 칩니다. (영문 환경이면 `Terminal`)
3. 엔터를 누릅니다.

흰색이나 검은색 창이 하나 뜨고 커서가 깜빡이면, 그게 터미널입니다.

**윈도우에서 여는 법**

1. `Win + X`를 누릅니다. 작업 표시줄 근처에 메뉴가 뜹니다.
2. 목록에서 **Windows PowerShell** 또는 **터미널**을 클릭합니다.

시작 메뉴에서 `PowerShell`을 검색해도 됩니다. 다만 검색 결과에 **`Windows PowerShell (x86)`이 같이 뜨는데, 이건 누르면 안 됩니다.** 64비트 컴퓨터에서 x86 쪽을 열면 설치할 때 `Claude Code does not support 32-bit Windows`라는 오류가 납니다. 이름 뒤에 `(x86)`이 안 붙은 항목을 여세요.

## 윈도우는 검은 창이 두 종류입니다

맥 사용자는 이 단락을 건너뛰셔도 좋습니다. 윈도우 독자의 절반이 여기서 갈립니다.

윈도우에는 명령어를 입력하는 프로그램이 PowerShell과 CMD 두 가지 있습니다. 생긴 게 거의 똑같은데 쓰는 명령어가 다릅니다. 지금 내가 어느 쪽에 있는지는 커서 앞에 붙은 글자로 구분합니다.

```text
PS C:\Users\내이름>     ← PS가 붙어 있으면 PowerShell
C:\Users\내이름>        ← PS가 없으면 CMD
```

잘못 열었을 때 나오는 오류 메시지도 정해져 있습니다.

| 나온 오류 | 실제 상황 | 할 일 |
|---|---|---|
| `'irm' is not recognized as an internal or external command` | CMD인데 PowerShell 명령을 침 | PowerShell을 열거나 아래 CMD용 명령어 사용 |
| `The token '&&' is not a valid statement separator` | PowerShell인데 CMD 명령을 침 | 위의 `irm` 명령어 사용 |

CMD에서 그대로 설치하고 싶다면 이 명령어를 씁니다.

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

## 설치: 명령어 한 줄

창을 열었으면 이제 한 줄입니다. 타이핑하지 말고 **복사해서 붙여넣으세요.** 오타 하나가 그대로 오류가 됩니다.

맥·리눅스·WSL 환경 (붙여넣기는 `⌘ + V`):

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

윈도우 PowerShell (붙여넣기는 `Ctrl + V` 또는 마우스 오른쪽 클릭):

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

붙여넣고 엔터를 치면 글자가 주르륵 올라갑니다. 다 끝나면 `Claude Code successfully installed!`가 나옵니다.

## 제대로 깔렸는지 확인하기

설치가 끝났다는 메시지를 못 봤거나 못 믿겠으면 이 명령어를 칩니다.

```bash
claude --version
```

필자의 맥에서는 이렇게 나옵니다.

```text
2.1.278 (Claude Code)
```

버전 숫자 뒤에 `(Claude Code)`가 붙어야 제대로 설치된 것입니다. 숫자는 사람마다 다른데, 매주 새 버전이 나오기 때문입니다.

더 자세히 보고 싶으면 이 명령어도 있습니다.

```bash
claude doctor
```

Claude Code를 실행하지 않고 설치 상태와 설정 문제만 점검해서 보여줍니다. 나중에 뭔가 이상할 때 제일 먼저 쳐볼 명령어입니다.

## 필요한 것과 필요 없는 것

국내 설치 가이드 중에는 Node.js를 먼저 설치하게 하거나, VS Code에 Python 확장을 깔게 하는 글이 있습니다. 따라 하다 보면 설치 전에 프로그램을 세 개쯤 깔게 됩니다.

틀렸다기보다 기준이 다른 경로입니다. 예전에는 Claude Code를 npm(개발자들이 프로그램을 설치할 때 쓰는 도구)으로 설치했고, 그 경로는 Node.js(자바스크립트를 실행해 주는 프로그램)가 필요합니다. 지금 공식 문서가 권장하는 네이티브 설치는 그쪽이 아닙니다.

| | 필요한가 | 설명 |
|---|---|---|
| 터미널 (PowerShell) | **필요** | 윈도우·맥 모두 기본 설치돼 있습니다 |
| Pro·Max·Team·Enterprise 또는 Console 계정 | **필요** | 무료 계정은 사용 불가 |
| **Python** | 필요 없음 | 네이티브·npm 어느 경로에서도 쓰지 않습니다 |
| **Node.js** | 필요 없음 | npm 설치를 고집할 때만 필요(v2.1.198부터 Node.js 22 이상) |
| Git for Windows | 선택 | 없으면 PowerShell이 셸(명령어를 받아 실행하는 프로그램)로 쓰입니다 |
| WSL(윈도우 안에서 리눅스를 돌리는 기능) | 필요 없음 | 윈도우에서 그냥 설치됩니다 |

사전에 깔아야 할 프로그램은 0개입니다. 제목의 숫자는 여기서 나왔습니다.

## 설치 방식 4가지 — 진짜 차이는 자동 업데이트

방법이 여러 개라 헷갈리지만 실제로 갈리는 건 하나, 알아서 최신 버전이 되느냐입니다.

| 방식 | 명령어 | 자동 업데이트 |
|---|---|---|
| 네이티브 (권장) | 위의 한 줄 | **됩니다** |
| Homebrew (맥) | `brew install --cask claude-code` | 안 됩니다 |
| WinGet (윈도우) | `winget install Anthropic.ClaudeCode` | 안 됩니다 |
| npm | `npm install -g @anthropic-ai/claude-code` | 조건부 |

Homebrew나 WinGet으로 깔면 직접 올려야 합니다.

```bash
brew upgrade claude-code          # 맥
winget upgrade Anthropic.ClaudeCode   # 윈도우
```

Homebrew를 쓸 거라면 cask가 두 개라는 점도 알아두세요. `claude-code`는 안정 채널이라 최신보다 일주일 정도 뒤처지는 대신 큰 문제가 있는 버전을 건너뜁니다. `claude-code@latest`는 나오는 즉시 받습니다.

처음 설치하신다면 네이티브 한 줄을 권합니다. 업데이트를 신경 쓸 일이 없습니다.

## 로그인

설치가 끝났으면 실행합니다.

```bash
claude
```

처음 실행하면 로그인하라고 나옵니다. 안내를 따라가면 브라우저가 열리고 거기서 로그인하면 터미널로 돌아옵니다. 한 번 하면 다음부터는 안 물어봅니다.

계정을 바꾸고 싶으면 Claude Code가 실행된 상태에서 `/login`을 칩니다.

여기까지 왔으면 설치는 끝났습니다. 이제 한글로 질문하면 답이 옵니다. 몇 가지만 알아두세요.

- 터미널 안에서는 클릭이 안 됩니다. 방향키로 움직입니다.
- Claude가 뭔가 하는 중에 멈추고 싶으면 `Esc`입니다.
- 나가려면 `/exit`을 치거나 `Ctrl + D`를 두 번 누릅니다.
- 뭘 할 수 있는지 모르겠으면 `/help`입니다.

## 여기서 막힙니다

설치가 한 번에 되면 좋겠지만 안 될 때가 있습니다. 공식 문제 해결 문서의 오류 목록에서 맨 첫 줄에 있는 오류부터 순서대로 정리했습니다. 그만큼 자주 납니다.

**1. `command not found: claude` / `'claude' is not recognized`**

가장 흔합니다. 설치는 됐는데 컴퓨터가 `claude`라는 파일이 어디 있는지 모르는 상태라, 위치를 직접 알려주면 해결됩니다. 필자의 맥에서는 `~/.local/bin/claude`에 들어가 있었습니다.

맥(zsh):

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

윈도우 PowerShell:

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

그다음 **창을 닫고 새로 여세요.** 기존 창에서는 반영이 안 됩니다.

**2. `syntax error near unexpected token '<'` 또는 `403`**

명령어가 설치 스크립트 대신 웹페이지를 받아온 경우입니다. 한 번 더 실행해 본 뒤 계속 같으면 Homebrew로 설치합니다. 받아온 페이지에 `App unavailable in region`이라고 적혀 있다면 해당 국가에서 서비스되지 않는다는 뜻이라 명령어 문제가 아닙니다.

**3. `dyld: cannot load` 또는 `built for Mac OS X 13.0`**

맥 버전이 낮습니다. 사과 메뉴 → '이 Mac에 관하여'에서 확인하고 13.0 미만이면 macOS를 업데이트합니다.

**4. `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell`**

셸을 하나도 못 찾은 경우입니다. `powershell.exe`가 `C:\Windows\System32\WindowsPowerShell\v1.0\` 경로에 있는지 확인하거나, [Git for Windows](https://git-scm.com/downloads/win)를 설치합니다.

여기 없는 오류는 공식 [문제 해결 문서](https://code.claude.com/docs/en/troubleshoot-install)에 오류 메시지별 표로 정리돼 있습니다. 터미널에 뜬 문장을 그대로 찾으면 됩니다.

## 터미널이 답이 아닐 때도 있습니다

지금까지 터미널 기준으로 썼지만, 터미널을 안 쓰는 방법도 있습니다.

Claude Code에는 데스크톱 앱이 있습니다. 공식 문서도 설치 안내 첫머리에 이 문장을 달아 뒀습니다.

> Don't want to use the terminal? The Claude Code desktop app lets you skip the terminal entirely.
> (터미널을 쓰고 싶지 않으신가요? 데스크톱 앱을 쓰면 터미널을 통째로 건너뛸 수 있습니다.)

맥·윈도우·리눅스 모두 지원하고, VS Code 확장과 JetBrains 플러그인, 웹(claude.ai/code)까지 있습니다.

그런데도 이 시리즈가 터미널로 가는 건 이어지는 글들이 전부 터미널 화면을 기준으로 쓰이기 때문입니다. CLAUDE.md, 스킬, 훅, 권한 모드는 데스크톱 앱과 VS Code에서도 쓸 수 있지만, 설명하고 따라 하기에는 터미널 쪽이 가장 깔끔합니다. 지금 검은 창에 10분 투자하면 앞으로 읽을 글이 그대로 통합니다.

"일단 뭔지만 보고 싶다"면 데스크톱 앱이 빠릅니다. "제대로 쓸 생각"이라면 터미널을 권합니다.

설치 전에 Cursor 같은 다른 도구와 저울질 중이시라면 [Claude Code가 있는데 Cursor를 또 결제해야 할까](/posts/cursor-vs-claude-code/)를 먼저 읽어보셔도 좋습니다.

## 다음 편

창은 열었고 설치도 됐습니다. 그런데 커서만 깜빡이는 화면 앞에서 또 막힙니다. 뭘 쳐야 하는지가 다음 문제입니다.

그 전에 알아둘 게 있습니다. Claude Code는 지금 열려 있는 폴더를 기준으로 움직입니다. 엉뚱한 폴더에서 실행하면 엉뚱한 파일을 읽습니다. 다음 편은 그 폴더와 경로 이야기입니다.