Using Claude

Claude Code 설치 가이드: native vs npm, Windows까지

Claude Code 설치 방법(native/npm)과 사전 준비물, Windows WSL2 설정, 인증, 설치 직후 권장 작업(CLAUDE.md)까지 단계별로 정리했습니다.

Claude Code는 터미널에서 작동하는 코딩 에이전트입니다. 2026년 기준 설치는 native installer가 권장되며, 과거 npm 글로벌 설치는 deprecated 됐습니다. Windows에서도 2025년 말부터 native로 직접 지원돼 WSL2 없이도 쓸 수 있습니다. 이 가이드는 macOS, Linux, Windows 전부 다룹니다.

구독 플랜 먼저 확인

Claude Code는 무료 플랜에선 사용할 수 없습니다. 다음 중 하나가 필요합니다.

  • Pro ($20/월): 개인 일반 사용
  • Max 5x ($100/월): 거의 매일 코딩
  • Max 20x ($200/월): 풀타임 코딩, 멀티 에이전트
  • Team / Enterprise: 조직 단위
  • Anthropic Console (API 종량제): API 키로 사용 (구독 대신)

⚠️ ANTHROPIC_API_KEY 환경 변수가 설정돼 있으면 Pro/Max 구독 대신 API 키로 결제됩니다. 구독 사용을 원하면 키를 unset 하고 실행하세요.

시스템 요구 사항

  • macOS: 13.0 (Ventura) 이상
  • Linux: Ubuntu 20.04+ 또는 Debian 10+
  • Windows: Windows 10 1809+ 또는 Windows Server 2019+ (PowerShell, CMD, Git Bash 또는 WSL2)
  • RAM: 최소 4GB (8GB 권장)
  • 인터넷: Anthropic 클라우드 API 통신 필요
  • GPU: 불필요 (모든 추론은 Anthropic 서버)

1. macOS / Linux 설치 (native, 권장)

가장 빠른 방법입니다. Node.js 같은 의존성 없이 단일 바이너리로 설치되고, 백그라운드 자동 업데이트됩니다.

curl -fsSL claude.ai/install.sh | sh

설치 후 새 터미널에서 검증:

claude --version
claude doctor

claude doctor는 설치 상태·PATH·권한·네트워크를 점검해 문제를 알려줍니다. 처음에 가장 먼저 실행해보세요.

2. Windows native 설치 (2025년 말 이후 공식 지원)

PowerShell에서 한 줄로 끝납니다.

irm claude.ai/install.ps1 | iex

완료 후 새 PowerShell 창에서:

claude --version
claude doctor

Git for Windows가 있으면 Git Bash에서도 동작합니다. 없으면 PowerShell로 자동 폴백합니다.

3. Windows WSL2 설치 (MCP 서버 호환성 우선)

MCP 서버 생태계가 macOS/Linux 기반으로 작성된 게 많아, MCP를 적극 활용한다면 WSL2가 더 안전합니다.

  1. 관리자 PowerShell에서: wsl --install (재시작 필요할 수 있음)
  2. Ubuntu가 기본 배포판으로 설치됨. Windows Terminal에서 Ubuntu 탭 열기
  3. Ubuntu 안에서 macOS/Linux와 같은 native 설치 명령 실행

⚠️ 프로젝트는 Windows 파일시스템(/mnt/c/...) 대신 Linux 파일시스템(~/projects/)에 두세요. 파일 I/O가 5~10배 빨라집니다.

4. npm 설치 (deprecated, 폴백용)

2026년 기준 npm 설치는 더 이상 권장되지 않지만 여전히 가능합니다. 특정 버전 고정이 필요한 경우에만 사용하세요.

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

Node.js 18 이상이 필요합니다. sudo를 절대 쓰지 마세요 — 권한 오류가 나면 sudo가 답이 아니라 nvm 사용이 정답입니다.

첫 실행 + 로그인

cd ~/your-project
claude

처음 실행 시 브라우저 창이 자동으로 열리며 Anthropic 계정 로그인을 요구합니다. 로그인 후 터미널로 돌아가면 인증이 완료되고 작업을 시작할 수 있습니다.

자주 발생하는 문제 해결

  • claude: command not found: 새 터미널 열기 → 안 되면 ~/.zshrc나 ~/.bashrc에 PATH 추가 확인
  • MCP 서버가 spawn npx ENOENT 에러: Windows native에서 자주 발생. WSL2로 전환 또는 Node.js LTS 재설치 후 PATH 갱신
  • API 키와 구독이 충돌: echo $ANTHROPIC_API_KEY로 확인. 구독을 쓰려면 unset ANTHROPIC_API_KEY
  • 업데이트 안 됨: claude update 또는 native 재설치

다음 단계

설치가 끝났으면:

출처: Anthropic Claude Code 공식 문서, Anthropic 발표(claude.ai/install). 정보는 2026년 5월 기준이며, 설치 방법은 업데이트될 수 있습니다.