고급 설정

Claude Code의 시스템 요구 사항, 플랫폼별 설치, 버전 관리 및 제거에 대한 안내입니다.

이 페이지에서는 시스템 요구 사항, 플랫폼별 설치 세부 사항, 업데이트 및 제거를 다룹니다. 첫 번째 세션의 안내형 워크스루는 빠른 시작을 참조하세요. 터미널을 한 번도 사용해본 적이 없다면 터미널 가이드를 참조하세요.

시스템 요구 사항

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

운영 체제:
- macOS 13.0+
- Windows 10 1809+ 또는 Windows Server 2019+
- Ubuntu 20.04+
- Debian 10+
- Alpine Linux 3.19+
하드웨어: 4 GB+ RAM
네트워크: 인터넷 연결 필요. 네트워크 구성을 참조하세요.
셸: Bash, Zsh, PowerShell 또는 CMD. Windows에서는 Git for Windows가 필요합니다.
지역: Anthropic 지원 국가

추가 의존성

ripgrep: 보통 Claude Code에 포함되어 있습니다. 검색이 실패하면 검색 문제 해결을 참조하세요.

Claude Code 설치

팁:

그래픽 인터페이스를 선호하시나요? Desktop 앱을 사용하면 터미널 없이 Claude Code를 사용할 수 있습니다. macOS 또는 Windows용으로 다운로드하세요.

터미널이 처음이신가요? 단계별 안내는 터미널 가이드를 참조하세요.

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

Windows에서는 Git for Windows가 필요합니다. 설치되어 있지 않다면 먼저 설치하세요.

참고: 네이티브 설치는 백그라운드에서 자동으로 업데이트되어 항상 최신 버전을 유지합니다.

Homebrew

brew install --cask claude-code

참고: Homebrew 설치는 자동 업데이트되지 않습니다. 최신 기능 및 보안 수정 사항을 받으려면 주기적으로 brew upgrade claude-code를 실행하세요.

WinGet

winget install Anthropic.ClaudeCode

참고: WinGet 설치는 자동 업데이트되지 않습니다. 최신 기능 및 보안 수정 사항을 받으려면 주기적으로 winget upgrade Anthropic.ClaudeCode를 실행하세요.

설치가 완료되면 작업할 프로젝트에서 터미널을 열고 Claude Code를 시작하세요:

claude

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

Windows에서 설정

Windows의 Claude Code에는 Git for Windows 또는 WSL이 필요합니다. PowerShell, CMD 또는 Git Bash에서 claude를 실행할 수 있습니다. Claude Code는 내부적으로 Git Bash를 사용하여 명령을 실행합니다. PowerShell을 관리자 권한으로 실행할 필요는 없습니다.

옵션 1: 네이티브 Windows + Git Bash

Git for Windows를 설치한 다음 PowerShell 또는 CMD에서 설치 명령을 실행하세요.

Claude Code가 Git Bash 설치 경로를 찾지 못하는 경우 settings.json 파일에서 경로를 설정하세요:

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

옵션 2: WSL

WSL 1과 WSL 2 모두 지원됩니다. WSL 2는 향상된 보안을 위한 샌드박싱을 지원합니다. WSL 1은 샌드박싱을 지원하지 않습니다.

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, Teams, Enterprise 또는 Console 계정이 필요합니다. 무료 Claude.ai 플랜에는 Claude Code 접근 권한이 포함되어 있지 않습니다. Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry와 같은 서드파티 API 제공자와 함께 Claude Code를 사용할 수도 있습니다.

설치 후 claude를 실행하고 브라우저 안내에 따라 로그인하세요. 모든 계정 유형 및 팀 설정 옵션은 인증을 참조하세요.

Claude Code 업데이트

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

자동 업데이트

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

참고:

Homebrew 및 WinGet 설치는 자동 업데이트되지 않습니다. 수동으로 업데이트하려면 brew upgrade claude-code 또는 winget upgrade Anthropic.ClaudeCode를 사용하세요.

알려진 문제: 새 버전이 이러한 패키지 관리자에서 사용 가능하기 전에 Claude Code가 업데이트를 알릴 수 있습니다. 업그레이드가 실패하면 잠시 기다렸다가 다시 시도하세요.

Homebrew는 업그레이드 후 이전 버전을 디스크에 유지합니다. 디스크 공간을 확보하려면 주기적으로 brew cleanup claude-code를 실행하세요.

릴리스 채널 구성

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

"latest" (기본값): 출시되는 즉시 새로운 기능을 받습니다
"stable": 보통 약 1주일 된 버전을 사용하여 주요 회귀가 있는 릴리스를 건너뜁니다

/config → Auto-update channel을 통해 구성하거나 settings.json 파일에 추가하세요:

{
  "autoUpdatesChannel": "stable"
}

엔터프라이즈 배포의 경우 관리형 설정을 사용하여 조직 전체에 일관된 릴리스 채널을 적용할 수 있습니다.

자동 업데이트 비활성화

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

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

수동 업데이트

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

claude update

고급 설치 옵션

이 옵션들은 버전 고정, npm에서의 마이그레이션 및 바이너리 무결성 확인을 위한 것입니다.

특정 버전 설치

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

최신 버전을 설치하려면 (기본값):

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

안정 버전을 설치하려면:

macOS, Linux, WSL

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

Windows PowerShell

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

Windows CMD

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

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

macOS, Linux, WSL

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

Windows PowerShell

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

Windows CMD

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

지원 중단된 npm 설치

npm 설치는 지원 중단되었습니다. 네이티브 설치 프로그램은 더 빠르고, 의존성이 필요 없으며, 백그라운드에서 자동 업데이트됩니다. 가능하면 네이티브 설치 방법을 사용하세요.

npm에서 네이티브로 마이그레이션

이전에 npm으로 Claude Code를 설치했다면 네이티브 설치 프로그램으로 전환하세요:

# 네이티브 바이너리 설치
curl -fsSL https://claude.ai/install.sh | bash

# 이전 npm 설치 제거
npm uninstall -g @anthropic-ai/claude-code

기존 npm 설치에서 claude install을 실행하여 네이티브 바이너리를 함께 설치한 다음 npm 버전을 제거할 수도 있습니다.

npm으로 설치

호환성을 위해 npm 설치가 필요한 경우 Node.js 18+이 설치되어 있어야 합니다. 패키지를 전역으로 설치하세요:

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

주의: sudo npm install -g를 사용하지 마세요. 권한 문제와 보안 위험이 발생할 수 있습니다. 권한 오류가 발생하면 권한 오류 문제 해결을 참조하세요.

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

SHA256 체크섬과 코드 서명을 사용하여 Claude Code 바이너리의 무결성을 확인할 수 있습니다.

모든 플랫폼의 SHA256 체크섬은 https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json의 릴리스 매니페스트에 게시됩니다. {VERSION}을 2.0.30과 같은 버전 번호로 교체하세요.
서명된 바이너리는 다음 플랫폼에 배포됩니다:
- macOS: "Anthropic PBC"가 서명하고 Apple이 공증
- Windows: "Anthropic, PBC"가 서명

Claude Code 제거

Claude Code를 제거하려면 설치 방법에 맞는 안내를 따르세요.

네이티브 설치

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

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
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Homebrew 설치

Homebrew cask를 제거하세요:

brew uninstall --cask claude-code

WinGet 설치

WinGet 패키지를 제거하세요:

winget uninstall Anthropic.ClaudeCode

npm

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

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

설정 파일 제거

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

Claude Code 설정 및 캐시된 데이터를 제거하려면:

macOS, Linux, WSL

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

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

Windows PowerShell

# 사용자 설정 및 상태 제거
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의 시스템 요구 사항, 플랫폼별 설치, 버전 관리 및 제거에 대한 안내입니다.

시스템 요구 사항

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

운영 체제:
- macOS 13.0+
- Windows 10 1809+ 또는 Windows Server 2019+
- Ubuntu 20.04+
- Debian 10+
- Alpine Linux 3.19+
하드웨어: 4 GB+ RAM
네트워크: 인터넷 연결 필요. 네트워크 구성을 참조하세요.
셸: Bash, Zsh, PowerShell 또는 CMD. Windows에서는 Git for Windows가 필요합니다.
지역: Anthropic 지원 국가

추가 의존성

ripgrep: 보통 Claude Code에 포함되어 있습니다. 검색이 실패하면 검색 문제 해결을 참조하세요.

Claude Code 설치

팁:

그래픽 인터페이스를 선호하시나요? Desktop 앱을 사용하면 터미널 없이 Claude Code를 사용할 수 있습니다. macOS 또는 Windows용으로 다운로드하세요.

터미널이 처음이신가요? 단계별 안내는 터미널 가이드를 참조하세요.

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

Windows에서는 Git for Windows가 필요합니다. 설치되어 있지 않다면 먼저 설치하세요.

참고: 네이티브 설치는 백그라운드에서 자동으로 업데이트되어 항상 최신 버전을 유지합니다.

Homebrew

brew install --cask claude-code

참고: Homebrew 설치는 자동 업데이트되지 않습니다. 최신 기능 및 보안 수정 사항을 받으려면 주기적으로 brew upgrade claude-code를 실행하세요.

WinGet

winget install Anthropic.ClaudeCode

참고: WinGet 설치는 자동 업데이트되지 않습니다. 최신 기능 및 보안 수정 사항을 받으려면 주기적으로 winget upgrade Anthropic.ClaudeCode를 실행하세요.

설치가 완료되면 작업할 프로젝트에서 터미널을 열고 Claude Code를 시작하세요:

claude

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

Windows에서 설정

옵션 1: 네이티브 Windows + Git Bash

Git for Windows를 설치한 다음 PowerShell 또는 CMD에서 설치 명령을 실행하세요.

Claude Code가 Git Bash 설치 경로를 찾지 못하는 경우 settings.json 파일에서 경로를 설정하세요:

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

옵션 2: WSL

WSL 1과 WSL 2 모두 지원됩니다. WSL 2는 향상된 보안을 위한 샌드박싱을 지원합니다. WSL 1은 샌드박싱을 지원하지 않습니다.

Alpine Linux 및 musl 기반 배포판

이 예제는 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를 실행하고 브라우저 안내에 따라 로그인하세요. 모든 계정 유형 및 팀 설정 옵션은 인증을 참조하세요.

Claude Code 업데이트

자동 업데이트

참고:

Homebrew 및 WinGet 설치는 자동 업데이트되지 않습니다. 수동으로 업데이트하려면 brew upgrade claude-code 또는 winget upgrade Anthropic.ClaudeCode를 사용하세요.

알려진 문제: 새 버전이 이러한 패키지 관리자에서 사용 가능하기 전에 Claude Code가 업데이트를 알릴 수 있습니다. 업그레이드가 실패하면 잠시 기다렸다가 다시 시도하세요.

Homebrew는 업그레이드 후 이전 버전을 디스크에 유지합니다. 디스크 공간을 확보하려면 주기적으로 brew cleanup claude-code를 실행하세요.

릴리스 채널 구성

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

"latest" (기본값): 출시되는 즉시 새로운 기능을 받습니다
"stable": 보통 약 1주일 된 버전을 사용하여 주요 회귀가 있는 릴리스를 건너뜁니다

/config → Auto-update channel을 통해 구성하거나 settings.json 파일에 추가하세요:

{
  "autoUpdatesChannel": "stable"
}

엔터프라이즈 배포의 경우 관리형 설정을 사용하여 조직 전체에 일관된 릴리스 채널을 적용할 수 있습니다.

자동 업데이트 비활성화

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

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

수동 업데이트

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

claude update

고급 설치 옵션

이 옵션들은 버전 고정, npm에서의 마이그레이션 및 바이너리 무결성 확인을 위한 것입니다.

특정 버전 설치

최신 버전을 설치하려면 (기본값):

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

안정 버전을 설치하려면:

macOS, Linux, WSL

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

Windows PowerShell

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

Windows CMD

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

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

macOS, Linux, WSL

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

Windows PowerShell

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

Windows CMD

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

지원 중단된 npm 설치

npm에서 네이티브로 마이그레이션

이전에 npm으로 Claude Code를 설치했다면 네이티브 설치 프로그램으로 전환하세요:

# 네이티브 바이너리 설치
curl -fsSL https://claude.ai/install.sh | bash

# 이전 npm 설치 제거
npm uninstall -g @anthropic-ai/claude-code

기존 npm 설치에서 claude install을 실행하여 네이티브 바이너리를 함께 설치한 다음 npm 버전을 제거할 수도 있습니다.

npm으로 설치

호환성을 위해 npm 설치가 필요한 경우 Node.js 18+이 설치되어 있어야 합니다. 패키지를 전역으로 설치하세요:

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

주의: sudo npm install -g를 사용하지 마세요. 권한 문제와 보안 위험이 발생할 수 있습니다. 권한 오류가 발생하면 권한 오류 문제 해결을 참조하세요.

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

SHA256 체크섬과 코드 서명을 사용하여 Claude Code 바이너리의 무결성을 확인할 수 있습니다.

모든 플랫폼의 SHA256 체크섬은 https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json의 릴리스 매니페스트에 게시됩니다. {VERSION}을 2.0.30과 같은 버전 번호로 교체하세요.
서명된 바이너리는 다음 플랫폼에 배포됩니다:
- macOS: "Anthropic PBC"가 서명하고 Apple이 공증
- Windows: "Anthropic, PBC"가 서명

Claude Code 제거

Claude Code를 제거하려면 설치 방법에 맞는 안내를 따르세요.

네이티브 설치

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

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
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Homebrew 설치

Homebrew cask를 제거하세요:

brew uninstall --cask claude-code

WinGet 설치

WinGet 패키지를 제거하세요:

winget uninstall Anthropic.ClaudeCode

npm

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

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

설정 파일 제거

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

Claude Code 설정 및 캐시된 데이터를 제거하려면:

macOS, Linux, WSL

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

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

Windows PowerShell

# 사용자 설정 및 상태 제거
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

46. 고급 설정

고급 설정

시스템 요구 사항

추가 의존성

Claude Code 설치

네이티브 설치 (권장)

Homebrew

WinGet

Windows에서 설정

옵션 1: 네이티브 Windows + Git Bash

옵션 2: WSL

Alpine Linux 및 musl 기반 배포판

설치 확인

인증

Claude Code 업데이트

자동 업데이트

릴리스 채널 구성

자동 업데이트 비활성화

수동 업데이트

고급 설치 옵션

특정 버전 설치

지원 중단된 npm 설치

npm에서 네이티브로 마이그레이션

npm으로 설치

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

Claude Code 제거

네이티브 설치

Homebrew 설치

WinGet 설치

npm

설정 파일 제거

46. 고급 설정

고급 설정

시스템 요구 사항

추가 의존성

Claude Code 설치

네이티브 설치 (권장)

Homebrew

WinGet

Windows에서 설정

옵션 1: 네이티브 Windows + Git Bash

옵션 2: WSL

Alpine Linux 및 musl 기반 배포판

설치 확인

인증

Claude Code 업데이트

자동 업데이트

릴리스 채널 구성

자동 업데이트 비활성화

수동 업데이트

고급 설치 옵션

특정 버전 설치

지원 중단된 npm 설치

npm에서 네이티브로 마이그레이션

npm으로 설치

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

Claude Code 제거

네이티브 설치

Homebrew 설치

WinGet 설치

npm

설정 파일 제거