본문으로 건너뛰기

설치 가이드

💡 이 챕터에서 배우는 것: Claude Code 설치 전 준비물, OS별 설치 방법, 설치 확인

전제 지식

이 챕터를 시작하기 전에 필요한 것:

  • 인터넷 연결
  • 터미널(명령 프롬프트/PowerShell/Terminal) 기본 사용법

시스템 요구사항​

항목최소 사양
macOS13.0 (Ventura) 이상
Windows10 (1809) 이상 + Git for Windows
LinuxUbuntu 20.04+ / Debian 10+ 등 glibc 기반
RAM4GB 이상
셸Bash, Zsh, PowerShell, CMD 중 하나
Node.js 불필요

네이티브 설치(권장)는 Node.js가 필요 없습니다. Node.js는 npm 설치(레거시) 방식에서만 필요합니다.

Claude Code 설치​

방법 1: 네이티브 설치 (권장)​

자동 업데이트를 지원하며, Node.js 없이 설치할 수 있는 권장 방법입니다.

macOS / Linux / WSL:

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

Windows PowerShell:

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

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Windows 사전 준비

Windows에서는 **Git for Windows**가 필요합니다. 없다면 먼저 설치하세요.

방법 2: 패키지 매니저​

Homebrew (macOS):

brew install --cask claude-code

WinGet (Windows):

winget install Anthropic.ClaudeCode
자동 업데이트 미지원

Homebrew/WinGet 설치는 자동 업데이트가 되지 않습니다. brew upgrade claude-code 또는 winget upgrade Anthropic.ClaudeCode로 직접 업데이트하세요.

레거시: npm 설치 (비권장)

Node.js 18 이상이 필요하며, 네이티브 설치가 권장됩니다.

npm install -g @anthropic-ai/claude-code

-g 옵션: 전역(global) 설치. 어느 디렉토리에서든 claude 명령을 사용할 수 있습니다.

설치 확인​

claude --version

정상 출력 예 (버전 번호는 설치 시점에 따라 다릅니다):

1.x.x (Claude Code)

더 상세한 진단이 필요하면:

claude doctor

첫 실행 및 로그인​

cd your-project
claude

처음 실행하면 브라우저가 열리면서 로그인 화면이 나타납니다:

  • claude.ai 계정 (Pro/Max/Team/Enterprise) 또는
  • Anthropic Console 계정 (API 과금)

으로 로그인하면 인증이 완료됩니다.

구독 플랜

Claude Code는 Pro, Max, Team, Enterprise 유료 플랜에서 사용 가능합니다. 무료 플랜으로는 사용할 수 없습니다. API 키 방식도 지원하며, 자세한 내용은 다음 챕터에서 설명합니다.

자주 겪는 설치 문제​

문제 1: claude: command not found​

터미널을 완전히 닫고 다시 열어보세요. PATH 환경변수가 새로 적용됩니다. 그래도 안 되면 claude doctor로 진단하세요.

문제 2: EACCES: permission denied (macOS/Linux, npm 설치 시)​

mkdir ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

네이티브 설치를 사용하면 이 문제가 발생하지 않습니다.

문제 3: 회사 네트워크에서 설치 실패​

프록시 설정이 필요할 수 있습니다:

# npm 설치 시
npm config set proxy http://프록시주소:포트
npm config set https-proxy http://프록시주소:포트

문제 4: Windows PowerShell 실행 정책 오류​

# PowerShell을 관리자 권한으로 열고 실행
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

핵심 정리​

  • 네이티브 설치가 권장 — Node.js 불필요, 자동 업데이트
  • macOS/Linux: curl ... | bash / Windows: irm ... | iex
  • 설치 후 claude --version으로 확인
  • 첫 실행 시 브라우저 로그인으로 인증
  • 유료 플랜 (Pro/Max/Team/Enterprise) 필요

다음 단계​

→ API 키 설정 — Anthropic Console에서 API 키를 발급하고 설정합니다

최종 수정: 에