6.0 KiB
설치
macOS, Linux, Windows(WSL 경유)에 Claude Code를 설치합니다. Node.js 18 이상이 필요합니다.
요구사항
- Node.js 18 이상 — Claude Code는 시작 시 Node.js 버전을 확인하고, 18 미만이면 오류와 함께 종료합니다.
- npm — Node.js에 포함되어 있습니다.
현재 버전 확인:
node --version
npm --version
Claude Code 설치
npm으로 전역 설치:
npm install -g @anthropic-ai/claude-code
설치 후 동작 확인:
claude --version
플랫폼별 안내
macOS
macOS에서는 npm 전역 설치가 기본적으로 작동합니다. npm install -g 실행 시 권한 오류가 발생하면 두 가지 옵션이 있습니다:
옵션 A: npm 권한 수정 (권장)
홈 폴더의 디렉토리를 사용하도록 npm을 설정:
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
셸 프로파일(~/.zshrc 또는 ~/.bash_profile)에 다음 추가:
export PATH=~/.npm-global/bin:$PATH
프로파일 다시 로드 후 설치:
source ~/.zshrc
npm install -g @anthropic-ai/claude-code
옵션 B: Node 버전 관리자 사용
nvm 또는 fnm 같은 도구는 홈 디렉토리에 Node.js를 설치해서 전역 권한 문제를 완전히 피할 수 있습니다:
# nvm 사용
nvm install --lts
nvm use --lts
npm install -g @anthropic-ai/claude-code
Linux
대부분의 Linux 배포판에서 npm install -g는 sudo 또는 npm prefix 수정이 필요합니다. sudo 사용은 나중에 권한 문제를 일으킬 수 있으므로 권장하지 않습니다.
권장: Node 버전 관리자 사용
# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
# 셸 다시 로드 후 Node.js 설치
nvm install --lts
nvm use --lts
# Claude Code 설치
npm install -g @anthropic-ai/claude-code
대안: npm 전역 prefix 수정
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code
Windows (WSL)
Claude Code는 Windows Subsystem for Linux(WSL)를 통해 Windows에서 실행됩니다. 커맨드 프롬프트나 PowerShell에서 직접 실행하는 것은 지원되지 않습니다.
1단계: WSL 설치
관리자 권한으로 PowerShell 열고 실행:
wsl --install
메시지가 나타나면 재시작. 기본적으로 Ubuntu와 함께 WSL 2가 설치됩니다.
2단계: WSL 터미널 열기
시작 메뉴에서 Ubuntu를 실행하거나, PowerShell에서 wsl을 실행합니다.
3단계: WSL 안에 Node.js 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts
4단계: Claude Code 설치
npm install -g @anthropic-ai/claude-code
📝 항상 WSL 터미널 안에서
claude를 실행하세요 — Windows CMD나 PowerShell에서 실행하지 마세요. 프로젝트 파일은 WSL 파일시스템(~/projects/등) 안에 있어야 최상의 성능을 발휘합니다./mnt/c/...를 통한 Windows 파일 접근은 가능하지만 느립니다.
업데이트
최신 버전으로 업데이트:
npm update -g @anthropic-ai/claude-code
또는 Claude Code 내장 업데이트 커맨드 사용:
claude update
현재 버전 확인:
claude --version
제거
Claude Code 제거:
npm uninstall -g @anthropic-ai/claude-code
claude 바이너리가 제거됩니다. ~/.claude/의 설정 파일은 자동으로 제거되지 않습니다. 삭제하려면:
rm -rf ~/.claude
문제 해결
설치 후 claude 커맨드를 찾을 수 없음
npm 전역 bin 디렉토리가 PATH에 없는 경우입니다.
npm이 전역 바이너리를 설치하는 위치 확인:
npm config get prefix
해당 경로의 bin 서브디렉토리를 PATH에 추가해야 합니다. 예를 들어 출력이 /home/you/.npm-global이면:
export PATH=/home/you/.npm-global/bin:$PATH
셸을 다시 로드(source ~/.zshrc 또는 새 터미널 열기) 후 다시 시도하세요.
Node.js 버전이 18 미만
Claude Code는 Node.js 18 이상이 필요합니다. 시작 시 이 오류가 보이면:
Error: Claude Code requires Node.js version 18 or higher.
버전 관리자를 사용해 Node.js를 업그레이드하세요:
# nvm
nvm install --lts
nvm use --lts
# fnm
fnm install --lts
fnm use --lts
npm install -g 시 권한 거부
sudo npm install -g를 사용하지 마세요 — root 소유 파일이 남아 추가 문제를 일으킬 수 있습니다. 대신 npm prefix를 사용자 쓰기 가능 디렉토리로 수정하세요:
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
npm install -g @anthropic-ai/claude-code
첫 실행 시 인증 실패
브라우저 기반 OAuth 흐름이 실패하거나 브라우저를 사용할 수 없는 경우, 환경 변수로 API 키를 직접 설정하세요:
export ANTHROPIC_API_KEY=sk-ant-...
claude
셸 프로파일에 추가하면 영구적으로 설정됩니다. API 키는 Anthropic Console에서 발급받을 수 있습니다.
Docker 또는 CI 환경에서 실행
비대화형 환경에서는 환경 변수로 인증하세요:
export ANTHROPIC_API_KEY=sk-ant-...
비대화형으로 실행하려면 -p 플래그 사용:
claude -p "테스트 스위트를 실행하고 실패를 보고해줘"
샌드박스 컨테이너에서 권한 프롬프트 없이 Claude Code를 작동시켜야 한다면 --dangerously-skip-permissions 플래그를 사용하세요. 이 플래그는 Claude Code의 샌드박스 안전 검사를 통과한 환경(인터넷 접근 없음, 컨테이너 외부에서 root로 실행하지 않음)에서만 작동합니다.