고급 설정

이 페이지에서는 시스템 요구사항, 플랫폼별 설치 세부사항, 업데이트 및 제거에 대해 다룹니다. 첫 번째 세션의 단계별 안내는 빠른 시작을 참조하세요. 터미널을 처음 사용하는 경우 터미널 가이드를 참조하세요.

시스템 요구사항

Claude Code는 다음 플랫폼 및 구성에서 실행됩니다:

운영 체제:
- 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. 네이티브 Windows 설정에는 Git for Windows가 필요합니다. WSL 설정에는 필요하지 않습니다.
위치: Anthropic 지원 국가

추가 종속성

ripgrep: 일반적으로 Claude Code에 포함됩니다. 검색이 실패하면 검색 문제 해결을 참조하세요.

Claude Code 설치

그래픽 인터페이스를 선호하시나요? Desktop 앱을 사용하면 터미널 없이 Claude Code를 사용할 수 있습니다. macOS 또는 Windows용으로 다운로드하세요.터미널이 처음이신가요? 단계별 지침은 터미널 가이드를 참조하세요.

To install Claude Code, use one of the following methods:

Native Install (Recommended)
Homebrew
WinGet

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

If you see The token '&&' is not a valid statement separator, you’re in PowerShell, not CMD. If you see 'irm' is not recognized as an internal or external command, you’re in CMD, not PowerShell. Your prompt shows PS C:\ when you’re in PowerShell and C:\ without the PS when you’re in CMD.Native Windows setups require Git for Windows. Install it first if you don’t have it. WSL setups do not need it.

Native installations automatically update in the background to keep you on the latest version.

brew install --cask claude-code

Homebrew offers two casks. claude-code tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. claude-code@latest tracks the latest channel and receives new versions as soon as they ship.

Homebrew installations do not auto-update. Run brew upgrade claude-code or brew upgrade claude-code@latest, depending on which cask you installed, to get the latest features and security fixes.

winget install Anthropic.ClaudeCode

WinGet installations do not auto-update. Run winget upgrade Anthropic.ClaudeCode periodically to get the latest features and security fixes.

You can also install with apt, dnf, or apk on Debian, Fedora, RHEL, and Alpine. 설치가 완료된 후 작업하려는 프로젝트에서 터미널을 열고 Claude Code를 시작하세요:

claude

설치 중에 문제가 발생하면 문제 해결 가이드를 참조하세요.

Windows에서 설정

Claude Code를 Windows에서 기본적으로 실행하거나 WSL 내에서 실행할 수 있습니다. 프로젝트가 위치한 곳과 필요한 기능을 기반으로 선택하세요:

옵션	필요 사항	샌드박싱	사용 시기
네이티브 Windows	Git for Windows	지원되지 않음	Windows 기본 프로젝트 및 도구
WSL 2	WSL 2 활성화	지원됨	Linux 도구 체인 또는 샌드박싱된 명령 실행
WSL 1	WSL 1 활성화	지원되지 않음	WSL 2를 사용할 수 없는 경우

옵션 1: Git Bash를 사용한 네이티브 Windows Git for Windows를 설치한 후 PowerShell 또는 CMD에서 설치 명령을 실행하세요. 관리자로 실행할 필요가 없습니다. PowerShell 또는 CMD에서 설치하는지 여부는 실행하는 설치 명령에만 영향을 줍니다. 프롬프트는 PowerShell에서 PS C:\Users\YourName>을 표시하고 CMD에서는 PS 없이 C:\Users\YourName>을 표시합니다. 터미널이 처음이라면 터미널 가이드에서 각 단계를 안내합니다. 설치 후 PowerShell, CMD 또는 Git Bash에서 claude를 실행하세요. Claude Code는 실행 위치와 관계없이 명령을 실행하기 위해 내부적으로 Git Bash를 사용합니다. Claude Code가 Git Bash 설치를 찾을 수 없으면 settings.json 파일에서 경로를 설정하세요:

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

Claude Code는 또한 Windows에서 PowerShell을 기본적으로 실행할 수 있습니다. PowerShell 도구는 점진적으로 출시되고 있습니다. 옵트인하려면 CLAUDE_CODE_USE_POWERSHELL_TOOL=1을 설정하거나 옵트아웃하려면 0을 설정하세요. 설정 및 제한사항은 PowerShell 도구를 참조하세요. 옵션 2: WSL WSL 배포판을 열고 위의 설치 지침에서 Linux 설치 프로그램을 실행하세요. PowerShell 또는 CMD가 아닌 WSL 터미널 내에서 claude를 설치하고 실행합니다.

Alpine Linux 및 musl 기반 배포판

Alpine 및 기타 musl/uClibc 기반 배포판의 네이티브 설치 프로그램에는 libgcc, libstdc++ 및 ripgrep이 필요합니다. 배포판의 패키지 관리자를 사용하여 이들을 설치한 후 USE_BUILTIN_RIPGREP=0을 설정하세요. 이 예제는 Alpine에 필요한 패키지를 설치합니다:

apk add libgcc libstdc++ ripgrep

그런 다음 settings.json 파일에서 USE_BUILTIN_RIPGREP을 0으로 설정하세요:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

설치 확인

설치 후 Claude Code가 작동하는지 확인하세요:

claude --version

설치 및 구성을 더 자세히 확인하려면 claude doctor를 실행하세요:

claude doctor

인증

Claude Code는 Pro, Max, Team, Enterprise 또는 Console 계정이 필요합니다. 무료 Claude.ai 플랜에는 Claude Code 액세스가 포함되지 않습니다. Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry와 같은 타사 API 제공자와 함께 Claude Code를 사용할 수도 있습니다. 설치 후 claude를 실행하고 브라우저 프롬프트를 따라 로그인하세요. 모든 계정 유형 및 팀 설정 옵션은 인증을 참조하세요.

Claude Code 업데이트

네이티브 설치는 백그라운드에서 자동으로 업데이트됩니다. 릴리스 채널을 구성하여 즉시 업데이트를 받을지 또는 지연된 안정적인 일정으로 받을지 제어하거나, 자동 업데이트를 비활성화할 수 있습니다. Homebrew, WinGet 및 Linux 패키지 관리자 설치는 수동 업데이트가 필요합니다.

자동 업데이트

Claude Code는 시작 시 및 실행 중에 주기적으로 업데이트를 확인합니다. 업데이트는 백그라운드에서 다운로드 및 설치되며 다음 번에 Claude Code를 시작할 때 적용됩니다.

Homebrew, WinGet, apt, dnf 및 apk 설치는 자동으로 업데이트되지 않습니다. Homebrew의 경우 brew upgrade claude-code 또는 brew upgrade claude-code@latest를 실행하세요(설치한 cask에 따라 다름). WinGet의 경우 winget upgrade Anthropic.ClaudeCode를 실행하세요. Linux 패키지 관리자의 경우 Linux 패키지 관리자로 설치의 업그레이드 명령을 참조하세요.알려진 문제: Claude Code는 새 버전이 이러한 패키지 관리자에서 사용 가능하기 전에 업데이트를 알릴 수 있습니다. 업그레이드가 실패하면 잠시 기다렸다가 나중에 다시 시도하세요.Homebrew는 업그레이드 후 디스크에 이전 버전을 유지합니다. 디스크 공간을 확보하려면 주기적으로 brew cleanup을 실행하세요.

릴리스 채널 구성

autoUpdatesChannel 설정으로 Claude Code가 자동 업데이트 및 claude update에 대해 따르는 릴리스 채널을 제어하세요:

"latest", 기본값: 새 기능이 릴리스되는 즉시 받기
"stable": 일반적으로 약 1주일 된 버전을 사용하여 주요 회귀가 있는 릴리스 건너뛰기

이를 /config → 자동 업데이트 채널을 통해 구성하거나 settings.json 파일에 추가하세요:

{
  "autoUpdatesChannel": "stable"
}

엔터프라이즈 배포의 경우 관리 설정을 사용하여 조직 전체에서 일관된 릴리스 채널을 적용할 수 있습니다. Homebrew 설치는 이 설정 대신 cask 이름으로 채널을 선택합니다: claude-code는 안정적인 버전을 추적하고 claude-code@latest는 최신 버전을 추적합니다.

최소 버전 고정

minimumVersion 설정은 하한을 설정합니다. 백그라운드 자동 업데이트 및 claude update는 이 값 이하의 버전 설치를 거부하므로 "stable" 채널로 이동해도 이미 최신 "latest" 빌드에 있는 경우 다운그레이드되지 않습니다. /config를 통해 "latest"에서 "stable"로 전환하면 현재 버전을 유지하거나 다운그레이드를 허용하라는 메시지가 표시됩니다. 현재 버전을 유지하도록 선택하면 minimumVersion이 해당 버전으로 설정됩니다. "latest"로 다시 전환하면 이를 지웁니다. settings.json 파일에 추가하여 하한을 명시적으로 고정하세요:

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

관리 설정에서 이는 사용자 및 프로젝트 설정이 재정의할 수 없는 조직 전체 최소값을 적용합니다.

자동 업데이트 비활성화

settings.json 파일의 env 키에서 DISABLE_AUTOUPDATER를 "1"로 설정하세요:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

DISABLE_AUTOUPDATER는 백그라운드 확인만 중지합니다. claude update 및 claude install은 계속 작동합니다. 수동 업데이트를 포함한 모든 업데이트 경로를 차단하려면 DISABLE_UPDATES를 대신 설정하세요. Claude Code를 자신의 채널을 통해 배포하고 사용자가 제공하는 버전에 머물러야 할 때 이를 사용하세요.

수동으로 업데이트

다음 백그라운드 확인을 기다리지 않고 즉시 업데이트를 적용하려면 다음을 실행하세요:

claude update

고급 설치 옵션

이러한 옵션은 버전 고정, Linux 패키지 관리자, npm 및 바이너리 무결성 확인을 위한 것입니다.

특정 버전 설치

네이티브 설치 프로그램은 특정 버전 번호 또는 릴리스 채널(latest 또는 stable)을 허용합니다. 설치 시 선택한 채널이 자동 업데이트의 기본값이 됩니다. 자세한 내용은 릴리스 채널 구성을 참조하세요. 최신 버전을 설치하려면(기본값):

macOS, Linux, WSL
Windows PowerShell
Windows CMD

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

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

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

안정적인 버전을 설치하려면:

macOS, Linux, WSL
Windows PowerShell
Windows CMD

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

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd

특정 버전 번호를 설치하려면:

macOS, Linux, WSL
Windows PowerShell
Windows CMD

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

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 2.1.89 && del install.cmd

Linux 패키지 관리자로 설치

Claude Code는 서명된 apt, dnf 및 apk 저장소를 게시합니다. 롤링 채널의 경우 stable을 latest로 바꾸세요. 패키지 관리자 설치는 Claude Code를 통해 자동 업데이트되지 않습니다. 업데이트는 일반적인 시스템 업그레이드 워크플로우를 통해 제공됩니다. 모든 저장소는 Claude Code 릴리스 서명 키로 서명됩니다. 키를 신뢰하기 전에 각 탭에 설명된 대로 확인하세요.

Debian 및 Ubuntu용입니다. 롤링 채널을 사용하려면 deb 줄의 두 stable 항목을 변경하세요: URL 경로 및 제품군 이름입니다.

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는 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE를 보고해야 합니다.나중에 업그레이드하려면 sudo apt update && sudo apt upgrade claude-code를 실행하세요.

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

dnf는 첫 설치 시 키를 다운로드하고 지문을 확인하도록 요청합니다. 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE와 일치하는지 확인한 후 수락하세요.나중에 업그레이드하려면 sudo dnf upgrade claude-code를 실행하세요.

Alpine Linux용입니다:

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으로 설치

Claude Code를 전역 npm 패키지로 설치할 수도 있습니다. 패키지에는 Node.js 18 이상이 필요합니다.

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

npm 패키지는 독립 실행형 설치 프로그램과 동일한 네이티브 바이너리를 설치합니다. npm은 @anthropic-ai/claude-code-darwin-arm64와 같은 플랫폼별 선택적 종속성을 통해 바이너리를 가져오고 설치 후 단계가 이를 제자리에 연결합니다. 설치된 claude 바이너리는 자체적으로 Node를 호출하지 않습니다. 지원되는 npm 설치 플랫폼은 darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64 및 win32-arm64입니다. 패키지 관리자는 선택적 종속성을 허용해야 합니다. 설치 후 바이너리가 누락된 경우 문제 해결을 참조하세요.

sudo npm install -g를 사용하지 마세요. 이는 권한 문제 및 보안 위험으로 이어질 수 있습니다. 권한 오류가 발생하면 설치 중 권한 오류 문제 해결을 참조하세요.

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

각 릴리스는 모든 플랫폼 바이너리에 대한 SHA256 체크섬을 포함하는 manifest.json을 게시합니다. 매니페스트는 Anthropic GPG 키로 서명되므로 매니페스트의 서명을 확인하면 이것이 나열하는 모든 바이너리를 전이적으로 확인합니다.

매니페스트 서명 확인

다음 단계 1-3에는 gpg 및 curl이 있는 POSIX 셸이 필요합니다. Windows에서는 Git Bash 또는 WSL에서 실행하세요. 4단계에는 PowerShell 옵션이 포함됩니다.

공개 키 다운로드 및 가져오기

릴리스 서명 키는 고정 URL에 게시됩니다.

curl -fsSL https://downloads.claude.ai/keys/claude-code.asc | gpg --import

가져온 키의 지문을 표시합니다.

gpg --fingerprint security@anthropic.com

출력에 이 지문이 포함되어 있는지 확인하세요:

31DD DE24 DDFA B679 F42D  7BD2 BAA9 29FF 1A7E CACE

매니페스트 및 서명 다운로드

VERSION을 확인하려는 릴리스로 설정하세요.

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 <security@anthropic.com>"을 보고합니다.gpg는 또한 새로 가져온 키에 대해 WARNING: This key is not certified with a trusted signature!을 인쇄합니다. 이는 예상된 것입니다. Good signature 줄은 암호화 확인이 통과했음을 확인합니다. 1단계의 지문 비교는 키 자체가 진정함을 확인합니다.

바이너리를 매니페스트와 비교

다운로드한 바이너리의 SHA256 체크섬을 manifest.json의 platforms.<platform>.checksum 아래에 나열된 값과 비교합니다.

Linux
macOS
Windows PowerShell

sha256sum claude

shasum -a 256 claude

(Get-FileHash claude.exe -Algorithm SHA256).Hash.ToLower()

매니페스트 서명은 2.1.89 이상의 릴리스에 사용 가능합니다. 이전 릴리스는 분리된 서명 없이 manifest.json에 체크섬을 게시합니다.

플랫폼 코드 서명

서명된 매니페스트 외에도 개별 바이너리는 지원되는 플랫폼에서 플랫폼 기본 코드 서명을 수행합니다.

macOS: “Anthropic PBC”에서 서명하고 Apple에서 공증합니다. codesign --verify --verbose ./claude로 확인하세요.
Windows: “Anthropic, PBC”에서 서명합니다. Get-AuthenticodeSignature .\claude.exe로 확인하세요.
Linux: 바이너리는 개별적으로 코드 서명되지 않습니다. claude-code-releases 버킷에서 직접 다운로드하거나 네이티브 설치 프로그램을 사용하는 경우 위의 매니페스트 서명으로 무결성을 확인하세요. apt, dnf 또는 apk로 설치하는 경우 패키지 관리자가 저장소 서명 키를 사용하여 서명을 자동으로 확인합니다.

Claude Code 제거

Claude Code를 제거하려면 설치 방법에 따른 지침을 따르세요.

네이티브 설치

Claude Code 바이너리 및 버전 파일을 제거하세요:

macOS, Linux, WSL
Windows PowerShell

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

Homebrew 설치

설치한 Homebrew cask를 제거하세요. 안정적인 cask를 설치한 경우:

brew uninstall --cask claude-code

최신 cask를 설치한 경우:

brew uninstall --cask claude-code@latest

WinGet 설치

WinGet 패키지를 제거하세요:

winget uninstall Anthropic.ClaudeCode

apt / dnf / apk

패키지 및 저장소 구성을 제거하세요:

sudo apt remove claude-code
sudo rm /etc/apt/sources.list.d/claude-code.list /etc/apt/keyrings/claude-code.asc

sudo dnf remove claude-code
sudo rm /etc/yum.repos.d/claude-code.repo

apk del claude-code
sed -i '\|downloads.claude.ai/claude-code/apk|d' /etc/apk/repositories
rm /etc/apk/keys/claude-code.rsa.pub

npm

전역 npm 패키지를 제거하세요:

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

구성 파일 제거

구성 파일을 제거하면 모든 설정, 허용된 도구, MCP 서버 구성 및 세션 기록이 삭제됩니다.

VS Code 확장 프로그램, JetBrains 플러그인 및 Desktop 앱도 ~/.claude/에 씁니다. 이들 중 하나라도 여전히 설치되어 있으면 다음 실행 시 디렉토리가 다시 생성됩니다. Claude Code를 완전히 제거하려면 이 파일을 삭제하기 전에 VS Code 확장 프로그램, JetBrains 플러그인 및 Desktop 앱을 제거하세요. Claude Code 설정 및 캐시된 데이터를 제거하려면:

macOS, Linux, WSL
Windows PowerShell

# 사용자 설정 및 상태 제거
rm -rf ~/.claude
rm ~/.claude.json

# 프로젝트별 설정 제거(프로젝트 디렉토리에서 실행)
rm -rf .claude
rm -f .mcp.json

# 사용자 설정 및 상태 제거
Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

# 프로젝트별 설정 제거(프로젝트 디렉토리에서 실행)
Remove-Item -Path ".claude" -Recurse -Force
Remove-Item -Path ".mcp.json" -Force

설정 및 액세스

사용량 및 비용

플러그인 배포

보안 및 데이터

시스템 요구사항

추가 종속성

Claude Code 설치

Windows에서 설정

Alpine Linux 및 musl 기반 배포판

설치 확인

인증

Claude Code 업데이트

자동 업데이트

릴리스 채널 구성

최소 버전 고정

자동 업데이트 비활성화

수동으로 업데이트

고급 설치 옵션

특정 버전 설치

Linux 패키지 관리자로 설치

npm으로 설치

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

매니페스트 서명 확인

플랫폼 코드 서명

Claude Code 제거

네이티브 설치

Homebrew 설치

WinGet 설치

apt / dnf / apk

npm

구성 파일 제거

설정 및 액세스

사용량 및 비용

플러그인 배포

보안 및 데이터

​시스템 요구사항

​추가 종속성

​Claude Code 설치

​Windows에서 설정

​Alpine Linux 및 musl 기반 배포판

​설치 확인

​인증

​Claude Code 업데이트

​자동 업데이트

​릴리스 채널 구성

​최소 버전 고정

​자동 업데이트 비활성화

​수동으로 업데이트

​고급 설치 옵션

​특정 버전 설치

​Linux 패키지 관리자로 설치

​npm으로 설치

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

​매니페스트 서명 확인

​플랫폼 코드 서명

​Claude Code 제거

​네이티브 설치

​Homebrew 설치

​WinGet 설치

​apt / dnf / apk

​npm

​구성 파일 제거

시스템 요구사항

추가 종속성

Claude Code 설치

Windows에서 설정

Alpine Linux 및 musl 기반 배포판

설치 확인

인증

Claude Code 업데이트

자동 업데이트

릴리스 채널 구성

최소 버전 고정

자동 업데이트 비활성화

수동으로 업데이트

고급 설치 옵션

특정 버전 설치

Linux 패키지 관리자로 설치

npm으로 설치

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

매니페스트 서명 확인

플랫폼 코드 서명

Claude Code 제거

네이티브 설치

Homebrew 설치

WinGet 설치

apt / dnf / apk

npm

구성 파일 제거