Claude Code, Homebrew 대신 네이티브 설치로 바꿨더니 확 달라졌다

2026-04-03

11분 만에 읽기

업데이트: 2026-04-03

hf_20260318_230525_e32fa965-d95a-47b0-80af-adff5282418d.webp

이 "어?" 하는 의문을 계기로, Claude Code의 설치 방법을 Homebrew에서 네이티브 설치로 전환했습니다. 결론부터 말하자면, 전환하길 잘했습니다. 이 글에서는 왜 버전이 어긋나는지, 어떻게 전환하는지, 설정이나 데이터는 사라지지 않는지 등의 궁금증을 한꺼번에 해소해 드리겠습니다.

왜 Homebrew에서는 버전이 어긋나는가

조사해 보니, 몇 가지 요인이 겹쳐 있는 것 같습니다.

우선, Claude Code의 Homebrew cask는 stable 릴리스 채널을 따르도록 설계되어 있다고 합니다. stable 채널은 latest보다 약 1주일 늦게 제공되기 때문에, Anthropic이 새 버전을 릴리스해도 Homebrew 측의 cask 정의에 반영되기까지 시간 차가 있는 것 같습니다. 게다가 Homebrew 4.0 이후부터는 cask 정의를 CDN 경유의 JSON API에서 가져오는 방식으로 바뀌었으며, CDN 엣지 노드나 로컬 캐시의 신선도 차이도 영향을 미친다고 합니다. 그래서 2대의 Mac에서 거의 동시에 brew upgrade를 실행해도, 가져오는 cask 정의가 다를 수 있다는 것입니다.

또한, 공식 문서에는 이렇게 적혀 있습니다.

Homebrew installations do not auto-update. Run brew upgrade claude-code periodically to get the latest features and security fixes. Known issue: Claude Code may notify you of updates before the new version is available in these package managers. If an upgrade fails, wait and try again later.

즉, Homebrew 버전은 자동 업데이트되지 않으며, 수동으로 brew upgrade를 실행해야 합니다. 게다가 Claude Code 본체가 "새 버전이 있습니다"라고 알림을 보내도, Homebrew 측에는 아직 반영되지 않은 경우도 있습니다. 여러 대의 Mac을 사용하다 보면, 이 어긋남이 은근히 스트레스가 됩니다.

네이티브 설치가 권장된다

공식 문서에서는 설치 방법으로 Native Install에 "Recommended" 라벨이 붙어 있습니다. Homebrew나 WinGet보다 네이티브 설치가 권장되는 이유는 자동 업데이트가 작동하기 때문입니다.

네이티브 설치 버전은 시작 시와 실행 중에 주기적으로 백그라운드에서 업데이트를 확인하고, 다운로드 및 설치까지 자동으로 수행합니다. 다음 번 시작 시에는 새 버전이 반영되어 있습니다.

여러 대의 Mac에서 작업하더라도, 각각이 알아서 최신 버전을 따라가기 때문에 "저쪽은 새 버전인데 이쪽은 구 버전"이라는 상황이 발생하기 어렵습니다.

전환 절차

전환은 매우 간단합니다. Homebrew 버전을 제거하고, 네이티브 설치를 실행하기만 하면 됩니다.

1. Homebrew 버전 삭제

brew uninstall --cask claude-code

2. npm 글로벌 버전이 설치되어 있다면 삭제

과거에 npm을 통해 설치한 적이 있다면, 이쪽도 삭제해 둡니다.

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

3. 네이티브 설치 실행

curl -fsSL https://claude.ai/install.sh | bash

4. 확인

claude --version

버전이 표시되면 성공입니다. which -a claude도 실행해서, 불필요한 다른 경로의 claude가 남아 있지 않은지 확인해 두면 안심할 수 있습니다.

which -a claude

출력이 ~/.local/bin/claude만 나오면, 전환이 완료된 것입니다.

command not found가 발생하는 경우

claude --version에서 command not found가 나오는 경우, ~/.local/bin이 PATH에 포함되어 있지 않을 가능성이 있습니다. 다음 명령어로 확인할 수 있습니다.

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

아무것도 출력되지 않으면, .zshrc에 PATH를 추가합니다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

다시 한번 claude --version을 실행해서 버전이 표시되면 OK입니다.

설정이나 데이터는 사라지지 않나요?

이 부분이 가장 걱정되는 점이라고 생각합니다. 결론부터 말하자면, 일반적으로는 사라지지 않습니다.

Claude Code의 설정과 상태는 실행 파일과는 별도의 위치에 저장됩니다.

~/.claude/settings.json — 사용자 설정
~/.claude.json — OAuth, 테마, MCP 서버 등의 글로벌 상태
프로젝트별 .claude/나 .mcp.json — 프로젝트 고유 설정

brew uninstall --cask claude-code와 네이티브 설치에서는 이러한 파일에 손대지 않습니다. 로그인 상태나 허가 설정, MCP 서버 구성도 그대로 남습니다.

공식 문서에서도, 설정을 초기화하고 싶은 경우에는 ~/.claude나 ~/.claude.json을 명시적으로 삭제하도록 안내하고 있습니다. 반대로 말하면, 삭제하지 않으면 사라지지 않는다는 뜻입니다.

혹시 모르니 백업하고 싶은 경우

걱정되시는 분은 전환 전에 백업을 해 두면 안심할 수 있습니다.

# 글로벌 설정 백업
mkdir -p ~/claude-backup-$(date +%Y%m%d)
cp -R ~/.claude ~/.claude.json ~/claude-backup-$(date +%Y%m%d) 2>/dev/null

# 프로젝트별 설정 백업 (프로젝트 디렉터리에서 실행)
cp -R .claude .mcp.json ~/claude-backup-$(date +%Y%m%d)/ 2>/dev/null

네이티브 버전의 업데이트 방법

네이티브 설치 버전은 기본적으로 자동 업데이트됩니다. 시작 시와 실행 중에 주기적으로 업데이트를 확인하고, 백그라운드에서 다운로드 및 설치가 이루어집니다. 다음 번 시작 시에 반영되므로, 평소에는 아무것도 할 필요가 없습니다.

지금 당장 수동으로 업데이트하고 싶을 때

claude update

릴리스 채널 전환

릴리스 채널을 설정하면 업데이트를 받는 방식을 변경할 수 있습니다.

"latest"（기본값）— 새 기능을 릴리스 직후에 받는다
"stable" — 보통 약 1주일 늦은 안정 버전을 받는다

설정하려면 Claude Code 내에서 /config에서 Auto-update channel을 선택하거나, settings.json에 직접 작성합니다.

{
  "autoUpdatesChannel": "stable"
}

안정성을 중시한다면 "stable"을 권장합니다.

자동 업데이트를 끄고 싶은 경우

settings.json의 env에 이렇게 작성합니다.

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

업데이트 후 확인

claude --version
claude doctor

claude doctor는 설정이나 상태를 자세히 확인하는 데 사용할 수 있는 명령어입니다. 뭔가 동작이 이상할 때도 도움이 됩니다.

정리

Homebrew 버전의 Claude Code는 간편하게 설치할 수 있지만, 자동 업데이트가 작동하지 않기 때문에 여러 대에서 사용하다 보면 수동 업데이트 타이밍에 따라 버전이 어긋날 수 있습니다.

네이티브 설치로 전환하면 백그라운드에서 자동 업데이트되기 때문에, 이 문제가 훨씬 발생하기 어려워집니다（업데이트는 다음 번 시작 시에 반영되므로, 재시작 타이밍의 차이로 일시적으로 어긋날 수는 있습니다）.

전환이 간단하다 — brew uninstall → curl로 재설치 → 확인, 의 3단계
설정이나 데이터가 사라지지 않는다 — 설정 파일은 실행 파일과는 별도의 위치에 저장된다
자동 업데이트가 작동한다 — 백그라운드에서 업데이트되므로, 항상 최신 버전을 사용할 수 있다
릴리스 채널로 업데이트 빈도 조정 가능 — 안정성 중시라면 "stable"을 선택할 수 있다

공식에서도 네이티브 설치를 권장하고 있으므로, 아직 Homebrew로 사용하고 계신 분은 이 기회에 전환해 보시는 건 어떨까요?

참고 링크

이 기사 공유하기

목차