AI 코딩 도구 설치·레퍼런스 (1/7) — Claude Code 설치: macOS·Linux·WSL·Windows 한 페이지
공식 문서 기준 모든 설치 경로 · 시스템 요구사항 · 인증 · 첫 세션까지
핵심 요약
- 대상 독자: Claude Code를 처음 설치하는 개발자·비개발자.
- 얻을 것: 5가지 설치 방법 비교, 플랫폼별 verbatim 명령어, 인증 옵션 4종, 첫 세션 진입까지 10분 안에.
- 선행 조건: Claude Pro/Max/Team/Enterprise 구독 또는 Anthropic Console API 계정 (무료 Claude.ai 플랜은 Claude Code 사용 불가).
1. 설치 방법 한눈에
공식 문서는 5가지 설치 경로를 제공한다. 플랫폼과 목적에 따라 하나를 선택한다.
| 방법 | 플랫폼 | 자동 업데이트 | 권장 상황 |
|---|---|---|---|
| Native Install (권장) | macOS, Linux, WSL, Windows | ✅ 백그라운드 자동 | 대부분의 개인 개발 환경 |
| Homebrew | macOS, Linux | ❌ 수동 | Homebrew로 툴 관리 중인 경우 |
| WinGet | Windows | ❌ 수동 | 회사 정책상 WinGet 필수 환경 |
| Linux 패키지 (apt/dnf/apk) | Debian/Ubuntu, Fedora/RHEL, Alpine | ❌ 시스템 업그레이드와 함께 | 서버 자동화 / 배포 파이프라인 |
| npm (deprecated) | 모든 플랫폼 | ❌ 수동 (npm update) |
Node 기반 워크플로가 이미 있을 때만 |
공식 README는 npm 설치를 deprecated로 표시한다. 기존 npm 설치 사용자도 native installer로 전환 권장.
2. 시스템 요구사항
공식 문서가 명시한 2026-04-24 기준 요구사항:
- OS
- macOS 13.0+
- Windows 10 1809+ 또는 Windows Server 2019+
- Ubuntu 20.04+ / Debian 10+ / Alpine Linux 3.19+
- 하드웨어: 4GB+ RAM, x64 또는 ARM64
- 셸: Bash, Zsh, PowerShell, CMD
- Native Windows는 Git for Windows 필수
- WSL은 별도 Git 불필요
- 네트워크: Anthropic 지원 국가에서 인터넷 연결 (한국 포함)
- 의존성:
ripgrep은 바이너리에 내장. Alpine/musl 계열은 별도 설치 필요 (아래 2.1 참고)
2.1 Alpine / musl 계열 추가 절차
Alpine Linux 같은 musl 기반 배포판은 네이티브 ripgrep이 깨지므로 시스템 ripgrep을 사용한다.
apk add libgcc libstdc++ ripgrep
그리고 ~/.claude/settings.json에 다음 항목을 추가한다.
{
"env": {
"USE_BUILTIN_RIPGREP": "0"
}
}
3. 설치 — 플랫폼별 verbatim 명령어
3.1 macOS / Linux / WSL — Native Install
curl -fsSL https://claude.ai/install.sh | bash
설치 후 셸을 다시 열거나 source ~/.bashrc(또는 ~/.zshrc)로 PATH를 리로드한다. 기본 경로는 ~/.local/bin/claude.
특정 버전 고정이 필요하면:
curl -fsSL https://claude.ai/install.sh | bash -s stable
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89
3.2 Windows — PowerShell
irm https://claude.ai/install.ps1 | iex
프롬프트가 PS C:\>로 시작하면 PowerShell이다. 'irm' is not recognized라는 오류가 나면 CMD에서 실행 중이므로 CMD용 명령을 대신 쓴다.
3.3 Windows — CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
프롬프트가 C:\>(PS 없음)면 CMD다. The token '&&' is not a valid statement separator가 나오면 PowerShell에서 실행 중이므로 PS용 명령으로 전환.
Native Windows는 Git for Windows가 먼저 설치되어 있어야 한다. 관리자 권한은 필요 없다.
3.4 Homebrew (macOS / Linux)
Homebrew는 두 cask를 제공한다.
brew install --cask claude-code # stable 채널 (약 1주 지연, 회귀 스킵)
brew install --cask claude-code@latest # latest 채널 (릴리즈 직후)
자동 업데이트가 없으므로 주기적으로 brew upgrade claude-code 또는 brew upgrade claude-code@latest 실행.
3.5 WinGet (Windows)
winget install Anthropic.ClaudeCode
업그레이드는 수동: winget upgrade Anthropic.ClaudeCode.
3.6 Linux 패키지 매니저
Debian/Ubuntu(apt), Fedora/RHEL(dnf), Alpine(apk)에서 서명된 저장소를 제공한다.
Debian / Ubuntu (apt)
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
-o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
| sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code
GPG 지문 검증:
gpg --show-keys /etc/apt/keyrings/claude-code.asc
Fedora / RHEL (dnf)
sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code
Alpine (apk)
wget -O /etc/apk/keys/claude-code.rsa.pub \
https://downloads.claude.ai/keys/claude-code.rsa.pub
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code
3.7 npm (deprecated)
Node.js 18+ 환경에서만 동작. 공식은 deprecated로 표시하지만 기존 워크플로에 남아있는 경우가 있다.
npm install -g @anthropic-ai/claude-code
sudo npm install -g는 권한·보안 이슈가 생기므로 피한다.
4. 설치 검증
설치가 끝났으면 두 명령으로 확인.
claude --version
claude doctor
claude doctor는 Node 버전, PATH, 권한, MCP 접근성 등을 점검한다. 무언가 붉은 글씨로 뜨면 공식 트러블슈팅 페이지를 참조한다.
5. 인증 — 4가지 옵션
Claude Code는 무료 Claude.ai 플랜으로는 사용할 수 없다. 다음 중 하나가 필요하다.
| 옵션 | 대상 | 과금 | 설정 방법 |
|---|---|---|---|
| Claude Pro / Max / Team / Enterprise 구독 | 개인·팀 | 구독료 정액 | claude 실행 → 브라우저 로그인 |
| Anthropic Console (API key) | 크레딧 선지불 | 사용량 과금 | Console → Claude Code 워크스페이스 자동 생성 |
| Amazon Bedrock | 엔터프라이즈 AWS | AWS 과금 | Bedrock 설정 가이드 |
| Google Vertex AI | 엔터프라이즈 GCP | GCP 과금 | Vertex 설정 가이드 |
| Microsoft Foundry | 엔터프라이즈 Azure | Azure 과금 | Foundry 설정 가이드 |
처음 claude를 실행하면 로그인 프롬프트가 뜬다. 이후 전환은 /login 명령.
6. 첫 세션
cd /path/to/your/project
claude
프로젝트 디렉터리 안에서 실행하는 것이 기본이다. 환영 화면에서 다음 명령을 기억해두면 된다.
/help— 사용 가능한 명령 목록/login— 계정 전환/clear— 대화 기록 초기화exit또는Ctrl+D— 종료
기본 명령 치트시트
| 명령 | 동작 |
|---|---|
claude |
대화형 세션 시작 |
claude "task" |
1회성 작업 실행 후 종료 |
claude -p "query" |
1회 쿼리, 비대화형 (스크립트 친화) |
claude -c |
현재 디렉터리의 가장 최근 대화 이어가기 |
claude -r |
이전 대화 선택해서 재개 |
전체 CLI 레퍼런스는 공식 CLI 문서에 있다.
7. 자동 업데이트 & 릴리즈 채널
Native 설치는 백그라운드에서 자동 업데이트된다. 채널은 두 개:
latest(기본값) — 릴리즈 즉시 반영stable— 약 1주일 지연, 회귀 포함 버전 스킵
전환은 /config → Auto-update channel에서, 또는 settings.json에 직접 기록:
{
"autoUpdatesChannel": "stable"
}
자동 업데이트를 완전히 끄고 싶다면:
{
"env": {
"DISABLE_AUTOUPDATER": "1"
}
}
수동 업데이트는 claude update.
8. 제거
8.1 Native
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force
8.2 설정 파일까지 완전 제거
~/.claude와 .claude(프로젝트별)을 지우면 설정·허용 도구·MCP 서버·세션 기록이 모두 사라진다.
rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json
VS Code 확장, JetBrains 플러그인, Desktop 앱이 설치되어 있으면 이들을 먼저 제거해야 ~/.claude가 재생성되지 않는다.
9. 반대 시나리오 — 이 가이드가 맞지 않는 경우
- 회사 방화벽이 claude.ai 설치 스크립트를 차단한다 → Linux 패키지 매니저 경로(3.6) 사용. 서명된 저장소로 정책 통과 가능.
- 오프라인 환경이다 → Claude Code는 인터넷 연결 필수. 공식 문서 기준 완전 오프라인 모드는 없다.
- Node 기반 툴체인을 이미 운영 중이다 → npm 설치(3.7)가 여전히 작동하지만 deprecated이므로 장기적으론 native로 이주 권장.
- macOS 12 이하이다 → 공식 최소 버전은 macOS 13.0+. OS 업그레이드가 선행.
10. 다음 단계
설치가 끝났다면 다음 세 편을 순서대로 읽으면 된다.
- Claude Code 슬래시 커맨드 총정리 —
/help이상의 실전 명령 레퍼런스 (예정) - CLAUDE.md 작성 가이드 — 넣어야 할 것, 넣지 말아야 할 것 — 프로젝트 지침서 설계 (예정)
- Claude Code 훅(Hooks) 완전 가이드 — 생명주기 4종 × 실제 스크립트 — 자동화 (예정)
참고
이 글은 "AI 코딩 CLI 진입 가이드" 시리즈의 1/15 편입니다. 대상 툴: Claude Code · Codex CLI · OpenClaw · Hermes Agent. last verified: 2026-04-24 (Claude Code 공식 문서 기준).
시리즈 전체 안내: 시리즈 목차
댓글
댓글 쓰기