설치 및 설정

기준일: 2026-06-06
난이도: 초급
공식 기준: Claude Code Advanced setup

Claude Code 설치 흐름은 예전 npm 전역 설치 중심에서 Native Install 중심으로 바뀌었습니다. 이 장에서는 현재 공식 문서 기준으로 설치 경로를 고르고, 설치 후 claude 명령이 동작하는지 확인합니다.

핵심 개념

Claude Code는 터미널에서 claude 명령으로 실행합니다. 설치 방식은 운영체제와 업데이트 정책에 따라 달라집니다.

시스템 요구사항

Windows native에서는 Git for Windows가 권장됩니다. Git Bash가 없으면 Claude Code는 PowerShell 도구를 사용할 수 있습니다. WSL 환경은 Git for Windows가 필요하지 않습니다.

선택 기준

실습

macOS, Linux, WSL:

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

Windows PowerShell:

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

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
claude

Homebrew:

brew install --cask claude-code
claude

WinGet:

winget install Anthropic.ClaudeCode
claude

설치 확인:

claude --version
claude --help
which claude

Windows CMD에서는 where claude를 사용합니다.

Claude Code에 입력할 프롬프트

내 Claude Code 설치 상태를 점검해줘.
운영체제, 설치 방식, claude 명령 위치, 업데이트 방식,
Git Bash 또는 PowerShell 도구 사용 여부를 확인하는 순서를 알려줘.
문제가 있으면 재설치보다 작은 확인 명령부터 제안해줘.

체크리스트

• 공식 Native Install, Homebrew, WinGet 중 하나를 선택했다.
• claude --version이 실행된다.
• 프로젝트 루트에서 claude를 실행했다.
• Windows native라면 Git for Windows 또는 PowerShell 도구 경로를 확인했다.
• Homebrew/WinGet 설치는 자동 업데이트가 아님을 기록했다.
• 오래된 claude-code 명령이 아니라 claude 명령 기준으로 문서를 검증했다.

문제 해결

claude 명령을 찾을 수 없음

echo "$PATH"
which claude

설치가 끝난 직후라면 새 터미널을 열거나 shell profile을 다시 로드합니다.

PowerShell과 CMD 명령을 혼동함

PowerShell 프롬프트는 보통 PS C:\...로 시작합니다. CMD에서는 irm ... | iex가 동작하지 않고, PowerShell에서는 && 사용 방식이 다를 수 있습니다. 현재 셸에 맞는 설치 명령을 사용하세요.

Alpine Linux에서 검색 도구 문제가 있음

Alpine 또는 musl 기반 배포판에서는 libgcc, libstdc++, ripgrep을 패키지 매니저로 설치하고, 필요하면 USE_BUILTIN_RIPGREP=0 설정을 검토합니다.

이전 npm 설치와 충돌이 의심됨

예전 npm 전역 설치 흔적이 있다면 공식 트러블슈팅 문서를 기준으로 native installer 경로와 npm global 경로를 분리해서 확인합니다. 바로 삭제하기 전에 which claude, npm global list, ~/.claude 경로를 먼저 기록하세요.

다음 단계

• 인증 설정에서 로그인과 API 키 사용 방식을 확인합니다.
• 빠른 시작에서 첫 프로젝트 작업을 실행합니다.
• 핵심 개념에서 Claude Code의 작업 모델을 이해합니다.