Claude Code 설치 가이드: irm 스크립트, npm 설정 및 https://claude.ai/install.ps1 사용법

소개

Claude Code는 AI 지원 코딩을 위한 제가 가장 선호하는 명령줄 도구입니다. Windows, macOS, Linux 어디서든 설치가 간단하며 여러 옵션이 있습니다:

• 네이티브 바이너리 (권장): Linux/macOS용 curl -fsSL https://claude.ai/install.sh | bash
• Windows PowerShell: Windows 사용자용 irm https://claude.ai/install.ps1 | iex
• npm 전역 설치: Node.js 환경용 npm install -g @anthropic-ai/claude-code

이 가이드에서는 각 설치 방법과 일반적인 문제를 진단하고 수정하기 위한 claude doctor 명령어 사용법을 자세히 다룹니다.

권장: 네이티브 바이너리

2025년 현재, Claude는 node.js와 bun.js를 포함한 여러 런타임에서 사용 가능합니다. Anthropic은 네이티브 바이너리 설치를 권장합니다. 이 방법은 패키지 관리자 충돌을 피하고 가장 안정적입니다.

네이티브 바이너리 설치하기

1. 설치 스크립트 실행:

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

2. 셸 설정 다시 로드:

   source ~/.bashrc
   # zsh 사용자의 경우:
   source ~/.zshrc

3. 설치 확인:

   claude --version
   claude doctor

완료입니다! Claude Code가 이제 ~/.claude/bin/claude 또는 ~/.local/bin/claude에 설치되었습니다.

문제 해결: 손상된 설치 수정하기

세그멘테이션 오류와 같은 문제가 발생한다면 혼합되거나 오래된 설치가 있을 가능성이 높습니다. 저처럼 처음부터 Claude를 사용해왔다면 node.js 또는 bun.js 버전이 설치되어 있을 수 있습니다. 다음은 수정 방법입니다:

claude doctor로 현재 설치 진단하기

claude doctor 명령어는 문제 해결의 첫 번째 단계입니다. 설치를 분석하고 잠재적인 문제를 보고합니다.

claude doctor

claude doctor가 확인하는 항목

claude doctor 명령어는 다음을 검사합니다:

• 설치 방법: 네이티브 바이너리, npm, Bun 또는 Homebrew
• 버전 정보: 현재 버전 및 업데이트 상태
• 자동 업데이트 기능: 업데이트 적용 가능 여부
• 검색 기능: ripgrep이 제대로 번들/설치되었는지
• 경로 설정: Claude가 PATH에 올바르게 있는지
• 실행 경로: 실행되는 실제 바이너리

일반적인 문제 출력

claude doctor 출력에서 다음 경고 신호를 주시하세요:

• unknown (2.0.0) - 버전 감지 실패, 혼합 설치 가능성
• Bun, npm, Node.js 간의 혼합 경로
• 호출 경로와 실행 경로가 다름
• 자동 업데이트 비활성화 또는 실패
• 검색 상태에 오류 표시

또한 충돌할 수 있는 여러 설치가 있는지 확인하세요:

which -a claude

모든 기존 설치 제거

# Bun 설치 제거
bun uninstall -g @anthropic-ai/claude-code
rm -f ~/.bun/bin/claude

# npm/Node.js 설치 제거
npm uninstall -g @anthropic-ai/claude-code

# nvm 특정 설치 제거
# 각 nvm Node 버전 확인
nvm list
# 각 버전에 대해 해당 버전으로 전환하고 제거
nvm use <version>
npm uninstall -g @anthropic-ai/claude-code

Homebrew로 Claude Code 제거

Homebrew를 통해 Claude Code를 설치한 경우:

# Homebrew에서 Claude Code 제거
brew uninstall claude-code

# 캐시된 파일 정리
brew cleanup claude-code

brew로 제거한 후 더 나은 자동 업데이트 지원을 위해 네이티브 바이너리 설치로 전환할 수 있습니다.

3단계: 설정 및 캐시 지우기

남아있는 설정 파일 제거:

# Claude Code 설정 디렉토리 제거
rm -rf ~/.claude-code
rm -rf ~/.config/claude-code
rm -rf ~/.cache/claude-code

4단계: 새로운 네이티브 바이너리 설치

이제 네이티브 바이너리를 설치합니다:

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

5단계: 수정 확인

설치 후 모든 것이 작동하는지 확인합니다:

# 버전 확인
claude --version

# 진단 실행
claude doctor

정상적인 설치는 다음을 표시해야 합니다:

• Version: native (2.0.x 이상)
• Config install method: native
• Auto-updates: enabled
• Search: OK (bundled)

대안 설치 방법

네이티브 바이너리가 권장되지만 다른 옵션도 있습니다:

npm 설치: npm install -g @anthropic-ai/claude-code

npm(Node Package Manager)을 선호한다면 Claude Code를 전역으로 설치할 수 있습니다. 이 방법은 Node.js 18 이상이 필요합니다.

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

npm install -g가 하는 일

-g 플래그는 패키지를 전역으로 설치하여 터미널 어디서나 claude를 명령어로 사용할 수 있게 합니다. @anthropic-ai/claude-code 패키지는 Anthropic에서 유지 관리하는 공식 npm 패키지입니다.

npm 설치의 장점:

• Node.js 개발자에게 익숙한 워크플로우
• 다른 전역 패키지와 함께 관리하기 쉬움
• 컨테이너화된/CI 환경에서 잘 작동

단점:

• Node.js 런타임 필요
• 다른 패키지 관리자(Bun, pnpm)와 충돌할 수 있음
• 업데이트를 위해 수동으로 npm update -g @anthropic-ai/claude-code 실행 필요

중요: 권한 문제를 일으키므로 sudo npm install -g를 절대 사용하지 마세요. EACCES 오류가 발생하면 대신 npm 권한을 수정하세요.

특정 버전 설치

네이티브 바이너리의 특정 버전을 설치하려면:

# 최신 버전 설치
curl -fsSL https://claude.ai/install.sh | bash -s latest

# 특정 버전 설치
curl -fsSL https://claude.ai/install.sh | bash -s 2.0.22

플랫폼별 안내

Homebrew가 있는 macOS

brew install claude-code

참고: Homebrew 설치는 brew 디렉토리와 독립적으로 자동 업데이트됩니다.

Windows: irm https://claude.ai/install.ps1 | iex 사용

Windows 사용자의 경우 세 가지 옵션이 있습니다:

1. WSL (권장): WSL을 설치하고 Linux 지침 따르기
2. Git Bash: Git Bash에서 네이티브 설치 프로그램 사용
3. PowerShell (네이티브 Windows):

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

irm 명령어 이해하기

irm 명령어는 PowerShell의 Invoke-RestMethod로, URL에서 콘텐츠를 다운로드합니다. 이 명령이 하는 일은 다음과 같습니다:

• irm https://claude.ai/install.ps1 - Anthropic 서버에서 설치 스크립트 다운로드
• | iex - 스크립트를 Invoke-Expression으로 파이프하여 실행

https://claude.ai/install.ps1 스크립트는 다음을 처리합니다:

• Windows 아키텍처 감지 (x64, ARM64)
• 적절한 Claude Code 바이너리 다운로드
• 사용자 디렉토리에 설치
• PATH 환경 변수에 Claude 추가

보안 참고: 설치 스크립트를 실행하기 전에 항상 공식 claude.ai 도메인에서 다운로드하는지 확인하세요.

Alpine Linux

Alpine 및 기타 musl 기반 배포판은 추가 의존성이 필요합니다:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0
curl -fsSL https://claude.ai/install.sh | bash

설치 후 설정

인증

설치 후 Claude Code를 인증합니다:

claude

인증 방법을 선택하라는 메시지가 표시됩니다:

• Claude Console (기본): console.anthropic.com에서 청구되는 API 액세스
• Claude Pro/Max: Claude 구독이 있는 경우
• Enterprise: AWS Bedrock 또는 Google Vertex AI 배포용

기본 사용법

Claude Code 사용 시작:

# 프로젝트로 이동
cd /path/to/your/project

# Claude Code 시작
claude

# 도움말 보기
claude help

# 세션 내에서 슬래시 명령어 사용
/help    # 사용 가능한 명령어 표시
/clear   # 대화 지우기
/exit    # Claude Code 종료

업데이트 관리

자동 업데이트

Claude Code는 기본적으로 자동 업데이트됩니다. 시작 시 업데이트를 확인하고 백그라운드에서 적용합니다.

Claude Code 업데이트 방법

claude update

이를 영구적으로 적용하려면 .bashrc 또는 .zshrc에 추가하세요.

일반적인 문제 및 해결책

문제: "Insufficient permissions to install update"

이 문제는 일반적으로 npm/Bun 설치에서 발생합니다. 해결책: 네이티브 바이너리 설치로 전환하세요.

문제: "command not found: claude"

PATH가 업데이트되지 않았습니다. 셸 설정에 추가하세요:

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

문제: 검색 기능이 작동하지 않음

보통 네이티브 설치로 해결되지만 계속 문제가 있다면:

# ripgrep 수동 설치
sudo apt-get install ripgrep  # Ubuntu/Debian
brew install ripgrep          # macOS

모범 사례

1. 항상 네이티브 바이너리 사용 - 특별한 요구 사항이 없는 한
2. sudo 사용 금지 - 어떤 설치 방법에서도
3. 자동 업데이트 활성화 유지 - 보안 및 기능을 위해
4. 설치 또는 업데이트 후 claude doctor 실행 - 상태 확인
5. 새 버전 설치 전 이전 설치 정리 - 충돌 방지

결론

의심스러울 때는 모든 것을 제거하고 네이티브 바이너리로 새로 시작하세요. Claude Code를 실행하는 가장 간단하고 빠르며 안정적인 방법입니다.

관련 읽기

이제 Claude Code가 설치되었으니 실제로 사용해보세요:

• Flask로 쇼핑 카트 만들기 - Claude Code를 사용하여 Python과 Flask로 완전한 전자상거래 백엔드를 구축하는 실습 튜토리얼

빠른 참조

• 설치: curl -fsSL https://claude.ai/install.sh | bash
• 버전 확인: claude --version
• 진단: claude doctor
• 업데이트: claude update
• 시작: claude
• 도움말: claude help