Claude Code가 최신 버전으로 업데이트되지 않을 때 해결하는 방법

Claude Code업데이트Native InstallerHomebrewnpmPATH개발도구

Claude Code를 사용하다 보면 최신 기능이 적용되지 않거나, claude update를 실행했는데도 버전이 그대로인 경우가 있다. 특히 macOS에서 Homebrew로 설치했거나, 예전에 npm으로 설치한 뒤 나중에 Native Installer로 다시 설치한 경우에는 설치 경로가 꼬여 업데이트가 제대로 반영되지 않을 수 있다.

핵심은 claude update만 반복해서 실행하는 것이 아니다. 먼저 현재 실행 중인 claude가 어디에 있는지 확인하고, 어떤 설치 방식으로 들어온 실행 파일인지 파악해야 한다.

이 글은 Anthropic의 Claude Code Advanced setup, CLI reference, Settings, Troubleshooting 문서를 기준으로 2026년 6월 10일에 다시 확인해 정리했다.

먼저 결론

Claude Code가 최신 버전으로 업데이트되지 않는다면 다음 순서로 확인한다.

확인 항목명령어 또는 위치의미
현재 버전claude --version실제 실행되는 Claude Code 버전
실행 경로which -a claudePATH에서 어떤 claude가 먼저 잡히는지 확인
설치 상태claude doctor설치, 설정, 최근 업데이트 시도 상태 점검
수동 업데이트claude updateNative Installer 또는 auto-update 경로의 즉시 업데이트
설치 방식Native Installer, Homebrew, npm, WinGet설치 방식에 따라 업데이트 방법이 다름
업데이트 채널autoUpdatesChannel, Homebrew cask 이름latest인지 stable인지 확인

대부분의 문제는 설치 방식이 섞였거나, PATH가 예전 실행 파일을 먼저 참조하거나, Homebrew/WinGet/npm처럼 별도 업데이트가 필요한 방식으로 설치되어 있어서 발생한다.

현재 버전과 실행 경로 확인하기

먼저 현재 설치된 Claude Code 버전을 확인한다.

claude --version

그 다음 실제 실행 파일 위치를 확인한다.

which -a claude

which claude는 첫 번째로 잡히는 실행 파일만 보여주지만, which -a claude는 PATH에 잡힌 후보를 여러 개 보여준다. 설치가 꼬였는지 확인할 때는 -a를 붙이는 편이 더 유용하다.

예를 들어 다음과 같은 경로가 나올 수 있다.

/Users/you/.local/bin/claude
/opt/homebrew/bin/claude
/usr/local/bin/claude

이 결과를 보면 Native Installer, Homebrew, npm 중 어떤 실행 파일이 우선되는지 추정할 수 있다. 업데이트했는데도 버전이 그대로라면, 새 버전은 설치되었지만 터미널이 여전히 오래된 claude를 실행하고 있을 가능성이 크다.

Windows에서는 다음 명령어로 후보 경로를 확인한다.

where.exe claude

가장 먼저 실행해볼 명령어

Claude Code에는 설치와 설정 상태를 점검하는 진단 명령이 있다.

claude doctor

공식 문서도 Claude Code가 실행되지 않거나 설치 상태가 의심될 때 shell에서 claude doctor를 실행하라고 안내한다. 자동 업데이트가 최근에 실패했는지, npm 글로벌 디렉터리 권한 문제가 있는지 같은 힌트를 얻을 수 있다.

즉시 업데이트를 시도하려면 다음 명령어를 사용한다.

claude update

다만 이 명령어가 모든 설치 방식에서 같은 의미로 동작하는 것은 아니다. Native Installer와 Claude Code의 auto-update 경로에서는 핵심 명령이지만, Homebrew, WinGet, Linux package manager 설치는 기본적으로 각 package manager의 upgrade 명령을 사용해야 한다.

Native Installer로 설치한 경우

Anthropic 문서는 Claude Code 설치 방식으로 Native Install을 추천한다. macOS, Linux, WSL에서는 다음 명령어를 사용한다.

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

Windows PowerShell에서는 다음 명령어를 사용한다.

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

Native Installer로 설치한 Claude Code는 백그라운드 자동 업데이트를 지원한다. Claude Code는 시작 시점과 실행 중 주기적으로 업데이트를 확인하고, 업데이트는 다음 시작 시 적용된다.

수동으로 바로 반영하고 싶다면 다음 명령을 실행한다.

claude update

그래도 버전이 그대로라면 설치 자체보다 PATH 문제일 가능성이 높다. 다시 확인한다.

which -a claude
claude --version

Homebrew로 설치한 경우

macOS에서 Homebrew로 설치했다면 Claude Code 자체 자동 업데이트가 아니라 Homebrew 업그레이드 흐름을 따라야 한다.

stable cask를 설치했다면:

brew upgrade claude-code

latest cask를 설치했다면:

brew upgrade claude-code@latest

공식 문서에 따르면 Homebrew에는 두 cask가 있다.

cask채널특징
claude-codestable보통 약 일주일 늦고, 큰 회귀가 있는 릴리스는 건너뜀
claude-code@latestlatest새 버전이 나오면 더 빨리 받음

중요한 점은 Homebrew 설치에서는 settings.json의 autoUpdatesChannel보다 cask 이름이 채널을 결정한다는 것이다. 최신 기능을 바로 받고 싶다면 claude-code@latest cask를 설치해야 한다.

stable에서 latest로 바꾸려면 다음처럼 정리할 수 있다.

brew uninstall --cask claude-code
brew install --cask claude-code@latest

업그레이드 후에는 다음도 가끔 실행해 디스크를 정리한다.

brew cleanup

npm으로 설치한 경우

예전에 Claude Code를 npm으로 설치했다면 다음 명령어로 업데이트할 수 있다.

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

다만 npm 글로벌 설치는 Node 버전 관리자, 전역 prefix, 권한 문제 때문에 꼬이기 쉽다. 특히 과거에 sudo npm install -g로 설치한 적이 있다면 auto-update나 글로벌 패키지 업데이트가 권한 문제에 막힐 수 있다.

먼저 npm 글로벌 prefix와 실행 경로를 확인한다.

npm config get prefix
which -a claude

which -a claude 결과에서 npm 글로벌 경로가 Native Installer나 Homebrew보다 앞에 있다면, 터미널은 npm으로 설치된 오래된 Claude Code를 먼저 실행하고 있을 수 있다.

여러 설치 방식이 섞여 있다면 장기적으로는 하나만 남기는 편이 좋다. 특별한 이유가 없다면 Native Installer로 통일하는 것이 가장 단순하다.

Windows와 WinGet으로 설치한 경우

Windows에서 Native Installer를 사용할 때 PowerShell 명령은 다음과 같다.

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

WinGet으로 설치했다면 다음 명령어로 업그레이드한다.

winget upgrade Anthropic.ClaudeCode

공식 문서에 따르면 WinGet 설치는 기본적으로 Claude Code가 자동 업데이트하지 않는다. 또한 Windows에서는 Claude Code가 실행 중일 때 실행 파일이 잠겨 업그레이드가 실패할 수 있다. 이 경우 Claude Code를 종료한 뒤 WinGet 명령을 다시 실행한다.

설치 후에는 버전과 경로를 확인한다.

claude --version
where.exe claude

업데이트 채널 확인하기

Claude Code가 최신 기능을 받지 못하는 이유가 업데이트 채널 때문일 수도 있다.

Native Installer와 claude update는 autoUpdatesChannel 설정을 따른다. 공식 문서 기준으로 주요 값은 다음과 같다.

값의미
latest기본값. 새 기능을 가장 빨리 받음
stable보통 약 일주일 늦고, 큰 회귀가 있는 릴리스를 피함

설정은 /config의 Auto-update channel에서 바꾸거나 settings.json에 직접 넣을 수 있다.

{
  "autoUpdatesChannel": "latest"
}

안정성을 우선한다면 다음처럼 둘 수 있다.

{
  "autoUpdatesChannel": "stable"
}

다시 강조하면 Homebrew 설치에서는 이 설정이 아니라 cask 이름이 중요하다. claude-code는 stable, claude-code@latest는 latest를 따른다.

업데이트가 막혀 있는 설정 확인하기

설정에서 업데이트를 제한하고 있을 수도 있다. 사용자 설정 파일을 확인한다.

cat ~/.claude/settings.json

다음 설정은 백그라운드 자동 업데이트 확인을 막는다.

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

DISABLE_AUTOUPDATER는 백그라운드 업데이트만 막는다. claude update와 claude install은 여전히 동작할 수 있다.

반면 DISABLE_UPDATES는 수동 업데이트까지 막을 수 있는 더 강한 설정이다. 조직이나 회사에서 특정 버전을 강제로 유지하려고 설정했을 수 있으므로, 개인 환경이 아니라 관리형 환경이라면 함부로 제거하기 전에 팀 정책을 확인해야 한다.

Homebrew 또는 WinGet 설치에서 Claude Code가 package manager upgrade를 백그라운드로 실행하게 하려면 다음 환경 변수를 사용할 수 있다.

{
  "env": {
    "CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE": "1"
  }
}

다만 package manager 기반 설치는 조직 정책, 권한, 실행 중 파일 잠금 같은 변수가 있으므로 수동 upgrade 명령을 알고 있는 편이 안전하다.

PATH 문제 해결하기

업데이트했는데도 버전이 바뀌지 않는 가장 흔한 원인은 PATH 충돌이다.

다음 명령으로 모든 후보를 확인한다.

which -a claude

zsh나 bash에서 shell hash cache 때문에 예전 경로가 남아 있을 수 있다. 이때는 다음 명령을 실행한다.

hash -r

그 다음 터미널을 완전히 닫았다가 다시 열고 확인한다.

claude --version
which -a claude

만약 Homebrew, npm, Native Installer 경로가 동시에 보인다면 하나만 남기는 것이 좋다. 예를 들어 Native Installer로 통일하려면 오래된 Homebrew나 npm 설치를 제거한 뒤 다시 확인한다.

brew uninstall --cask claude-code
npm uninstall -g @anthropic-ai/claude-code
which -a claude

단, 이 명령은 실제로 설치를 제거한다. 팀이나 회사 장비라면 관리 정책을 먼저 확인해야 한다.

추천 해결 순서

Claude Code가 최신 버전으로 업데이트되지 않는다면 아래 순서대로 진행한다.

claude --version
which -a claude
claude doctor
claude update

그래도 해결되지 않으면 설치 방식별로 처리한다.

Native Installer 사용자

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

Homebrew 사용자

brew upgrade claude-code

latest cask라면:

brew upgrade claude-code@latest

npm 사용자

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

Windows WinGet 사용자

winget upgrade Anthropic.ClaudeCode

마지막으로 다시 확인한다.

claude --version
which -a claude

Windows에서는:

claude --version
where.exe claude

결론

Claude Code가 최신 버전으로 업데이트되지 않을 때 가장 중요한 것은 설치 방식을 먼저 확인하는 것이다.

claude update만 반복해서 실행하기보다, which -a claude로 실제 실행 경로를 확인하고, Native Installer, Homebrew, npm, WinGet 중 어떤 방식으로 설치되어 있는지 파악해야 한다.

특히 macOS에서는 Homebrew와 Native Installer가 동시에 설치되어 PATH가 꼬이는 경우가 많다. 이런 경우에는 하나의 설치 방식만 남기고 정리하는 것이 가장 확실하다.

정리하면 다음과 같다.

  • Native Installer라면 claude update 또는 설치 스크립트 재실행
  • Homebrew라면 brew upgrade claude-code 또는 brew upgrade claude-code@latest
  • npm이라면 npm install -g @anthropic-ai/claude-code@latest
  • WinGet이라면 winget upgrade Anthropic.ClaudeCode
  • 업데이트 후에도 버전이 그대로라면 which -a claude 또는 where.exe claude로 PATH 문제 확인

Claude Code는 업데이트가 자주 이루어지는 도구다. 최신 기능을 안정적으로 사용하려면 설치 방식과 업데이트 채널을 명확히 관리하는 것이 좋다.

Related