클로드 코드 설치 전 알아둘 다섯 가지

2026년 9월 21일Importants Studio

클로드 코드를 처음 설치하는 분, 특히 터미널에서 바로 프로젝트 작업을 시작하려는 분에게 필요한 글입니다. 설치 명령 자체는 짧지만 운영체제와 계정 상태, 셸 환경에 따라 설치 뒤의 경험이 달라집니다.

공식 문서의 설치 명령은 빠르지만, 실제 개발 환경에서는 설치가 끝난 시점과 매일 쓰기 시작할 수 있는 시점 사이에 확인할 항목이 생기므로 명령만 복사하고 끝내면 나중에 원인을 찾기 어려운 문제가 남습니다. 순서가 중요합니다.

먼저 결론부터

macOS·Linux·WSL에서는 아래 네이티브 설치 명령을 쓰면 자동 업데이트를 받습니다.

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

Windows PowerShell에서는 아래 네이티브 설치 명령을 쓰면 자동 업데이트를 받습니다.

irm https://claude.ai/install.ps1 | iex

Claude.ai 무료 플랜은 Claude Code 접근 권한을 포함하지 않습니다.
버전 하나는 약 204~208MB이고, 자동 업데이트가 누적되면 이 맥에서는 네 버전이 823MB를 차지했습니다.
PATH에 다른 래퍼가 먼저 잡힐 수 있으므로 자동화에는 전체 실행 경로를 적는 편이 안전합니다.
설치 뒤에는 아래 명령으로 버전과 실제 경로, 자동 업데이트 상태를 확인합니다.

claude --version
claude doctor

네이티브 설치부터 권합니다

네이티브 설치는 Node.js 없이 동작하며 자동 업데이트도 처리합니다. macOS 13.0 이상, Windows 10 1809 이상, Ubuntu 20.04 이상, Debian 10 이상, Alpine 3.19 이상에서 쓸 수 있고 RAM은 4GB 이상, CPU는 x64 또는 ARM64가 필요합니다.

회사 네트워크라면 먼저 연결을 확인합니다. 설치 과정에서는 downloads.claude.ai와 platform.claude.com에 접속할 수 있어야 하며, 방화벽이 이 주소를 막으면 설치가 실패합니다.

설치 방법	자동 업데이트
공식 네이티브 설치 스크립트	지원
Homebrew cask	미지원
winget	미지원
npm 전역 설치	미지원

다른 설치 경로도 있습니다.

brew install --cask claude-code
winget install Anthropic.ClaudeCode
npm install -g @anthropic-ai/claude-code

npm 설치만 Node.js 22 이상이 필요합니다. 업데이트를 따로 관리할 이유가 없다면 네이티브 설치가 편합니다.

로그인과 요금제

처음 실행하면 브라우저가 열립니다. 로그인만 마치면 터미널로 돌아와 사용할 수 있습니다.

claude

무료 Claude.ai 플랜에서는 사용할 수 없습니다. Pro 이상 구독자, Console 계정에서 API 사용량을 청구하는 사용자, Bedrock·Vertex AI·Foundry 클라우드 계정을 가진 사용자가 접근할 수 있습니다.

디스크에 쌓이는 버전들

자동 업데이트는 편하지만 이전 버전을 즉시 지우지 않습니다. 이 맥에서 직접 용량을 재보니 2.1.274, 2.1.275, 2.1.276, 2.1.278 네 버전이 남아 있었고, 각각 약 204~208MB로 합계 823MB를 차지했습니다.

설치 날짜도 9월 17일, 18일, 18일, 19일로 사흘 동안 네 번이었습니다. 저장 공간이 빠듯하다면 한 번씩 확인할 만합니다.

실행 파일 링크는 ~/.local/bin/claude에 있고, 실제 버전별 바이너리는 ~/.local/share/claude/versions/ 아래에 있습니다. 안 쓰는 버전 디렉터리는 지워도 되지만, 현재 쓰는 버전은 먼저 아래 명령의 Path 줄에서 확인해야 합니다.

claude doctor

PATH가 가리키는 위치

설치 뒤 claude를 찾지 못하는 경우가 가장 흔합니다. zsh에서는 아래 내용을 넣고 새 터미널을 열며, bash를 쓴다면 ~/.zshrc 대신 ~/.bashrc에 넣습니다.

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

반대 상황도 있습니다. 이 맥에서는 아래 명령 결과가 두 줄이었고 터미널 앱이 설치한 래퍼가 실제 바이너리보다 앞에 있었는데, 평소에는 문제없어도 launchd나 cron처럼 PATH가 다르게 구성되는 자동 실행에서는 앞선 래퍼가 잡히거나 PATH 자체가 전달되지 않아 배치 작업이 한 번 멈췄습니다.

which -a claude

자동화 작업에는 ~/.local/bin/claude처럼 실행 경로 전체를 적는 편이 안전합니다.

확인과 업데이트, 제거

아래 명령은 설치 방식, 플랫폼, 실제 경로, 자동 업데이트 여부와 마지막 업데이트 결과를 보여줍니다.

claude --version
claude doctor

업데이트는 자동으로 진행되며, 바로 올리고 싶을 때는 아래 명령을 씁니다.

claude update

업데이트를 막으려면 설정에서 DISABLE_AUTOUPDATER 값을 1로 둡니다. latest 채널은 바로 받고 stable 채널은 약 일주일 늦게 받는 대신 큰 문제 버전을 건너뛸 수 있으며, 채널 변경은 아래에서 합니다.

/config

제거할 때는 실행 파일과 버전 저장소를 함께 지웁니다.

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

설정까지 지우려면 ~/.claude와 ~/.claude.json도 제거합니다. 세션 기록과 MCP 설정도 함께 사라집니다.

마무리

설치가 끝났다면 작은 저장소에서 먼저 실행해 보고, 사용할 인증 방식과 업데이트 채널을 정한 뒤 자동화에 넣는 순서가 좋습니다. 특히 정기 작업을 돌릴 계획이라면 실행 경로를 명시해 두는 편이 낫습니다.

버전이 디스크에 누적되는 모습과 PATH 앞쪽에 다른 래퍼가 잡히는 현상은 이 글에서 직접 확인한 두 가지입니다. 공식 문서는 모든 사용자의 업데이트 이력이나 터미널 앱, launchd·cron 환경까지 대신 관찰할 수 없으므로 이런 차이는 각자의 개발 환경에서 한 번 확인해야 합니다.

지난 글: MCP 서버 설치 후 상태 확인법
다음 글: git add -A가 PR 세 개에 옆 글을 섞어 넣은 일
목록으로