Claude Code 쓰다 보면 가끔 새 기능이 추가됐다는 얘기가 들리는데, 정작 내 버전에서는 안 되는 경우가 있습니다. 이럴 때 업데이트가 필요한데, 방법이 여러 가지라 헷갈리는 분들이 많습니다.
오늘은 Claude Code를 최신 버전으로 업그레이드하는 방법을 정리해봤습니다.
일단 자동 업데이트가 기본입니다
사실 Claude Code는 별도로 뭔가 안 해도 자동으로 업데이트됩니다. 시작할 때나 실행 중에 주기적으로 새 버전이 있는지 확인하고, 있으면 백그라운드에서 알아서 다운로드합니다.
하지만 자동 업데이트가 진행되지않거나 예외적인 환경이 있을테니 아래 각 목차별 해당하는 부분을 확인해주세요.
업데이트가 완료되면 알림이 뜨고, 다음에 Claude Code를 다시 실행하면 새 버전이 적용됩니다.
자동 업데이트가 싫은 분들도 있을 겁니다. 그럴 때는 환경 변수 하나만 설정하면 됩니다.
export DISABLE_AUTOUPDATER=1
settings.json에서도 설정 가능합니다.
Homebrew / WinGet으로 설치한 경우
Homebrew나 WinGet으로 설치한 경우에는 해당 패키지 매니저를 통해 수동으로 업데이트해야 합니다.
Homebrew (macOS)
brew upgrade claude-code
WinGet (Windows)
winget upgrade Anthropic.ClaudeCode
참고로 Claude Code가 새 버전이 나왔다고 알림을 띄워도 패키지 매니저에는 아직 안 올라온 경우가 있습니다. 업그레이드 실패하면 좀 기다렸다가 다시 시도하면 됩니다.
수동으로 바로 업데이트하기
자동 업데이트 기다리기 싫고 지금 당장 최신 버전 쓰고 싶다면 이 명령어 하나면 됩니다.
claude update
끝입니다. 진짜 간단합니다.
근데 여기서 주의할 점이 있습니다. 예전에 NPM으로 Claude Code를 설치한 경우에는 claude update가 안 됩니다. 저도 NPM으로 설치해서 쓰고 있었는데, claude update 쳐도 업데이트가 안 됐습니다.
이런 경우에는 아래 설치 스크립트로 직접 설치하거나, 네이티브 설치로 마이그레이션해야 합니다.
최신 개발 버전, 특정 버전으로 설치하고 싶을 때
가끔 최신 버전에서 버그가 생겨서 이전 버전으로 돌아가야 하거나, 반대로 아직 정식 출시 안 된 최신 개발 버전을 써보고 싶을 때가 있습니다.
이럴 때는 설치 스크립트에 버전을 직접 지정하면 됩니다.
macOS, Linux, WSL 사용자
# 안정 버전 (기본)
curl -fsSL https://claude.ai/install.sh | bash
# 최신 개발 버전
curl -fsSL https://claude.ai/install.sh | bash -s latest
# 특정 버전 지정 (예: 1.0.58)
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
Windows PowerShell 사용자
# 안정 버전 (기본)
irm https://claude.ai/install.ps1 | iex
# 최신 개발 버전
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest
# 특정 버전 지정
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
Windows CMD 사용자
REM 안정 버전 (기본)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
REM 최신 개발 버전
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd latest && del install.cmd
REM 특정 버전 지정
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd
저는 Windows 환경에서 최신 개발 버전 명령어를 통해 최신버전을 유지하는 명령어를 자주 사용합니다.
NPM으로 설치한 경우 (deprecated)
NPM 설치는 현재 공식 GitHub에서 deprecated로 표시되어 있습니다.
예전에 NPM으로 설치하신 분들은 npm update 명령어로 업데이트할 수 있긴 합니다.
npm update -g @anthropic-ai/claude-code
근데 NPM 설치는 자동 업데이트가 안 되고, 업데이트 과정에서 ENOTEMPTY 에러 같은 문제가 자주 발생합니다. claude update 명령어도 안 먹습니다. 저도 이것 때문에 고생했습니다.
참고로 sudo npm install -g는 쓰지 않는 게 좋습니다. 권한 문제 생기고 보안상으로도 안 좋습니다.
네이티브 설치로 마이그레이션하기 (권장)
NPM으로 설치해서 쓰고 계신 분들은 네이티브 설치로 마이그레이션하는 걸 권장합니다. 공식 문서에서도 네이티브 설치를 권장하고 있습니다.
저도 NPM으로 쓰다가 업데이트 안 돼서 결국 PowerShell에서 설치 스크립트로 다시 설치했습니다. 그 이후로는 업데이트 문제가 없습니다.
네이티브 설치가 뭐가 좋냐면, 일단 Node.js 없어도 돌아가고, 실행 파일 하나로 깔끔하게 관리됩니다. 자동 업데이터도 제대로 작동합니다.
기존 NPM 설치에서 네이티브로 마이그레이션하는 방법은 간단합니다.
claude install
이 명령어 하나로 네이티브 설치로 전환됩니다.
업데이트 잘 됐는지 확인하기
claude doctor
업데이트하고 나서 제대로 됐는지 확인하고 싶으면 이 명령어 쳐보시면 됩니다.
현재 설치된 유형이랑 버전 정보가 나옵니다.
Windows에서 쓰는 분들 참고
Windows에서 Claude Code 쓰는 방법은 크게 두 가지입니다. 일단 npm이나 윈도우 자체에 설치해서 쓰는건 정말 비추드리고,
첫 번째는 WSL 안에서 쓰는 건데, WSL 1이든 2든 상관없이 잘 돌아갑니다. 리눅스 명령어 그대로 쓸 수 있어서 편합니다.
두 번째는 Git Bash 쓰는 건데, Git for Windows 설치하면 같이 깔립니다. 네이티브 Windows에서 쓰고 싶은 분들은 이쪽으로 가시면 됩니다.
포터블 Git 쓰시는 분들은 bash.exe 경로를 따로 지정해줘야 합니다.
$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"
업데이트 안 될 때 체크할 것들
업데이트가 안 되면 보통 세 가지 중 하나입니다.
첫째, 인터넷 연결 문제. Claude Code는 업데이트할 때 서버에 접속해야 해서 네트워크가 안 되면 당연히 안 됩니다.
둘째, 예전에 만들어둔 별칭이나 심볼릭 링크가 남아있는 경우. 이거 때문에 꼬이는 경우가 종종 있으니까 설치 전에 정리해주시면 됩니다.
셋째, 리눅스에서 권한 문제. 이건 공식 문서 troubleshooting 페이지에 해결 방법이 나와 있습니다.
마무리
Claude Code 업데이트는 대부분 자동으로 되니까 크게 신경 안 써도 됩니다. 근데 급하게 새 기능 써보고 싶거나 버전 문제로 뭔가 안 될 때는 위에 정리한 방법들 참고하시면 됩니다.
더 자세한 내용은 공식 문서에서 확인하실 수 있습니다.
Claude Code 설정 - Claude Code Docs
개발 머신에 Claude Code를 설치, 인증 및 시작하세요.
code.claude.com