Claude Code 고급 설치(Advanced setup)

Claude Code 고급 설치(Advanced setup)

Claude Code는 터미널·IDE·데스크톱 앱·브라우저에서 쓸 수 있는 에이전트 코딩 도구예요. 이 페이지는 처음 세션을 안내하는 quickstart가 아니라, 시스템 요구사항·플랫폼별 설치·버전 관리·삭제를 다루는 설치 가이드예요. 첫 세션을 직접 따라 해보고 싶다면 quickstart를, 터미널 자체가 낯설다면 terminal guide를 먼저 보는 게 좋아요.

출처: 공식문서

본문

시스템 요구사항

Claude Code는 다음 플랫폼과 구성에서 동작해요.

  • 운영체제: macOS 13.0+, Windows 10 1809+ 또는 Windows Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
  • 하드웨어: 4 GB+ RAM, x64 또는 ARM64 프로세서
  • 네트워크: 인터넷 연결 필수
  • 셸: Bash, Zsh, PowerShell, CMD
  • 지역: Anthropic 지원 국가

추가 의존성으로는 ripgrep이 있는데요, 보통 Claude Code에 포함되어 있어요. 검색이 실패하면 검색 트러블슈팅 문서를 확인하세요.

Claude Code 설치

그래픽 인터페이스를 선호한다면 Desktop 앱이 터미널 없이도 Claude Code를 쓸 수 있게 해줘요. 설치 방법은 네 가지가 있어요.

네이티브 설치 (권장)

  • 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

여기서 The token '&&' is not a valid statement separator가 나오면 PowerShell, 'irm' is not recognized...가 나오면 CMD에 있다는 뜻이에요. 네이티브 설치는 백그라운드에서 자동 업데이트되어 항상 최신 버전을 유지해요.

네이티브 Windows에서는 Git for Windows 설치를 권장해요. 설치하면 Claude Code가 Bash 도구를 쓸 수 있거든요. Git이 없으면 Claude Code는 셸 도구로 PowerShell을 대신 사용해요. WSL에서는 Git for Windows가 필요 없어요.

Homebrew

brew install --cask claude-code

Homebrew는 두 개의 cask를 제공해요. claude-code는 안정(stable) 채널(보통 1주 정도 뒤처짐)이고 claude-code@latest는 최신 채널이에요. Homebrew 설치는 자동 업데이트되지 않으니 brew upgrade claude-code로 직접 올려야 해요.

WinGet

winget install Anthropic.ClaudeCode

WinGet도 자동 업데이트되지 않으니 winget upgrade Anthropic.ClaudeCode를 주기적으로 실행하세요.

설치가 끝나면 작업하려는 프로젝트의 터미널을 열고 claude를 실행하면 대화형 세션이 열려요. 설치 중 문제가 생기면 설치/로그인 트러블슈팅 문서를 보세요.

Windows에서 설정하기

네이티브 Windows 또는 WSL에서 실행할 수 있어요. 프로젝트 위치와 필요한 기능에 따라 고르면 돼요.

옵션 요구사항 샌드박싱 언제 쓸까
네이티브 Windows 없음(Git for Windows는 선택) 미지원 Windows 네이티브 프로젝트·도구
WSL 2 WSL 2 활성화 지원 Linux 툴체인 또는 샌드박스 명령 실행
WSL 1 WSL 1 활성화 미지원 WSL 2가 없을 때

옵션 1: 네이티브 Windows — PowerShell이나 CMD에서 설치 명령을 실행해요. 관리자 권한은 필요 없어요. Git for Windows가 없으면 PowerShell 도구로, 있으면 Git Bash로 셸 명령을 실행해요. Claude Code가 Git Bash를 못 찾으면 settings.json에 경로를 지정할 수 있어요.

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Git for Windows가 설치되면 Bash 옆에 PowerShell 도구도 함께 쓰여요(claude.ai·Console 계정에선 기본 켜짐, Amazon Bedrock·Google Cloud's Agent Platform·Microsoft Foundry 세션에선 CLAUDE_CODE_USE_POWERSHELL_TOOL=1로 활성화, 0으로 끔).

옵션 2: WSL — WSL 배포판에서 Linux 설치 명령을 실행해요. claude는 PowerShell/CMD가 아니라 WSL 터미널 안에서 설치·실행해요.

Alpine Linux 및 musl 기반 배포판

Alpine에 설치하려면 실행에 bash, curl(설치용)과 libgcc, libstdc++, ripgrep이 필요해요. Alpine은 기본에 bash/curl이 없어서 이 패키지들을 먼저 설치해야 해요.

apk add bash curl libgcc libstdc++ ripgrep

Alpine에서 ripgrep은 커뮤니티 저장소에 있어요. 패키지가 없다고 나오면 커뮤니티 저장소를 추가하세요.

echo "https://dl-cdn.alpinelinux.org/alpine/v3.22/community" >> /etc/apk/repositories

apk update 후 다시 apk add를 실행하고, settings.json에 USE_BUILTIN_RIPGREP를 0으로 설정하세요.

설치 확인

설치 후 claude --version으로 동작을 확인해요. 정상이면 2.1.211 (Claude Code) 같은 버전 번호가 출력돼요. 더 자세한 설치·설정 진단은 claude doctor로 확인할 수 있어요(세션 시작 없이 설치 상태, 설정 파일 검증 오류, 경고를 읽기 전용으로 출력).

인증

Claude Code는 Pro, Max, Team, Enterprise, Console 계정이 필요해요(무료 Claude.ai 플랜은 미포함). Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry 같은 서드파티 API 제공자로도 쓸 수 있어요. 설치는 claude를 실행해 브라우저 프롬프트를 따라가면 되고, ANTHROPIC_API_KEY 환경변수가 설정돼 있으면 브라우저 대신 키 승인을 한 번 물어봐요.

Claude Code 업데이트

네이티브 설치는 백그라운드에서 자동 업데이트돼요. autoUpdatesChannel 설정으로 채널을 고를 수 있어요.

  • "latest"(기본): 새 기능을 출시 즉시
  • "stable": 보통 1주 정도 된 버전, 주요 회귀가 있는 릴리스는 건너뜀
{
  "autoUpdatesChannel": "stable"
}

minimumVersion 설정으로 최소 버전 하한을 고정할 수 있어요. 아래 예시처럼 하면 stable 채널로 바꿔도 이미 더 새로운 latest 빌드를 쓰고 있다면 다운그레이드되지 않아요.

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}

자동 업데이트를 완전히 끄려면 settings.json의 env에 DISABLE_AUTOUPDATER를 "1"로 설정해요. 백그라운드 검사만 끄고 claude update/claude install은 여전히 동작해요. 모든 업데이트 경로(수동 포함)를 막으려면 DISABLE_UPDATES를 쓰세요.

수동으로 즉시 업데이트하려면 claude update를 실행해요. 성공 시 Successfully updated from <old> to version <new>, 이미 최신이면 Claude Code is up to date (<version>)가 출력돼요.

특정 버전 설치

네이티브 설치 프로그램은 특정 버전 번호나 릴리스 채널(latest/stable)을 받아요.

  • 최신(macOS/Linux/WSL): curl -fsSL https://claude.ai/install.sh | bash
  • 안정(macOS/Linux/WSL): curl -fsSL https://claude.ai/install.sh | bash -s stable
  • 특정 버전(macOS/Linux/WSL): curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89
  • Windows PowerShell: & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable 또는 ... ))) 2.1.89
  • Windows CMD: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd

claude --version으로 2.1.89 (Claude Code)처럼 정확히 설치된 버전을 확인할 수 있어요.

Linux 패키지 매니저 설치

Claude Code는 서명된 apt, dnf, apk 저장소를 제공해요. 각 저장소는 stable(보통 1주 지연)과 latest(출시 즉시) 두 채널이 있어요. 패키지 매니저 설치는 Claude Code를 통한 자동 업데이트가 아니라 시스템 업그레이드 흐름으로 업데이트돼요.

apt (Debian/Ubuntu) — 서명 키를 내려받아 gpg로 검증해요.

sudo apt install curl gnupg
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
gpg --show-keys /etc/apt/keyrings/claude-code.asc

지문이 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE여야 해요. 그다음 저장소를 등록하고 설치해요.

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

업그레이드는 sudo apt update && sudo apt upgrade claude-code.

dnf (Fedora/RHEL)

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

업그레이드는 sudo dnf upgrade claude-code.

apk (Alpine)

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

sha256sum /etc/apk/keys/claude-code.rsa.pub이 395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6인지 확인하세요. 업그레이드는 apk update && apk upgrade claude-code.

npm 설치

전역 npm 패키지로도 설치할 수 있어요. v2.1.198부터 npm 패키지는 Node.js 22 이상을 요구해요(옛 버전이면 EBADENGINE 경고만 나오고 설치가 완료되며, 네이티브 바이너리를 내려받아 런타임에 Node를 쓰지 않아요).

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

sudo npm install -g는 쓰지 마세요. 권한 문제와 보안 위험이 생길 수 있어요. 업그레이드는 npm install -g @anthropic-ai/claude-code@latest. npm update -g는 semver 범위를 존중해서 최신 릴리스로 안 옮겨갈 수 있어 피하세요.

바이너리 무결성 및 코드 서명

각 릴리스는 모든 플랫폼 바이너리의 SHA256 체크섬을 담은 manifest.json을 게시해요. 이 매니페스트는 Anthropic GPG 키로 서명되어 있어서 서명 검증이 매니페스트에 적힌 모든 바이너리를 간접 검증해요. 매니페스트 서명은 2.1.89부터 제공돼요.

curl -fsSL https://downloads.claude.ai/keys/claude-code.asc | gpg --import
gpg --fingerprint [email protected]
# 지문: 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE
REPO=https://downloads.claude.ai/claude-code-releases
VERSION=2.1.89
curl -fsSLO "$REPO/$VERSION/manifest.json"
curl -fsSLO "$REPO/$VERSION/manifest.json.sig"
gpg --verify manifest.json.sig manifest.json

Good signature from "Anthropic Claude Code Release Signing <[email protected]>"가 나오면 성공이에요. WARNING: This key is not certified with a trusted signature!는 새로 임포트한 키에 항상 나오는 것이라 정상이에요. 바이너리를 대조하려면 sha256sum claude(Linux)/shasum -a 256 claude(macOS)/(Get-FileHash claude.exe -Algorithm SHA256).Hash.ToLower()(Windows PowerShell)로 매니페스트의 platforms.<platform>.checksum과 비교하세요.

플랫폼 코드 서명: macOS는 "Anthropic PBC"로 서명·Apple 노터리, Windows는 "Anthropic, PBC" 서명, Linux는 개별 서명 없음(매니페스트 서명이나 패키지 매니저로 검증).

Claude Code 삭제

설치 방식을 따라 제거해요. 제거 후에도 claude가 실행되면 두 번째 설치나 옛 설치 프로그램의 셸 별칭이 남아있는 거예요.

  • 네이티브(macOS/Linux/WSL): rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude
  • 네이티브(Windows PowerShell): Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force 등
  • Homebrew: brew uninstall --cask claude-code 또는 claude-code@latest
  • WinGet: winget uninstall Anthropic.ClaudeCode
  • apt: sudo apt remove claude-code + 저장소·키 파일 삭제
  • dnf: sudo dnf remove claude-code + repo 파일 삭제
  • apk: apk del claude-code + 저장소 줄·키 삭제
  • npm: npm uninstall -g @anthropic-ai/claude-code

설정 파일을 지우는 건 모든 설정·허용 도구·MCP 서버 구성·세션 기록을 삭제한다는 뜻이라 주의하세요. VS Code 확장·JetBrains 플러그인·데스크톱 앱도 ~/.claude/에 쓰므로 이들을 먼저 제거해야 완전히 지워져요.

더 알아보기