클로드 코드(Claude Code) 업데이트: 설치 방식별 명령과 안 될 때

Ubuntu 테스트 환경에서 claude --version은 2.1.284라고 했는데, npm ls -g @anthropic-ai/claude-code는 2.1.42라고 했습니다. 둘 다 Claude Code인데 숫자가 한참 달랐죠.

이 차이는 claude doctor가 설명해 줍니다. 맨 위의 Running: native (2.1.284)가 지금 실제로 도는 설치본이고, 아래쪽에는 npm에 남은 설치본이 있다는 경고가 따로 붙어 있었거든요.

업데이트 명령은 이렇게 설치 방식이 정합니다. 네이티브 설치본은 그냥 두면 알아서 올라가고, 지금 바로 올리려면 claude update를 실행합니다. npm은 npm install -g @anthropic-ai/claude-code@latest, Homebrew는 brew upgrade claude-code, WinGet은 winget upgrade Anthropic.ClaudeCode예요.

올렸는데 버전이 그대로라면 Claude Code를 완전히 껐다 켜 보고, 그래도 같으면 claude doctor로 지금 실행되는 설치본이 무엇인지 확인하세요.

2026년 9월 29일 Ubuntu 24.04 · bash 테스트 환경에서 Claude Code 2.1.284(네이티브 설치본)를 직접 실행해 확인했고, 설치 방식별 명령과 설정은 같은 날 공식 문서와 변경 기록 기준입니다.

10월 12일에는 Windows 11 · PowerShell 5.1에서 npm으로 깐 2.1.286을 claude update로 2.1.296까지 올려 봤습니다. Homebrew·WinGet·apt·dnf·apk 설치본은 직접 올려 보지 않았습니다.

Windows에 처음 설치하는 단계는 Claude Code를 Windows에 설치하고 첫 작업까지 시키는 순서에 있습니다.

어느 설치본인지부터: claude doctor

테스트 환경에서 claude doctor를 실행하면 맨 위에 이렇게 나옵니다.

Running: native (2.1.284)
Platform: linux-x64
Path: <네이티브 설치 경로>/bin/claude
Config install method: unknown
Auto-updates: disabled (set by env: DISABLE_AUTOUPDATER)
Auto-update channel: latest
Last update attempt: none recorded
…
- Leftover npm global installation at <npm 전역 경로>/bin/claude
  Fix: Run: npm -g uninstall @anthropic-ai/claude-code

Running 줄이 설치 방식과 지금 도는 버전입니다. claude --version은 숫자만 알려 줄 뿐 그 숫자가 어느 설치본에서 왔는지는 말해 주지 않아요. 나머지 줄은 자동 업데이트가 켜졌는지(이 환경은 DISABLE_AUTOUPDATER로 꺼 둔 상태였습니다), 어느 채널을 따르는지, 마지막 시도가 어떻게 끝났는지입니다.

Windows에서 npm으로 깐 설치본은 이렇게 나왔습니다. PowerShell에서 그대로 claude doctor를 치면 됩니다.

Running: npm-global (2.1.296)
Platform: win32-x64
Path: %APPDATA%\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe
Config install method: global
Auto-updates: disabled (set by env: DISABLE_AUTOUPDATER)
Auto-update channel: latest
Last update attempt: success → 2.1.296 (2026-10-12)
…
No installation issues found.

npm으로 깔아도 실제로 도는 건 패키지 안의 claude.exe라는 게 Path 줄에 그대로 보입니다. 마지막 줄의 No installation issues found.는 설치 쪽에 걸리는 문제가 없다는 뜻이에요. Ubuntu처럼 설치본이 둘이면 이 자리에 경고가 붙습니다.

설치 방식을 알았으면 명령은 이 표에서 고르면 됩니다.

설치 방식	자동 업데이트	수동 명령
네이티브	자동	claude update
npm 전역	자동(전역 폴더에 쓸 수 있을 때)	npm install -g @anthropic-ai/claude-code@latest
Homebrew	기본은 수동	brew upgrade claude-code 또는 brew upgrade claude-code@latest
WinGet	기본은 수동	winget upgrade Anthropic.ClaudeCode
apt	수동	sudo apt update && sudo apt upgrade claude-code
apk	수동	apk update && apk upgrade claude-code

• Homebrew 명령이 둘인 건 어느 cask로 깔았느냐에 따라 이름이 다르기 때문입니다. claude-code는 stable 채널, claude-code@latest는 latest 채널이에요.
• dnf는 배포판마다 명령이 달라 공식 설치 문서의 Linux 패키지 관리자 절을 봅니다.
• npm 패키지도 독립 설치 프로그램과 같은 네이티브 실행 파일을 깝니다. 실행되는 프로그램은 같고 올리는 방법만 다릅니다.

npm으로 깔았다고 npm update -g를 쓰면 안 됩니다. 처음 설치할 때의 버전 범위를 따르기 때문에 최신 릴리스로 올라가지 않을 수 있어요. @latest를 붙인 npm install -g가 맞습니다.

새 버전은 다음 시작 때 적용된다

Claude Code는 시작할 때 한 번, 실행 중에 주기적으로 새 버전을 확인합니다. 받은 버전은 백그라운드에서 설치되고 다음에 시작할 때 적용돼요. 그래서 “업데이트했는데 버전이 그대로”의 상당수는 실패가 아니라 아직 다시 시작하지 않은 겁니다.

시작 직후의 확인은 2.1.238부터 실행 뒤 약 10초로 미뤄졌습니다. 시작할 때 CPU를 다투지 않게 하려는 변경입니다.

기다리지 않고 지금 받으려면 claude update(별칭 claude upgrade)를 실행합니다. 결과 문구는 상황에 따라 이렇게 나옵니다.

상황	문구
새 버전 설치	Successfully updated from <old version> to version <new version>
이미 최신	Claude Code is up to date (<version>)
Homebrew·WinGet·apk 설치본	Claude is up to date!

Windows에서 npm 설치본을 올렸을 때는 이렇게 나왔습니다. npm으로 깔았어도 claude update가 알아서 npm 쪽 방식으로 올려 주더라고요.

New version available: 2.1.296 (current: 2.1.286)
Installing update...
Using global installation update method...
Successfully updated from 2.1.286 to version 2.1.296

바로 한 번 더 실행하면 Claude Code is up to date (2.1.296)가 나옵니다. 이 뒤 npm ls -g @anthropic-ai/claude-code도 2.1.296을 가리켜서, 두 숫자가 어긋나지 않았어요. Homebrew·WinGet·apk의 Claude is up to date!는 직접 본 것이 아니라 공식 문서에 적힌 문구입니다.

claude update에는 버전을 고르는 옵션이 없습니다. 테스트 환경의 claude update --help에도 -h, --help 하나뿐이었어요.

특정 버전이나 채널로 가려면 claude install을 씁니다. 이미 깔려 있어도 다시 깔려면 --force를 붙이고요.

claude install 2.1.100   # 특정 버전
claude install stable    # stable 채널
claude install latest    # latest 채널

채널과 minimumVersion으로 범위 정하기

새 기능을 바로 받으려면 latest(기본값), 큰 문제가 있던 릴리스를 건너뛴 조금 묵은 버전을 원하면 stable입니다. stable은 보통 일주일쯤 된 버전이지만 정확히 일주일로 정해진 것은 아닙니다.

/config의 Auto-update channel에서 바꾸거나 설정 파일에 "autoUpdatesChannel": "stable"을 적으며, 이 값은 자동 업데이트와 claude update 양쪽에 적용됩니다. Homebrew만은 이 설정이 아니라 cask 이름이 채널을 정해요.

채널을 latest에서 stable로 내리면 지금보다 낮은 버전으로 내려갈 수 있습니다. 이걸 막는 것이 minimumVersion입니다.

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

• 이 값보다 낮은 버전은 자동 업데이트도 claude update도 설치하지 않습니다.
• /config로 채널을 내리면 지금 버전에 머물지, 내려가도 될지 묻습니다. 머물기를 고르면 minimumVersion이 지금 버전으로 정해지고, 나중에 latest로 돌아가면 지워집니다.

minimumVersion은 업데이트만 막을 뿐, 그보다 낮은 버전으로 Claude Code가 시작하는 것까지 막지는 않습니다.

시작 자체를 막으려면 조직 관리 설정의 requiredMinimumVersion·requiredMaximumVersion(2.1.163에 추가)을 씁니다. 업데이트도 requiredMaximumVersion보다 높게는 올라가지 않습니다.

설정 파일을 어느 계층에 둘지는 Claude Code 설정 파일 4계층에서 같은 키가 충돌할 때 이기는 자리에 정리했습니다.

DISABLE_AUTOUPDATER와 DISABLE_UPDATES

배경 업데이트만 끄려면 DISABLE_AUTOUPDATER, 손으로 올리는 것까지 막으려면 DISABLE_UPDATES입니다. 이름이 비슷해서 헷갈리는데, 막는 범위가 다릅니다.

변수("1"로 설정)	배경 업데이트	claude update·claude install
DISABLE_AUTOUPDATER	멈춤	그대로 됨
DISABLE_UPDATES	멈춤	막힘

설정 파일의 env 키에 {"env": {"DISABLE_AUTOUPDATER": "1"}}처럼 넣습니다. DISABLE_UPDATES(2.1.118에 추가)는 회사가 자체 채널로 배포하면서 사용자를 정해진 버전에 묶어 둘 때 씁니다.

적용됐는지는 claude doctor로 봅니다. 네이티브·npm 설치본에서 Auto-updates 줄이 enabled 대신 disabled (set by env: DISABLE_AUTOUPDATER)로 바뀌면 됩니다. Ubuntu와 Windows 테스트 환경의 줄도 글자까지 같았어요.

표의 “그대로 됨”도 Windows에서 확인했습니다. DISABLE_AUTOUPDATER가 켜진 채로 claude update를 실행했는데 2.1.296까지 정상으로 올라갔거든요.

껐는데 enabled로 남아 있다면 값을 넣은 설정 파일이 읽히지 않은 것이니, 값을 다시 적기 전에 어느 파일에 넣었는지부터 확인하세요.

반대로 Homebrew·WinGet을 자동으로 올리고 싶다면 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE를 1로 둡니다(2.1.129에 추가). 새 버전이 나오면 Claude Code가 백그라운드에서 업그레이드를 실행하고 성공하면 다시 시작하라고 알려 줍니다.

대상은 Claude Code 패키지 하나뿐입니다. apt·dnf·apk는 관리자 권한이 필요한 명령이라 이 변수를 켜도 명령을 보여 주기만 해요.

버전이 안 바뀔 때

1. Claude Code를 완전히 껐다 켭니다

새 버전은 다음 시작 때 적용되므로, 돌고 있는 세션이 하나라도 있으면 그대로입니다.

2. 설치본이 둘인지 확인합니다

그래도 같으면 claude doctor의 Running과 Path를 봅니다. 맨 앞에 적은 테스트 환경이 바로 이 경우였습니다.

명령	결과	가리키는 것
claude --version	2.1.284	PATH가 고른 실행 파일(네이티브)
npm ls -g @anthropic-ai/claude-code	2.1.42	npm에 남은 패키지

npm 쪽을 아무리 올려도 PATH가 네이티브 쪽을 고르면 claude --version은 그대로입니다. claude doctor가 경고와 함께 제시한 npm -g uninstall @anthropic-ai/claude-code로 남은 쪽을 지우면 됩니다.

Windows PowerShell이라면 (Get-Command claude).Source로 지금 잡히는 파일을 바로 볼 수 있습니다. npm 설치본이면 %APPDATA%\npm\claude.ps1이 나오고, 독립 설치본이면 %USERPROFILE%\.local\bin\claude.exe가 나와요.

3. 증상에 맞는 원인을 찾습니다

• Auto-updates가 계속 disabled: DISABLE_AUTOUPDATER가 설정 파일이나 셸 환경 변수 어딘가에 있습니다. 괄호 안이 (set by env: …)이고 설정 파일 쪽을 지워도 그대로면 셸이 내보내는 변수를 봅니다.
• 알림은 떴는데 패키지 관리자에 새 버전이 없음: 알려진 문제입니다. 패키지 관리자에 올라오기 전에 알림이 먼저 뜰 수 있으니 기다렸다 다시 합니다.
• WinGet 업그레이드 실패: Claude Code가 실행 중이면 Windows가 실행 파일을 잠가 실패할 수 있습니다. Claude Code가 보여 주는 명령대로, 모두 끈 뒤 winget upgrade Anthropic.ClaudeCode를 실행합니다. 2.1.169부터 자동 업데이터는 다른 프로세스가 claude.exe를 붙들고 있으면 세션 안에서 재시도를 멈추고, 2.1.217에서는 업데이트 실패로 claude.exe가 사라질 수 있던 문제가 고쳐져 보존해 둔 파일을 되살립니다.
• npm 설치본이 자동으로 안 올라감: npm 전역 폴더에 쓸 권한이 없는 경우입니다. 시작할 때 한 번 알림이 뜨고, 놓쳤다면 claude doctor가 해결책을 보여 줍니다.
• 직접 만든 실행 파일 링크가 그대로(macOS·Linux): ~/.local/bin/claude를 직접 만든 스크립트나 링크로 바꾸면 업데이트가 그 파일을 건드리지 않고, 새 버전은 ~/.local/share/claude/versions/ 아래에만 쌓입니다(2.1.207 이전엔 매번 덮어썼습니다). 다시 맡기려면 그 파일을 지우고 claude update를 실행합니다. 그대로 두면 어느 버전이 필요한지 알 수 없어 모든 버전이 디스크에 쌓입니다.
• claude update가 멈춤: 2.1.277에서 최소·최대 버전이 설정된 상태에서 프록시가 잘못된 버전 정보를 주면 30분마다 오류가 나고 멈추던 문제가, 2.1.214에서 셸 설정 경로가 폴더일 때 claude update·claude doctor가 멈추던 문제가 고쳐졌습니다. 그보다 낮은 버전이면 위 표의 수동 명령으로 올립니다.

업데이트해도 설정이나 인증 정보는 사라지지 않습니다. 업데이트가 바꾸는 것은 실행 파일이고, 설정과 상태는 홈 폴더의 .claude와 .claude.json에 따로 있거든요.

공식 삭제 절차도 둘을 나눠 두었고, 설정 파일까지 지워야 설정·허용 도구·MCP 서버 설정·세션 기록이 사라집니다. 그 폴더에 무엇이 있는지는 .claude 디렉터리에 무엇이 쌓이고 언제 읽히는지에 있습니다.

Homebrew는 업그레이드 뒤에도 옛 버전을 디스크에 남기니 가끔 brew cleanup을 실행하세요.

마치며

업데이트가 안 된다는 문제는 대개 업데이트 자체보다 “지금 어느 설치본이 도는가”와 “다시 시작했는가”에서 풀립니다. 테스트 환경에서도 claude --version과 npm ls -g가 서로 다른 숫자를 말했고, 둘을 이어 준 건 claude doctor의 Running 줄이었어요. 저는 업데이트 명령을 고르기 전에 이 줄부터 보길 권합니다.

claude doctor를 한 번 실행해 Running·Auto-updates·Auto-update channel 세 줄을 확인해 두세요. 업데이트를 마쳤다면 어떤 모델로 돌릴지 정할 차례이고, 그 방법은 Claude Code 모델을 바꾸는 다섯 자리와 우선순위에 있습니다.