개발자가 쓰는 AI 일기: 클로드 코드(Claude Code) 업데이트 완벽 가이드

클로드 코드는 거의 매일 새 버전이 나올 정도로 빠르게 발전하고 있습니다. 글 작성 시점 기준 npm에 올라온 @anthropic-ai/claude-code 패키지의 최신 버전은 **2.1.119**이며, 며칠 단위로 새 릴리스가 푸시되고 있죠. 새 모델 지원, 버그 수정, 토큰 한도 확장 같은 굵직한 변경사항이 자주 들어오기 때문에 버전을 최신으로 유지하는 것이 곧 생산성과 직결됩니다.

이번 글에서는 설치 방법별로 클로드 코드를 업데이트하는 방법을 정리하고, 자동 업데이트 채널 설정과 자주 마주치는 오류 해결법까지 한 번에 다뤄봅니다.

0. 먼저 내 설치 방식이 무엇인지 확인하기

업데이트 명령어는 어떻게 설치했느냐에 따라 완전히 달라집니다. 터미널을 열고 다음 명령으로 현재 버전과 설치 위치부터 확인하세요.

claude --version
which claude        # macOS / Linux / WSL
where claude        # Windows CMD
Get-Command claude  # Windows PowerShell

경로를 보면 설치 방식을 가늠할 수 있습니다.

경로 패턴	설치 방식
`~/.local/bin/claude` 또는 `~/.local/share/claude/...`	네이티브 인스톨러 (공식 권장)
`/opt/homebrew/...` 또는 `/usr/local/Cellar/...`	Homebrew
`~/.npm-global/...`, `~/.nvm/versions/node/...`	npm 글로벌
`C:\Program Files\WinGet\...`	WinGet
`/usr/bin/claude` (apt/dnf/apk 패키지)	리눅스 패키지 매니저

설치 환경 전반을 점검하려면 claude doctor 명령이 더 친절합니다. 누락된 의존성이나 권한 문제까지 함께 짚어주거든요. 이미 클로드 코드 세션에 들어와 있다면 슬래시 명령 /doctor로도 동일한 진단을 돌릴 수 있습니다.

1. 네이티브 인스톨러 — 백그라운드에서 알아서 업데이트

curl ... | bash 또는 irm ... | iex로 설치한 경우입니다. 가장 신경 쓸 일이 적은 방식으로, 클로드 코드가 시작할 때와 실행 중 주기적으로 알아서 최신 버전을 확인하고 백그라운드에서 다운로드합니다. 다음번 실행 시 새 버전이 적용되죠.

즉시 업데이트하고 싶다면

백그라운드 체크를 기다릴 수 없을 때는 직접 명령을 내립니다.

claude update

릴리스 채널 선택하기

네이티브 설치는 두 가지 채널 중 하나를 따릅니다.

latest (기본값): 새 기능이 출시되는 즉시 받습니다. 새것 좋아하는 분, 최신 모델을 빨리 써보고 싶은 분에게 적합합니다.
stable: 보통 1주 정도 늦게 도착하지만, 큰 회귀(regression)가 발견된 릴리스는 건너뜁니다. 안정성이 중요한 환경에 추천합니다.

채널은 클로드 코드 안에서 /config를 실행하고 Auto-update channel 항목에서 바꾸거나, ~/.claude/settings.json에 직접 적어줄 수 있습니다.

{
  "autoUpdatesChannel": "stable"
}

다운그레이드 방지 — `minimumVersion` 설정

latest로 잘 쓰다가 stable로 옮길 때, 현재 버전이 stable 채널 최신보다 더 높다면 의도치 않게 다운그레이드될 수 있습니다. 이를 막기 위해 최소 버전을 못 박을 수 있어요.

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

이렇게 해두면 백그라운드 업데이트와 claude update가 이 버전 미만으로는 절대 내려가지 않습니다. 기업 환경에서는 관리자 정책(managed settings)으로 조직 전체에 강제할 수도 있습니다.

자동 업데이트 끄기

자동 업데이트가 거슬린다면 환경 변수로 끌 수 있습니다.

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

DISABLE_AUTOUPDATER는 백그라운드 체크만 막을 뿐, claude update를 직접 실행하면 여전히 동작합니다. 모든 업데이트 경로를 차단하려면 DISABLE_UPDATES를 사용하세요. 사내 배포 채널을 통해 특정 버전을 강제로 유지해야 하는 경우에 쓰입니다.

2. Homebrew (macOS / Linux) — 자동 업데이트 안 됨

Homebrew는 자동 업데이트되지 않습니다. 직접 명령을 실행해야 합니다.

# stable 채널로 설치한 경우
brew upgrade claude-code

# latest 채널로 설치한 경우
brew upgrade claude-code@latest

Homebrew는 두 개의 cask를 제공하며, cask 이름 자체가 채널을 결정합니다. autoUpdatesChannel 설정이 아니라 어떤 cask를 깔았는지가 중요해요. 헷갈리면 brew list --cask | grep claude로 확인할 수 있습니다.

또 한 가지 — Homebrew는 업그레이드 후에도 옛 버전을 디스크에 남겨둡니다. 디스크 공간이 아쉬우면 가끔 정리해주세요.

brew cleanup

⚠️ Homebrew 사용자가 주의할 함정

claude-code (stable) cask로 설치했는데 autoUpdatesChannel이 "latest"로 되어 있으면 순환 데드락이 생깁니다. 그런데 이 채널 설정의 **기본값이 "latest"**라서 별도로 만진 적이 없어도 이 함정에 빠질 수 있다는 게 문제예요. 인앱에서는 "업데이트 가능: 2.1.x → 2.1.y"라고 친절하게 알려주지만, 정작 brew upgrade claude-code를 실행하면 stable 채널의 더 낮은 버전만 받을 수 있어서 알림 속 버전을 영영 받지 못하는 상황이 생기죠.

해결책은 둘 중 하나입니다.

채널을 stable로 통일: ~/.claude/settings.json에서 autoUpdatesChannel을 "stable"로 두거나 아예 설정을 지웁니다. 그러면 인앱 알림도 stable 채널 기준으로 뜹니다.
latest cask로 갈아타기: 최신 버전을 빨리 받고 싶다면 brew uninstall claude-code && brew install --cask claude-code@latest로 옮긴 뒤 autoUpdatesChannel을 "latest"로 두세요.

요지는 **"설치한 cask와 autoUpdatesChannel의 채널을 맞추라"**는 것입니다.

3. WinGet (Windows) — 정기적인 수동 업그레이드

WinGet 역시 자동 업데이트가 없습니다. PowerShell에서 주기적으로 실행해주세요.

winget upgrade Anthropic.ClaudeCode

설치된 모든 패키지를 한꺼번에 올리고 싶다면 winget upgrade --all도 가능합니다.

4. 리눅스 패키지 매니저 (apt / dnf / apk)

apt, dnf, apk로 설치했다면 시스템 업그레이드 워크플로의 일부로 함께 올라갑니다.

# Debian / Ubuntu
sudo apt update && sudo apt upgrade claude-code

# Fedora / RHEL
sudo dnf upgrade claude-code

# Alpine
apk update && apk upgrade claude-code

이 방식의 장점은 시스템 전체 업데이트와 동일한 사이클로 관리된다는 점입니다. CI/CD 빌드 이미지나 서버 환경에서 특히 깔끔하죠.

5. npm 글로벌 패키지

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

이 명령은 설치할 때도, 업데이트할 때도 동일하게 사용합니다. 같은 명령어를 다시 실행하면 npm이 최신 버전으로 갱신해줍니다. 특정 버전을 고정해서 깔고 싶다면 @ 뒤에 버전을 붙이세요.

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

주의: sudo npm install -g는 사용하지 마세요. 권한 꼬임과 보안 이슈의 주범입니다. 권한 에러가 난다면 npm 글로벌 prefix를 홈 디렉토리(~/.npm-global 등)로 바꾸거나 nvm을 쓰는 쪽으로 정비하는 게 정답입니다.

pnpm 사용자라면 동일한 의미로 pnpm add -g @anthropic-ai/claude-code를 실행합니다.

6. 업데이트 후 확인

업데이트가 끝났으면 새 버전이 잘 잡혔는지 점검합니다.

claude --version

새로 들어온 변경사항이 궁금하다면 클로드 코드 안에서 슬래시 명령을 써보세요.

/release-notes

최근 릴리스의 주요 변경점을 바로 띄워줍니다. 전체 변경 이력은 GitHub의 CHANGELOG에서 확인할 수 있습니다.

7. 자주 마주치는 업데이트 오류와 해결

"Another Claude process is currently running" / "another process is currently installing"

설치나 업데이트 도중 프로세스가 비정상 종료되면, 인스톨러가 만들어둔 PID 락 파일이 남아 다음 시도를 막습니다. 헷갈리기 쉬운 점은 이 락 파일이 ~/.claude가 아니라 **XDG 표준 경로인 ~/.local/state/claude/locks/**에 있다는 것입니다. ~/.claude를 아무리 뒤져도 못 찾는 이유가 여기에 있죠.

# 어떤 락 파일이 있는지 확인
ls ~/.local/state/claude/locks/

# 해당 PID가 실제로 살아있는지 확인 (없으면 stale 락)
ps -p <PID>

# stale이라고 판단되면 삭제
rm ~/.local/state/claude/locks/*.lock

락 파일을 비운 뒤에도 시스템 프로세스 목록에 떠 있는 claude 프로세스가 있다면 함께 정리하고 재시도하세요.

macOS의 `ENOTEMPTY` npm 에러

macOS(Sonoma 이상)에서 npm으로 클로드 코드를 업데이트할 때 자주 발생하는 문제입니다. 클로드 코드 자체의 버그가 아니라 APFS 파일 잠금 때문에 npm이 폴더 이름을 바꾸지 못해 일어납니다. 해결 절차는 다음과 같습니다.

# 1) 기존 설치 제거
rm -rf $(npm config get prefix)/lib/node_modules/@anthropic-ai/claude-code

# 2) 숨겨진 임시 폴더 제거 (이 단계가 핵심)
rm -rf $(npm config get prefix)/lib/node_modules/@anthropic-ai/.claude-code-*

# 3) 캐시 정리
npm cache clean --force

# 4) 재설치
npm install -g @anthropic-ai/claude-code

2번 단계에서 지우는 .claude-code-* 형태의 숨김 폴더가 바로 ENOTEMPTY 에러의 원인이라 빠뜨리면 안 됩니다.

네이티브 설치인데 `claude update`가 npm-global로 인식하는 경우

PATH에서 nvm의 bin 디렉토리가 ~/.local/bin보다 우선순위가 높을 때 발생할 수 있는 알려진 이슈입니다. 이 경우 claude update가 네이티브 심링크를 지우고 npm 패키지로 덮어써버리니, npm 글로벌 패키지가 깔려 있다면 먼저 제거한 뒤 네이티브 인스톨러를 다시 실행하는 것이 안전합니다.

npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash

권한 에러

EACCES: permission denied

처음에 sudo로 npm 글로벌 설치를 했을 때 자주 나옵니다. npm 글로벌 디렉토리의 소유권을 본인 계정으로 되돌리거나, ~/.npm-global 같은 사용자 영역으로 prefix를 옮기는 것이 근본 해법입니다.

마무리 — 어떤 방식을 추천하나?

개인 개발 환경이라면 네이티브 인스톨러 + latest 채널 조합이 가장 손이 덜 갑니다. 백그라운드에서 알아서 갱신되고, 새 모델이 풀리면 가장 빨리 써볼 수 있습니다.

팀이나 회사에서 여러 명이 함께 쓴다면 stable 채널 + minimumVersion 고정 또는 리눅스 패키지 매니저 기반 배포가 안정적입니다. 회귀 이슈가 있는 릴리스를 자동으로 피해 가면서, 조직 전체가 같은 버전대를 유지할 수 있거든요.

CI/CD 환경이라면 npm으로 버전을 명시적으로 고정하고(@2.1.100처럼), 업데이트는 PR을 통해 의도적으로 올리는 방식이 재현성 측면에서 가장 깔끔합니다.

참고 자료

공식 문서 (Advanced setup): https://code.claude.com/docs/en/setup
npm 패키지: https://www.npmjs.com/package/@anthropic-ai/claude-code
GitHub CHANGELOG: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md

개발자가 쓰는 AI 일기

2026년 4월 25일 토요일

클로드 코드(Claude Code) 업데이트 완벽 가이드 — 설치 방법별 최신 버전 유지하기

0. 먼저 내 설치 방식이 무엇인지 확인하기

1. 네이티브 인스톨러 — 백그라운드에서 알아서 업데이트

즉시 업데이트하고 싶다면

릴리스 채널 선택하기

다운그레이드 방지 — `minimumVersion` 설정

자동 업데이트 끄기

2. Homebrew (macOS / Linux) — 자동 업데이트 안 됨

⚠️ Homebrew 사용자가 주의할 함정

3. WinGet (Windows) — 정기적인 수동 업그레이드

4. 리눅스 패키지 매니저 (apt / dnf / apk)

5. npm 글로벌 패키지

6. 업데이트 후 확인

7. 자주 마주치는 업데이트 오류와 해결

"Another Claude process is currently running" / "another process is currently installing"

macOS의 `ENOTEMPTY` npm 에러

네이티브 설치인데 `claude update`가 npm-global로 인식하는 경우

권한 에러

마무리 — 어떤 방식을 추천하나?

댓글 없음:

댓글 쓰기

2026년 4월 25일 토요일

클로드 코드(Claude Code) 업데이트 완벽 가이드 — 설치 방법별 최신 버전 유지하기

0. 먼저 내 설치 방식이 무엇인지 확인하기

1. 네이티브 인스톨러 — 백그라운드에서 알아서 업데이트

즉시 업데이트하고 싶다면

릴리스 채널 선택하기

다운그레이드 방지 — minimumVersion 설정

자동 업데이트 끄기

2. Homebrew (macOS / Linux) — 자동 업데이트 안 됨

⚠️ Homebrew 사용자가 주의할 함정

3. WinGet (Windows) — 정기적인 수동 업그레이드

4. 리눅스 패키지 매니저 (apt / dnf / apk)

5. npm 글로벌 패키지

6. 업데이트 후 확인

7. 자주 마주치는 업데이트 오류와 해결

"Another Claude process is currently running" / "another process is currently installing"

macOS의 ENOTEMPTY npm 에러

네이티브 설치인데 claude update가 npm-global로 인식하는 경우

권한 에러

마무리 — 어떤 방식을 추천하나?

댓글 없음:

댓글 쓰기

다운그레이드 방지 — `minimumVersion` 설정

macOS의 `ENOTEMPTY` npm 에러

네이티브 설치인데 `claude update`가 npm-global로 인식하는 경우