클로드 코드 업데이트 — 명령어와 안 될 때
클로드 코드 업데이트는 터미널에서 claude update 한 줄이면 됩니다. 다만 설치 방식에 따라 자동 업데이트가 되는 것과 안 되는 것이 갈립니다. 공식 설치 스크립트(네이티브)와 npm은 백그라운드에서 알아서 올라가지만, 홈브루·WinGet·apt/dnf/apk로 깐 경우는 자동으로 올라가지 않아 직접 명령을 쳐야 합니다. 아래는 Claude Code 2.1.202 기준(2026년 7월 29일 확인)으로 설치 방식 확인 → 업데이트 명령 → 안 될 때 순서로 정리한 내용입니다.
1. 내가 어떻게 깔았는지부터 확인한다
업데이트 명령이 설치 방식마다 다르기 때문에, 먼저 지금 쓰는 claude가 어디서 온 것인지 봐야 합니다. macOS·리눅스라면 이렇게 확인합니다.
$ claude --version
2.1.202 (Claude Code)
$ which claude
/opt/homebrew/bin/claude
$ ls -l /opt/homebrew/bin/claude
lrwxr-xr-x 1 user admin 60 7 7 15:13 /opt/homebrew/bin/claude -> ../lib/node_modules/@anthropic-ai/claude-code/bin/claude.exe/opt/homebrew/bin)에 있지만 실제로는 npm 전역 설치입니다. 심볼릭 링크가 lib/node_modules/@anthropic-ai/claude-code를 가리키고 있고, brew list --cask에도 잡히지 않습니다. 홈브루로 깐 Node를 쓰면 npm 전역 패키지도 이 경로에 들어가기 때문입니다.
판별 기준은 다음과 같습니다.
| 확인 명령 | 여기에 잡히면 |
|---|---|
ls ~/.local/bin/claude |
네이티브 설치(공식 install.sh). 버전 파일은 ~/.local/share/claude/versions/에 쌓입니다. |
npm ls -g --depth=0 |
npm 전역 설치. @anthropic-ai/claude-code@2.1.202처럼 버전까지 나옵니다. |
brew list --cask |
홈브루 설치. 캐스크 이름이 claude-code인지 claude-code@latest인지 함께 봅니다. |
아직 설치 전이거나 방식을 바꾸고 싶다면 클로드 코드 설치 글에 운영체제별 설치 명령을 정리해 두었습니다.
2. 설치 방식별 업데이트 명령어
공통으로 쓸 수 있는 건 claude update입니다(claude upgrade도 같은 명령의 별칭입니다). 다만 홈브루·WinGet·리눅스 패키지 매니저로 깐 경우 이 명령은 실제 업그레이드를 하지 않고 Claude is up to date!만 찍으므로, 각 패키지 매니저 명령을 써야 합니다.
| 설치 방식 | 업데이트 명령 | 자동 업데이트 |
|---|---|---|
| 네이티브(install.sh / install.ps1) | claude update |
✅ 백그라운드로 자동 |
| npm 전역 | npm install -g @anthropic-ai/claude-code@latest |
✅ (전역 디렉터리에 쓰기 권한이 있을 때) |
| 홈브루 | brew upgrade claude-code 또는 brew upgrade claude-code@latest |
❌ 수동 |
| WinGet | winget upgrade Anthropic.ClaudeCode |
❌ 수동 |
| apt (Debian·Ubuntu) | sudo apt update && sudo apt upgrade claude-code |
❌ 수동 |
| dnf / apk | sudo dnf upgrade claude-code · apk update && apk upgrade claude-code |
❌ 수동 |
업데이트가 실제로 설치되면 Successfully updated from <옛 버전> to version <새 버전>, 이미 최신이면 Claude Code is up to date (<버전>)이 출력됩니다.
npm update -g를 쓰지 마세요. 처음 설치할 때의 semver 범위를 지켜서, 최신 릴리스로 안 올라갈 수 있습니다. @latest를 붙인 npm install -g가 확실합니다. 또 sudo npm install -g는 권한 문제를 만드니 피하라고 공식 문서가 못박고 있습니다.
3. 지금 최신 버전인지 확인하는 법
내 버전은 claude --version으로 보고, 배포된 최신 버전은 설치 방식에 맞춰 확인합니다. npm이라면 레지스트리를 직접 조회하는 게 가장 빠릅니다.
# 내 버전
$ claude --version
2.1.202 (Claude Code)
# npm 레지스트리의 최신 버전
$ npm view @anthropic-ai/claude-code version
2.1.220
# 홈브루 캐스크가 들고 있는 버전
$ brew info --cask claude-code
==> claude-code (Claude Code): 2.1.212위 출력처럼 같은 시점에도 경로마다 버전이 다릅니다. npm 레지스트리가 2.1.220일 때 홈브루 캐스크는 2.1.212였습니다. 홈브루 claude-code 캐스크는 안정(stable) 채널을 따라가서 보통 일주일쯤 뒤처지고, claude-code@latest 캐스크가 최신 채널을 받습니다.
4. 자동 업데이트는 언제 도나 — 채널과 최소 버전
클로드 코드는 시작할 때와 실행 중 주기적으로 업데이트를 확인합니다. 내려받은 새 버전은 백그라운드에서 설치되고, 다음에 클로드 코드를 새로 켤 때 적용됩니다. 그래서 업데이트 알림을 봤다고 지금 세션이 바로 바뀌지는 않습니다.
받는 속도는 릴리스 채널로 조절합니다. settings.json에 넣거나 클로드 코드 안에서 /config → Auto-update channel로 고릅니다. 설정 파일과 슬래시 명령은 클로드 코드 슬래시 명령어 글에서 함께 정리했습니다.
{
"autoUpdatesChannel": "stable",
"minimumVersion": "2.1.100"
}"latest"(기본값) — 릴리스되는 대로 바로 받습니다."stable"— 대략 일주일 지난 버전을 씁니다. 큰 회귀가 있는 릴리스는 건너뜁니다.minimumVersion— 이 값보다 낮은 버전은 자동 업데이트도claude update도 설치하지 않습니다. 최신 채널에서 안정 채널로 옮길 때 버전이 내려가는 걸 막는 바닥값입니다.
홈브루는 이 설정 대신 캐스크 이름으로 채널이 결정됩니다(claude-code=stable, claude-code@latest=latest).
5. 자동 업데이트 끄기 — 두 단계가 다르다
버전을 고정해야 하는 환경이면 환경변수로 막습니다. 두 변수의 차단 범위가 다릅니다.
{
"env": {
"DISABLE_AUTOUPDATER": "1"
}
}| 환경변수 | 막는 것 |
|---|---|
DISABLE_AUTOUPDATER=1 |
백그라운드 자동 확인만 끕니다. claude update·claude install은 그대로 동작합니다. |
DISABLE_UPDATES=1 |
수동 업데이트까지 전부 막습니다. 사내에서 배포 버전을 통제할 때 씁니다. |
DISABLE_UPDATES=1을 준 상태로 업데이트를 시도하면 이렇게 거절당합니다. 실제로 실행해 본 출력입니다.
$ DISABLE_UPDATES=1 claude update
Updates are disabled by your administrator. Contact your IT team to get the latest version.회사 노트북에서 이 문구가 뜬다면 명령이 잘못된 게 아니라 관리형 설정으로 업데이트가 막혀 있는 것입니다.
6. 클로드 코드 업데이트 안 될 때 확인할 것
① 홈브루·WinGet·apt로 깔았다 — 이 방식들은 기본적으로 자동 업데이트를 하지 않습니다. 2번 표의 명령을 직접 실행하세요. 홈브루·WinGet은 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE를 1로 두면 클로드 코드가 대신 업그레이드 명령을 백그라운드로 돌려 줍니다(apt·dnf·apk는 권한이 필요해 계속 수동입니다).
② npm 전역 디렉터리에 쓰기 권한이 없다 — 자동 업데이트가 조용히 실패하고, 시작할 때 1회 안내가 뜹니다. npm 권한 문제로 계속 막힌다면 공식 문서는 네이티브 설치로 갈아타라고 안내합니다.
curl -fsSL https://claude.ai/install.sh | bash③ 런처를 직접 바꿔 놨다 — macOS·리눅스 네이티브 설치는 ~/.local/bin/claude를 ~/.local/share/claude/versions/ 아래로 연결하는 심볼릭 링크로 관리합니다. 이 자리를 사용자가 만든 스크립트로 바꿔 두면 새 버전은 versions/에만 쌓이고 실행되는 버전은 그대로입니다. 다시 맡기려면 ~/.local/bin/claude를 지우고 claude update를 실행합니다.
④ npm 설치인데 claude가 아예 안 뜬다 — npm 패키지는 플랫폼별 바이너리를 선택적 의존성으로 받은 뒤 postinstall에서 자리를 잡습니다. --ignore-scripts나 --omit=optional로 설치하면 이 단계가 건너뛰어져 Error: claude native binary not installed.가 납니다. 해당 플래그를 빼고 다시 설치하는 게 정답입니다.
claude doctor가 가장 최근 업데이트 시도의 결과와 설치 상태를 진단해 줍니다. 세션을 시작하지 않고 읽기 전용으로 확인만 합니다.
자주 묻는 질문 (FAQ)
Q. claude update와 claude install은 뭐가 다른가요?
update는 새 버전이 있으면 받아서 설치하는 명령이고, install은 네이티브 빌드를 설치하는 명령입니다. install은 대상을 지정할 수 있어서 claude install stable이나 claude install 2.1.89처럼 채널·특정 버전을 골라 깔 수 있습니다.
Q. 특정 버전으로 되돌릴 수 있나요?
네이티브 설치 스크립트에 버전을 넘기면 됩니다. curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89처럼 실행한 뒤 claude --version이 그 버전을 찍는지 확인하세요.
Q. 업데이트했는데 왜 버전이 그대로인가요?
새 버전은 다음 실행부터 적용됩니다. 켜 둔 세션을 끄고 다시 시작한 뒤 claude --version을 확인하세요. 그래도 그대로면 위 6번의 ③번(런처 교체)이나 설치 방식 중복을 의심합니다.
Q. 홈브루 업그레이드 후 디스크가 계속 차는데요?
홈브루는 업그레이드 후에도 예전 버전을 남겨 둡니다. brew cleanup을 가끔 돌려 정리하면 됩니다.
마무리
정리하면 이렇습니다. 업데이트 명령은 claude update지만, 그게 실제로 먹히는지는 설치 방식이 결정합니다. 네이티브와 npm은 자동으로 올라가고, 홈브루·WinGet·리눅스 패키지 매니저는 직접 명령을 쳐야 합니다. 버전이 안 바뀐다면 ① 설치 방식 확인(which claude) → ② 그 방식의 업그레이드 명령 실행 → ③ 클로드 코드를 껐다 켜고 claude --version 확인 순서로 좁혀 가면 대부분 해결됩니다. 버전마다 명령과 설정 이름이 바뀔 수 있으니, 막히면 공식 문서의 Advanced setup 페이지를 함께 확인하는 것을 권합니다.
📚 참고 출처 (2026년 7월 29일 확인 · Claude Code 2.1.202 기준)
· Claude Code — Advanced setup (Update Claude Code)
· Claude Code — Environment variables
· Claude Code — Troubleshoot installation and login
COMMENTS