Claude Code 업데이트하는 법 — 최신 버전 확인과 수동 업데이트

Claude Code 업데이트는 대부분 명령어 한 줄로 끝나지만, 처음 쓰는 분들은 "지금 내 버전이 몇인지", "자동 업데이트가 도는지", "권한 오류가 뜨면 어떻게 하는지"에서 막힙니다. 이 글은 맥과 윈도우 모두에서 Claude Code를 최신 버전으로 유지하는 순서를 정리합니다. 저도 처음엔 재설치만 반복하다가, 원인이 설치 경로 하나였다는 걸 뒤늦게 알았습니다. 결론부터 살짝 말하자면 대부분은 claude update 한 줄이면 되고, 안 되면 npm 재설치로 넘어가면 됩니다.

Claude Code 업데이트, 왜 자주 해야 하나

Claude Code는 Anthropic이 만든 터미널(검은 화면에 명령어를 입력하는 프로그램)에서 돌아가는 AI 코딩 도구입니다. ChatGPT처럼 웹에서 쓰는 게 아니라, 내 컴퓨터에 설치해서 폴더째 코드를 맡기는 형태죠.

이 도구는 업데이트 주기가 굉장히 빠릅니다. 제가 체감하기로도 일주일에 두세 번은 새 버전이 올라옵니다. 새 모델(Sonnet, Opus 등) 지원, 버그 수정, 성능 개선이 계속 붙기 때문이죠.

문제는 오래된 버전을 쓰면 이런 게 생깁니다.

증상	원인 가능성
새 모델이 선택 목록에 없음	모델 지원 코드가 빠진 구버전
갑자기 응답이 느려짐	서버측 API 변경에 못 따라감
MCP·서브에이전트 기능 오류	최신 기능이 구버전에 없음
deprecated 경고 문구	곧 지원 종료 예정

특히 "어제까진 됐는데 오늘 갑자기 이상하다" 싶으면 90%는 업데이트 문제입니다.

현재 버전부터 확인하기

업데이트 전에 지금 내 버전이 뭔지 먼저 봅니다. 터미널(맥은 Terminal 앱, 윈도우는 PowerShell 또는 WSL)을 열고 아래 명령어를 칩니다.

claude --version

이 명령은 "Claude야, 네 버전 좀 알려줘"라는 뜻입니다. 결과는 이런 식으로 뜹니다.

1.0.44 (Claude Code)

앞의 숫자가 버전입니다. 이 숫자를 Anthropic 공식 GitHub 릴리스 페이지의 최신 버전과 비교하면 됩니다. 차이가 크면(예: 1.0.20인데 최신이 1.0.60) 업데이트가 밀린 겁니다.

💡 claude: command not found 오류가 뜨면 아직 설치 자체가 안 됐거나 PATH 설정 문제입니다. 이 경우엔 업데이트가 아니라 설치 가이드부터 봐야 합니다.

가장 쉬운 방법: 내장 명령어로 업데이트

Claude Code에는 자체 업데이트 명령이 들어있습니다. 가장 먼저 시도할 방법입니다.

claude update

이 명령을 치면 최신 버전을 확인해서 자동으로 받아 설치합니다. 저는 보통 이걸로 끝납니다. 소요 시간은 인터넷 속도에 따라 다르지만 대략 10~30초 정도입니다.

성공하면 이런 메시지가 뜹니다.

Updated to version 1.0.60

이미 최신이면 "already up to date" 비슷한 문구가 뜨고 아무 일도 일어나지 않습니다.

실행 중일 땐 어떻게 하나

Claude Code를 켜놓은 상태에서 업데이트가 감지되면, 화면 아래쪽에 "Update available" 같은 알림이 뜹니다. 이럴 땐 세션을 한 번 종료(/exit 입력 또는 Ctrl+C 두 번)한 뒤 위 명령을 치는 게 안전합니다. 켜둔 채로 업데이트하면 파일이 반쯤 덮어써져서 다음 실행 때 이상하게 꼬이는 경우를 겪었습니다.

npm으로 수동 업데이트하기

claude update가 실패하거나, "업데이트했다는데 버전이 그대로"인 경우가 있습니다. 이럴 땐 npm(Node.js에 딸려오는 패키지 설치 도구, 앱스토어의 명령어 버전이라고 보면 됩니다) 으로 직접 재설치합니다.

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

-g는 "이 컴퓨터 전체에서 쓸 수 있게 설치"라는 옵션입니다. 없으면 현재 폴더에만 깔려서 어디서든 claude를 못 부릅니다.

설치가 끝나면 다시 버전을 확인합니다.

claude --version

숫자가 올라갔으면 성공입니다.

캐시가 꼬여 있을 때

가끔 npm이 예전 버전을 캐시(임시 저장)에서 꺼내와서 아무리 재설치해도 그대로인 경우가 있습니다. 이럴 땐 캐시를 지우고 다시 설치합니다.

npm cache clean --force
npm install -g @anthropic-ai/claude-code

저는 회사에서 쓰던 노트북에서 이 증상을 겪었는데, 캐시 청소 한 번으로 해결됐습니다. 원인은 오래 방치한 npm 캐시였습니다.

권한 오류(EACCES)가 뜰 때

맥·리눅스에서 npm install -g 명령을 치면 이런 오류가 뜰 수 있습니다.

npm ERR! code EACCES
npm ERR! permission denied

"관리자 권한이 없어서 못 쓴다"는 뜻입니다. 흔한 해결법 두 가지가 있습니다.

1) sudo 붙이기 (빠르지만 비추)

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

sudo는 "관리자 권한으로 실행" 명령입니다. 되긴 되는데, 이후에 다른 npm 도구를 쓸 때도 계속 sudo가 필요해지는 부작용이 있어서 권장되지 않습니다.

2) npm 설치 경로를 홈 폴더로 바꾸기 (권장)

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

그다음 셸 설정 파일(맥 기본은 ~/.zshrc)에 아래 한 줄을 추가합니다.

export PATH=~/.npm-global/bin:$PATH

이 줄은 "명령어를 찾을 때 이 폴더도 뒤져라"라는 지시입니다. 저장 후 터미널을 껐다 켜거나 source ~/.zshrc를 치면 적용됩니다. 이 방법이 처음엔 번거로워도 앞으로의 npm 도구 설치 전부를 편하게 만들어줍니다.

자동 업데이트 켜고 끄기

Claude Code는 기본적으로 백그라운드에서 자동 업데이트를 시도합니다. 이게 싫으면(예: 사내 정책상 버전을 고정해야 하는 분) 끌 수 있습니다.

claude config set auto-updater-status disabled

다시 켜려면 disabled 자리에 enabled를 넣으면 됩니다. 공식 문서 기준으로 이 설정은 사용자별로 저장됩니다.

저는 개인 작업에선 자동 업데이트를 켜두는 편입니다. 매번 신경 쓰기 귀찮고, 어차피 하위 호환이 대체로 잘 지켜지기 때문입니다. 다만 중요한 프로젝트 마감 직전에는 새 버전이 예상 못한 문제를 일으킬 수 있으니 잠시 꺼두는 것도 방법입니다.

업데이트 후 확인해야 할 것

버전이 올라갔다고 끝이 아닙니다. 저는 업데이트 후 항상 이 세 가지를 확인합니다.

• [ ] claude --version으로 새 버전 숫자 재확인
• [ ] 짧은 프롬프트 하나로 응답 정상 확인 ("hello" 정도면 충분)
• [ ] 자주 쓰는 커스텀 명령어(/로 시작하는 것들)가 그대로 동작하는지

특히 세 번째가 중요합니다. 메이저 버전(1.x → 2.x)이 바뀔 때는 명령어 문법이 살짝 바뀌기도 합니다. Anthropic 공식 릴리스 노트에 "breaking change"라는 문구가 있으면 그 부분은 반드시 확인해야 합니다.

자주 막히는 부분

"업데이트했는데 버전이 안 바뀝니다"

이건 십중팔구 Claude Code가 두 군데에 설치돼 있는 경우입니다. 예를 들어 예전에 홈브루로 한 번 깔고, 지금은 npm으로 또 깔았다면 명령어가 옛날 것을 부르고 있을 수 있습니다.

which claude

이 명령으로 지금 어느 경로의 claude가 불리는지 확인해봅니다. 예상한 경로가 아니라면 옛날 것을 지우고 하나만 남기는 게 깔끔합니다.

"윈도우에서 명령어가 아예 안 먹어요"

Anthropic은 공식적으로 WSL(윈도우에서 리눅스를 돌리는 기능) 사용을 권장합니다. 순수 윈도우 PowerShell에서는 일부 기능이 제한될 수 있습니다. 안 되면 WSL 안에서 다시 설치·업데이트하는 게 빠릅니다.

"업데이트 후 API 키가 사라졌어요"

거의 없는 케이스지만, 메이저 버전 업데이트 때 설정 파일 위치가 바뀌면 일어날 수 있습니다. claude login 또는 claude auth로 다시 로그인하면 됩니다. 결제·크레딧은 계정에 묶여 있으니 사라지지 않습니다.

마무리

정말 대부분은 claude update 한 줄이면 끝납니다. 안 되면 npm install -g @anthropic-ai/claude-code로 재설치, 권한 오류가 나면 npm 경로를 홈 폴더로 옮기는 순서로 접근하면 거의 다 해결됩니다.

새 버전이 나올 때마다 릴리스 노트를 훑는 습관을 붙이면 좋습니다. 어떤 기능이 새로 생겼는지 알고 있어야 나중에 "아 이거 됐지" 하면서 써먹을 수 있으니까요. 오늘은 일단 claude --version 한 번 쳐보시고, 버전이 밀려 있다면 업데이트부터 돌려보시길 권합니다.

함께 보면 좋은 글

• Claude Code 자주 막히는 에러 10가지 한국어 해결법
• Claude Code "command not found" 에러 해결법 7가지
• Claude Artifacts로 가계부 앱 직접 만들기 — 코딩 0줄 따라하기