Claude Code CLI 설치와 업데이트: Mac, Linux, Windows

Claude Code 설치는 플랫폼마다 명령 하나면 끝납니다. macOS, Linux, WSL에서는 curl -fsSL https://claude.ai/install.sh | bash, Windows PowerShell에서는 irm https://claude.ai/install.ps1 | iex를 실행하면 됩니다. 업데이트도 자동(기본값)이거나 claude update 한 번이면 충분합니다. 대부분의 문서가 건너뛰는 부분은 그 첫 명령 이후입니다. 선택지가 네 가지일 때 어떤 설치 방식을 골라야 하는지, 자동 업데이터가 어떻게 동작하고 어떻게 끄는지, 특정 버전을 어떻게 고정하는지, 각 방식을 어떻게 깔끔하게 제거하는지 말입니다. 이 페이지는 그 레퍼런스이며, 용도별로 표를 하나씩 정리했습니다. v2.1.224(2026년 8월) 기준입니다.¹

TL;DR

• 네이티브 설치 프로그램을 사용하십시오. Node.js 의존성이 없고, 플랫폼별로 테스트를 마친 바이너리를 배포하며, v2.1.113부터 기본값입니다. npm 패키지는 레거시로, v2.1.15에서 지원이 중단되었고 지금은 Node.js 22 이상을 요구합니다.¹
• 업데이트는 기본적으로 자동입니다. Claude Code는 시작할 때와 세션 중 주기적으로 확인하고, 백그라운드에서 내려받은 뒤 다음 실행 때 적용합니다. claude update를 실행하면 지금 즉시 적용됩니다.²
• 업데이트를 끄는 스위치는 두 가지입니다. DISABLE_AUTOUPDATER=1은 백그라운드 업데이트를 멈추고, DISABLE_UPDATES=1(v2.1.118 이상)은 수동 claude update를 포함한 모든 업데이트 경로를 차단합니다.²
• 버전 고정은 설치 프로그램에 버전을 넘기기만 하면 됩니다. curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58처럼 씁니다. 지금 실행 중인 버전은 claude --version으로 확인하고, 무엇이 바뀌었는지는 /release-notes로 살펴보십시오.¹²
• 무언가 이상하게 동작하면 claude doctor를 실행하십시오. 설치 유형, 버전, 감지된 문제를 알려 주며, v2.1.205부터는 세션 안의 /doctor가 설정 문제를 진단하고 수정까지 해 줍니다.²

Claude Code CLI는 어떻게 설치합니까?

플랫폼별로 명령 하나면 됩니다.

# 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

패키지 관리자를 선호한다면 두 가지 모두 일급으로 지원됩니다.

brew install --cask claude-code          # macOS / Linux (stable channel)
winget install Anthropic.ClaudeCode      # Windows

그다음 프로젝트 디렉터리에서 claude를 실행하고 Claude Pro/Max/Team 구독 또는 Anthropic API 계정으로 인증하면 됩니다.¹ 네이티브 설치 프로그램에는 Node.js도, sudo도, 미리 깔아 둘 것도 필요 없습니다. 레거시 npm 경로(npm install -g @anthropic-ai/claude-code)를 꼭 써야 한다면 Node.js 22 이상이 필요하며, sudo로는 절대 실행하지 마십시오. root 소유의 전역 모듈은 설치가 끝난 뒤까지 이어지는 권한 문제를 만듭니다.¹ 이미 npm으로 설치했다면 claude install이 그 자리에서 네이티브 바이너리로 옮겨 줍니다.

첫 세션 설정, 즉 인증 선택지와 첫 프롬프트, 권한 모드는 퀵스타트 안내가 처음부터 첫 결과까지의 과정을 다룹니다.

Claude Code는 어떤 플랫폼을 지원합니까?

Windows에 대해 반복해서 나오는 질문의 답은 이렇습니다. 네이티브 Windows는 잘 동작하며 관리자 권한도 필요 없습니다. Anthropic의 안내는 프로젝트가 어디에 있고 무엇이 필요한지에 따라 고르라는 것이며, Linux 툴체인이나 샌드박스 명령 실행이 필요하면 WSL 2를 쓰면 되고 같은 Linux용 설치 프로그램이 그 안에서 실행됩니다.³ Claude Code 자동 모드는 보안 경계가 아닙니다에서는 자동 모드가 아니라 OS 격리가 진짜 경계라고 주장합니다.

Claude Code는 어떻게 업데이트합니까?

대개는 아무것도 하지 않아도 됩니다. Claude Code는 기본적으로 자동 업데이트됩니다. 시작할 때와 세션 중 주기적으로 새 버전을 확인하고, 백그라운드에서 내려받은 다음 실행할 때 적용합니다.² 지금 바로 업데이트하고 싶거나 자동 업데이터를 꺼 둔 상태라면 다음을 실행하십시오.

claude update

패키지 관리자로 설치했다면 각자의 채널로 업데이트합니다. brew upgrade --cask claude-code, winget upgrade Anthropic.ClaudeCode가 그것입니다. v2.1.129부터는 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1을 설정하면 이런 설치에서도 패키지 관리자 업그레이드가 백그라운드로 실행되고 재시작을 안내합니다.²

업데이트 제어는 서로 다른 두 스위치로 나뉘며, 통제가 엄격한 환경에서는 이 차이가 중요합니다.

둘 다 환경 변수로 지정하거나 settings.json의 "env" 아래에 넣으면 됩니다.²

특정 버전은 어떻게 설치합니까?

설치 프로그램에 버전을 넘기면 됩니다. 버그를 재현하거나, 팀 전체를 검증된 릴리스에 묶어 두거나, 롤백할 때 유용합니다.

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

# Latest, explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell, specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

claude --version으로 확인하고, 각 릴리스에서 무엇이 바뀌었는지는 세션 안의 /release-notes 선택기로 읽으십시오.² 버전을 고정한다면 DISABLE_AUTOUPDATER=1과 함께 쓰십시오. 그러지 않으면 자동 업데이터가 다음 실행 때 그 고정을 정중하게 풀어 버립니다. 수동 claude update까지 막고 싶다면 대신 DISABLE_UPDATES=1을 쓰면 됩니다.

Claude Code는 어떻게 제거합니까?

제거 방법은 설치 방식에 맞춰야 합니다.

설정은 ~/.claude/에 따로 보관되므로 바이너리를 지워도 설정, 스킬, 기록은 사라지지 않습니다. 완전히 백지에서 시작하고 싶을 때만 이 디렉터리도 함께 지우십시오.¹

전체 수명 주기를 표 하나로

무언가 어긋났을 때, 이를테면 잘못된 버전이 보고되거나 업데이트 후 명령을 찾지 못하거나 설치가 절반만 적용되었을 때는 셸에서 claude doctor를 실행하십시오. 설치 유형과 버전, 감지된 문제를 알려 줍니다. 세션 안의 /doctor(v2.1.205 이상)는 전체 점검을 수행하고 발견한 문제를 고칠 수도 있습니다.² 설치 이후의 모든 것, 즉 구성과 권한, hooks, MCP, 서브에이전트는 Claude Code 전체 가이드에서 다룹니다.

Windows 문제 해결: claude를 인식하지 못함, 잘못된 셸, 차단된 스크립트

Windows에서 생기는 실패는 대부분 아래 아홉 가지 중 하나이며, 각각 알아볼 수 있는 오류 문자열이 있습니다. 아래의 모든 해결 방법은 2026년 9월 7일 기준 Anthropic의 설치 문제 해결 페이지와 설정 페이지에서 가져왔습니다.³⁴

1. 'claude' is not recognized as an internal or external command(CMD) 또는 The term 'claude' is not recognized as the name of a cmdlet(PowerShell). 설치 프로그램은 claude.exe를 %USERPROFILE%\.local\bin\claude.exe에 두었는데, 그 디렉터리가 PATH에 없거나 아직 설치를 실행한 터미널을 그대로 쓰고 있어 예전 PATH가 남아 있는 경우입니다. 확인하고, 추가한 다음, 새 터미널을 여십시오.⁴

$env:PATH -split ';' | Select-String '\.local\\bin'      # no output = not on PATH
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

CMD에서는 echo %PATH% | findstr /i "local\bin"으로 확인하고, 환경 변수 설정에서 사용자 PATH에 %USERPROFILE%\.local\bin을 추가하면 해결됩니다.⁴

2. 'irm' is not recognized, The token '&&' is not a valid statement separator, 또는 A parameter cannot be found that matches parameter name 'fsSL'. 다른 셸용 설치 명령을 실행한 것입니다. irm이 없다는 것은 CMD에 있다는 뜻이므로(프롬프트가 C:\로 표시됨) 위의 CMD 설치 명령을 쓰거나 PowerShell(PS C:\)을 여십시오. &&가 거부된다면 PowerShell에서 CMD용 명령을 실행한 것이니 irm https://claude.ai/install.ps1 | iex를 쓰십시오. fsSL 오류는 macOS/Linux용 curl -fsSL ... | bash 명령을 PowerShell에 붙여 넣었다는 뜻이며, PowerShell에서 curl은 Invoke-WebRequest의 별칭입니다. 명령이 스크립트 텍스트만 출력하고 아무것도 설치하지 않는다면, 내려받는 부분만 실행하고 그것을 실행하는 부분은 빠뜨린 것입니다.⁴

3. running scripts is disabled on this system / PSSecurityException. PowerShell 실행 정책이 npm이 만드는 .ps1 실행 래퍼(npm.ps1, claude.ps1)를 막고 있는 것입니다. 네이티브 설치 프로그램은 내려받은 텍스트를 저장된 파일이 아니라 iex로 실행하므로 이 정책의 영향을 받지 않습니다. 또한 ClaudeInstall.ps1을 저장해 -ExecutionPolicy Bypass -File로 실행하는 방식은 Anthropic이 문서화한 설치 경로가 아닙니다(설정 페이지에는 irm 명령, CMD 설치 명령, WinGet, npm만 나와 있습니다). 해결 방법은 순서대로 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser를 실행하거나, claude.cmd를 호출하거나(이 정책은 .cmd에는 적용되지 않습니다), npm 설치를 네이티브 설치 프로그램으로 바꾸는 것입니다.⁴

4. HTML 태그나 CSS를 인용하는 iex 구문 분석 오류, 또는 curl: (22) The requested URL returned error: 403. 설치 URL이 스크립트 대신 웹 페이지를 돌려준 것입니다. 페이지에 “App unavailable in region”이라고 나온다면 해당 국가에서는 Claude Code를 제공하지 않는 것이고, 그렇지 않다면 프록시나 필터가 가로막고 있는 것입니다. curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest로 연결 가능 여부를 확인하십시오(curl.exe를 명시적으로 호출해야 합니다. PowerShell의 curl 별칭은 -sI를 거부합니다). 첫 줄이 200이면 호스트에 연결할 수 있고 실패는 일시적이었다는 뜻입니다. 문서화된 대안은 winget install Anthropic.ClaudeCode입니다.⁴

5. Could not establish trust relationship for the SSL/TLS secure channel 또는 CRYPT_E_NO_REVOCATION_CHECK (0x80092012). 첫 번째 오류는 설치 프로그램을 실행하기 전에 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12로 TLS 1.2를 강제하면 됩니다. 인증서 해지 관련 오류는 네트워크가 인증서 해지 조회를 차단하고 있다는 뜻입니다. CMD의 curl 명령에 --ssl-revoke-best-effort를 추가하거나, .NET으로 내려받아 해지 서버에 연결할 수 없어도 넘어가는 PowerShell 설치 프로그램을 쓰십시오.⁴

6. The process cannot access the file ... because it is being used by another process. 이전 설치 프로그램이 아직 실행 중이거나, 백신 프로그램이 %USERPROFILE%\.claude\downloads에 있는 일부만 받은 파일을 검사하고 있는 것입니다. 다른 PowerShell 창을 닫고 검사가 끝나기를 기다린 다음 다음을 실행하십시오.⁴

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

7. 엉뚱한 버전이 실행되거나 두 설치본이 서로 다른 경우. where.exe claude는 PATH에 있는 모든 claude를 나열하고, Test-Path "$env:USERPROFILE\.local\bin\claude.exe"는 네이티브 설치 프로그램이 바이너리를 설치했는지 알려 줍니다. 네이티브 설치본만 남기고 나머지는 제거하십시오(winget uninstall Anthropic.ClaudeCode, npm uninstall -g @anthropic-ai/claude-code, 레거시 로컬 npm 설치라면 Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"). claude doctor는 실제로 실행 중인 설치 유형과 버전을 출력합니다.⁴

8. Claude Code on Windows requires either Git for Windows (for bash) or PowerShell. 두 셸 모두 찾지 못한 것입니다. Git for Windows는 선택 사항입니다. 없으면 Claude Code는 PowerShell 도구로 명령을 실행하고, 있으면 Bash 도구가 Git Bash를 사용합니다. Git Bash가 설치되어 있는데도 찾지 못한다면 settings.json에서 경로를 지정하십시오.³

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

9. Claude Code does not support 32-bit Windows. 64비트 컴퓨터에서 x86용 PowerShell 항목을 연 것입니다. “(x86)”이 붙은 항목이 아니라 “Windows PowerShell”을 여십시오.⁴

어느 것에도 해당하지 않는다면 claude doctor(읽기 전용이며 세션을 시작하지 않습니다)가 설치 상태, 설정 파일 오류, 마지막 업데이트 시도 결과를 알려 주며, Anthropic의 문제 해결 페이지에 오류별 해결 방법 전체 표가 있습니다.³⁴

자주 묻는 질문

Claude Code CLI를 최신 버전으로 업데이트하려면 어떻게 합니까?

claude update를 실행하거나 그냥 다시 시작하십시오. Claude Code는 기본적으로 시작할 때와 세션 중에 업데이트를 확인해 백그라운드로 내려받고 다음 실행 때 적용합니다. Homebrew와 winget으로 설치했다면 각각 brew upgrade --cask claude-code와 winget upgrade Anthropic.ClaudeCode로 업데이트합니다.

Claude Code는 자동으로 업데이트됩니까?

예, 기본값이 자동입니다. 시작할 때와 실행 중 주기적으로 확인한 뒤, 내려받은 업데이트를 다음 실행 때 적용합니다. DISABLE_AUTOUPDATER=1은 수동 claude update는 남겨 둔 채 백그라운드 업데이트만 끄고, DISABLE_UPDATES=1은 모든 업데이트 경로를 차단합니다.

Windows에 Claude Code를 어떻게 설치합니까?

PowerShell에서 irm https://claude.ai/install.ps1 | iex를 실행하십시오(또는 winget install Anthropic.ClaudeCode). 네이티브 Windows 10(1809 이상)은 x64와 ARM64에서 관리자 권한 없이 지원됩니다. Linux 툴체인이나 샌드박스 명령 실행이 필요하면 WSL 2를 선택하고, Linux와 완전히 동일한 환경을 위해 그 안에서 Linux용 설치 명령을 실행하십시오.

Claude Code를 설치하려면 Node.js가 필요합니까?

아닙니다. 권장되는 네이티브 설치 프로그램에는 Node.js 의존성이 없습니다. Node.js가 필요한 것은 레거시 npm 패키지(npm install -g @anthropic-ai/claude-code, v2.1.15에서 지원 중단)뿐이며, 여기에는 Node.js 22 이상이 필요합니다. npm으로 설치해 두었다면 claude install이 네이티브 바이너리로 옮겨 줍니다.

지금 쓰는 Claude Code 버전은 어떻게 확인합니까?

셸에서 claude --version을 실행하거나, 세션 안에서 /release-notes를 쓰면 대화형 변경 이력 선택기가 열립니다. claude doctor는 설치 유형과 감지된 설정 문제까지 함께 알려 줍니다.