Claude Code 설치 가이드: Windows, macOS, Linux (2026년 5월)

Claude Code는 단 1년 만에 월간 검색량 0에서 100만으로 급성장했어요. ‘다들 쓰는데 나도 한 번 써봐야지’ 하고 여기 오셨다면, 이 글이 딱 5분 만에 끝내는 설치 가이드가 되어 줄 거예요.

설치 전 체크할 사항이에요.

1. Claude Pro 구독 ($20/월) 또는 상위 플랜이 필요해요. 무료 티어에서는 Claude Code를 사용할 수 없어요.
2. 터미널에서 실행해요. 컴퓨터의 명령어 창을 기본적으로 사용하기 때문에, 터미널 사용에 익숙해져야 해요.
3. 네이티브 인스톨러가 2026년 초에 npm을 공식 방법으로 대체했어요. 몇 달 전 작성된 튜토리얼은 아직 npm 방식을 소개하고 있을 수 있어요. 작동은 하지만 공식 권장 방식은 아니에요.
4. 2026년 초부터 추가된 공식 설치 경로: Homebrew (brew install --cask claude-code), WinGet (winget install Anthropic.ClaudeCode), 서명된 Linux 패키지 저장소 (apt/dnf/apk)도 공식 옵션으로 지원해요. 평소 패키지 매니저를 선호하신다면 딱 맞는 방법이에요.

그럼 바로 시작해 볼까요?

시스템 요구사항

설치 전에 지원되는 운영체제인지 먼저 확인해 주세요.

Windows 11이라면 문제없어요. macOS Monterey (12) 이하 버전을 사용 중이라면 먼저 OS를 업그레이드해 주세요.

옵션 1: macOS 또는 Linux (30초 설치)

터미널을 열고 아래 명령어를 붙여넣은 뒤 엔터를 눌러 주세요.

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

이 명령어 하나로 설치가 끝나요. 네이티브 인스톨러가 바이너리를 자동으로 다운로드하고 ~/.local/bin 폴더에 배치한 뒤, 자동 업데이트 설정까지 처리해 줘요. Node.js가 따로 필요 없으며, 외부 의존성이나 복잡한 패키지 매니저 설정 과정도 필요 없어요.

설치 완료 후 작동을 확인해 보세요.

claude --version
claude doctor

claude doctor 명령어를 실행하면 인증 상태, PATH 설정, 환경 설정, MCP 서버 연동 상태 등을 한눈에 진단해 줘요. 설치가 끝난 뒤 바로 한번 실행해 두면 나중에 발생할 수 있는 문제를 미리 방지할 수 있어요.

이제 프로젝트 폴더로 이동해 주세요.

cd /경로/프로젝트
claude

이제 Claude Code를 프로젝트 안에서 사용할 준비가 끝났어요.

옵션 2: Windows + WSL (권장)

WSL(Windows Subsystem for Linux)은 Windows 환경에서 Linux를 직접 실행할 수 있게 해 주는 기능이에요. Claude Code는 Windows 네이티브 경로보다 WSL 환경에서 훨씬 안정적으로 작동해요. 설치 과정은 macOS/Linux 옵션과 완전히 동일해요.

1단계: PowerShell을 관리자 권한으로 실행한 뒤 아래 명령어를 입력하세요.

wsl --install

재부팅을 요청하면 컴퓨터를 다시 시작해 주세요. 부팅이 완료되면 시작 메뉴에서 Ubuntu 터미널을 열어 주세요.

2단계: WSL 터미널 창에서 Claude Code를 설치하세요.

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

3단계: 설치가 완료되었는지 확인하고 시작하세요.

claude --version
claude doctor
cd /mnt/c/Users/당신의_사용자명/경로/프로젝트
claude

참고로 /mnt/c/ 경로는 WSL이 Windows 디스크를 마운트하는 방식이에요. Windows의 C: 드라이브는 WSL에서 /mnt/c/로, D: 드라이브는 /mnt/d/로 접근하면 돼요.

옵션 3: Windows 네이티브 (PowerShell)

WSL 설정이 부담스럽다면 Windows 환경에 직접 설치할 수도 있어요. 다만 이 방법은 Claude Code가 내부적으로 Git Bash를 사용하기 때문에, 반드시 Git for Windows가 먼저 설치되어 있어야 해요.

1단계: Git for Windows를 설치해 주세요. 설치 중 기본 설정을 그대로 유지해도 문제없어요.

2단계: PowerShell을 일반 사용자 권한으로 열고 아래 명령어를 실행하세요.

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

3단계: 설치가 정상적으로 완료되었는지 확인하세요.

claude --version
claude doctor

만약 claude doctor 실행 시 Git Bash 경로를 찾지 못한다는 오류가 발생한다면, ~/.claude/settings.json 파일에 아래 설정을 추가해 주세요.

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

옵션 4: 레거시 NPM 방식 (아직 작동)

이미 Node.js 18 이상이 설치되어 있고 npm을 선호하신다면 아래 명령어로 설치할 수 있어요.

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

공식적으로는 비권장 방식이지만, 기존 사용자를 위한 하위 호환성 유지 차원에서 아직 작동하고 있어요. 다만 다음과 같은 이유로 네이티브 인스톨러 사용을 권장하는 이유 3가지가 있어요.

1. 자동 업데이트가 지원되지 않아요. 새 버전이 출시되면 수동으로 npm update 명령어를 입력해야 해요.
2. Node.js 18 이상 환경이 필수예요. 네이티브 인스톨러는 별도의 런타임 의존성이 필요 없어요.
3. 설치 파손 빈도가 높아요. npm 전역 설치는 권한 관련 오류가 자주 발생하기 때문이에요.

만약 이미 npm으로 설치하셨다면, 네이티브 인스톨러로 전환하는 것을 추천해요.

# 네이티브 바이너리 설치
curl -fsSL https://claude.ai/install.sh | bash

# 기존 npm 버전 제거
npm uninstall -g @anthropic-ai/claude-code

옵션 5: Homebrew (macOS)

평소 Homebrew로 개발 도구를 관리해 오셨다면, Anthropic에서 공식 cask를 출시했어요.

brew install --cask claude-code

Homebrew cask는 크게 두 가지 버전으로 제공돼요.

• claude-code — stable 채널입니다. 최신 버전보다 약 1주일 정도 늦게 출시되며, 주요 결함이 발견된 릴리즈는 건너뛰고 안정성을 우선해요. 가장 안전한 선택이에요.
• claude-code@latest — latest 채널입니다. 새 버전이 출시되자마자 바로 반영돼요.

주의할 점은 Homebrew를 통한 설치는 자동 업데이트가 지원되지 않는다는 점이에요. 최신 기능과 보안 패치를 받으려면 brew upgrade claude-code (또는 claude-code@latest) 명령어를 주기적으로 실행해 주세요.

옵션 6: WinGet (Windows 패키지 매니저)

Microsoft의 공식 패키지 매니저인 WinGet에서도 Claude Code를 설치할 수 있어요.

winget install Anthropic.ClaudeCode

Homebrew와 마찬가지로 WinGet 설치 시 자동 업데이트는 지원되지 않아요. 새 버전이 출시되면 winget upgrade Anthropic.ClaudeCode 명령어를 수동으로 실행해 주세요.

옵션 7: Linux 패키지 저장소 (apt, dnf, apk)

Anthropic이 공식적으로 서명된 apt, dnf, apk 저장소를 운영하고 있어요. Debian/Ubuntu, Fedora/RHEL, Alpine 환경에서는 시스템 패키지 관리 워크플로우와 자연스럽게 연동되기 때문에 가장 깔끔한 설치 경로예요.

Debian / Ubuntu (apt):

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

GPG 키 지문(Fingerprint)을 반드시 확인해 주세요. gpg --show-keys /etc/apt/keyrings/claude-code.asc 명령어 실행 시 출력 결과에 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE 가 포함되어 있어야 해요.

Fedora / RHEL (dnf):

sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

Alpine (apk):

wget -O /etc/apk/keys/claude-code.rsa.pub \
  https://downloads.claude.ai/keys/claude-code.rsa.pub
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code

롤링 릴리즈 채널을 사용하고 싶다면, URL과 소트(suite) 이름에서 stable을 latest로 변경하면 돼요. 업데이트는 평소 사용하던 패키지 매니저 명령어(sudo apt upgrade claude-code, sudo dnf upgrade claude-code, apk upgrade claude-code)로 진행하면 돼요.

인증 (로그인 방법)

처음 claude 명령어를 실행하면 기본 브라우저가 열리며 OAuth 인증 페이지로 이동해요. Anthropic 계정 중 하나에 로그인하면 돼요.

• Claude Pro/Max 개인 구독 — claude.ai 로그인
• Claude Team 또는 Enterprise — 조직 워크스페이스 로그인
• Claude Console — 조직에서 초대한 경우

브라우저가 자동으로 열리지 않는다면, 터미널에서 c 키를 눌러 로그인 URL을 복사한 뒤 브라우저에 붙여넣고 로그인하세요. 인증이 완료되면 터미널에 요청되는 코드를 다시 붙여넣으면 돼요.

나중에 다른 계정으로 전환하고 싶을 때는 아래 명령어를 사용하세요.

/logout

(참고: 이 명령어는 일반 쉘이 아닌, Claude Code 인터랙티브 세션 안에서 실행해야 해요.)

첫 번째로 해볼 명령어

claude 명령어로 인터랙티브 세션에 진입했다면 아래 명령어를 한번 시도해 보세요.

/help          # 모든 사용 가능 명령어 표시
/status        # 인증, 구독, 요청 제한 확인
/config        # 현재 설정 보기
/logout        # 로그아웃

만약 인터랙티브 세션 밖에서 일반 쉘(터미널)에서 바로 실행하고 싶다면 아래 명령어를 사용하세요.

claude doctor    # 진단 리포트
claude --version # 설치된 버전 표시
claude mcp list  # 구성된 MCP 서버 목록

실제 프로젝트에 적용해 보기

이제 이미 진행 중인 프로젝트를 Claude Code에 열어 보세요. Next.js 웹 앱이든, Python 스크립트든, 설정 파일 레포지토리든 상관없어요. 아래 명령어로 시작하세요.

cd /경로/프로젝트
claude

그다음은 터미널에 한국어로 직접 작업을 지시해 보세요. 다음과 같이 입력하면 돼요.

“README 파일을 읽고, 이 프로젝트가 어떻게 구성되어 있는지 설명해 줘.”

또는

“이메일 주소 형식을 검증하는 새 함수를 추가해 줘. 기존 코드베이스 구조를 고려해서 가장 적합한 위치에 넣어.”

또는

“프로젝트 내 모든 TODO 주석을 찾아서, 파일 경로와 함께 목록으로 정리해 줘.”

Claude는 지시한 파일을 분석하고, 해결책을 생각한 뒤 변경 사항을 제안해요. 각 파일을 수정하기 전 반드시 사용자의 승인을 요청하므로, 코드 변경의 최종 결정권은 항상 당신에게 있어요.

자주 발생하는 설치 문제 및 해결법

“command not found: claude” 오류

인스톨러가 바이너리를 ~/.local/bin에 설치했지만, 현재 쉘이 해당 경로를 PATH에 포함하지 않아找不到요. 아래 명령어로 PATH를 추가해 주세요.

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

macOS Catalina 이후 기본 쉘이 zsh인 경우, .bashrc가 아닌 .zshrc 파일을 수정해 주세요.

“The token ‘&&’ is not a valid statement separator” 오류

PowerShell 환경에서 CMD 스타일의 명령어를 그대로 붙여넣었을 때 발생하는 오류예요. CMD 명령어 창으로 전환하거나, PowerShell에 맞는 명령어 버전을 사용하세요.

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

npm 설치 중 “Permission denied” 오류

sudo npm install -g 명령어를 사용해 권한 관련 오류가 발생했어요. npm 전역 설치 시 sudo 사용은 권장되지 않아요. 대신 다음 방법 중 하나를 선택해 주세요.

• 네이티브 인스톨러 사용 (sudo 불필요): curl -fsSL https://claude.ai/install.sh | bash
• **nvm(Node Version Manager)**을 사용해 Node.js를 홈 디렉토리에 설치한 후 npm을 사용

WSL 환경에서 인터넷 연결 불가

curl https://claude.ai 명령어로 인터넷 연결 상태를 테스트해 보세요. 연결이 실패한다면 Windows 방화벽이나 VPN 설정이 WSL 네트워크를 차단하고 있을 수 있어요. 대부분의 VPN 프로그램에는 ‘로컬 네트워크 트래픽 제외(Allow LAN traffic / Split tunneling)’ 옵션이 있으니, 이를 활성화해 주세요.

Node.js 버전이 너무 낮음 (npm 설치 전용)

npm을 통한 Claude Code 설치는 Node.js 18 이상 환경이 필요해요. node -v 명령어로 현재 버전을 확인해 주세요. v16 이하라면 nvm를 통해 업그레이드하세요.

nvm install 20
nvm use 20

만약 Node.js 환경 구축이 번거롭다면 아예 npm 설치를 건너뛰고 네이티브 인스톨러를 사용하는 것을 강력히 추천해요.

설치 직후 API 요청 제한 오류

Pro 플랜을 구독했는데 1시간도 안 되어 사용 한도에 도달했나요? 2026년 3월 31일 Anthropic 측에서 공식 인정한 이슈예요. 먼저 현재 Claude Code 버전을 확인해 보세요.

claude --version

2026년 5월 4일 기준 최신 빌드는 v2.1.126(5월 1일 릴리즈)이에요. 이 버전에는 claude project purge [path] 명령어가 추가되었고, Opus 4.7 모델의 /context 사용량 퍼센트 표시 버그도 수정되었어요. 다만 v2.1.100에서 도입된 토큰 인플레이션(불필요한 토큰 과다 생성) 문제는 아직 공식 패치가 적용되지 않았어요. 커뮤니티에서 공유하는 임시 해결책은 v2.1.34로 다운그레이드하거나, 네이티브 바이너리 대신 npm 패키지로 재설치하는 거예요.

특정 버전으로 설치를 고정하고 싶다면 네이티브 인스톨러를 사용하세요.

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

추후 자동 업데이트가 실수로 인해 문제가 있는 버전으로 올라가지 않도록 방지하려면, ~/.claude/settings.json 파일에 최소 버전 제한을 설정할 수도 있어요.

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.34"
}

MCP를 활용한 확장

설치가 잘 되었다면 이제 Claude Code의 진짜 잠재력을 확인할 때예요. MCP(Model Context Protocol)를 통해 다양한 외부 도구와 연결하면, Claude Code는 단순한 ‘코딩 어시스턴트’를 넘어 ‘당신의 데이터베이스, API, 팀 협업 도구에 직접 접근하는 지능형 개발 파트너’로 진화해요.

현재 공식적으로 지원되는 MCP 서버 목록이에요.

claude mcp list

직접 새로운 MCP 서버를 추가하고 싶다면(예: 데이터베이스 연결), 다음과 같이 설정하세요.

claude mcp add my-db --command "docker run --rm my-db-mcp:latest"

각 프로젝트 폴더에는 고유한 .claude/.mcp.json 설정 파일이 위치할 수 있어요. 이 파일에는 해당 프로젝트에서 사용할 MCP 서버 목록이 정의되어 있어요. 공유 레포지토리에 이 파일을 커밋해 두면, 팀원들은 설치를 진행할 때 자동으로 동일한 도구 설정을 상속받을 수 있어요.

먼저 시도해 보면 좋은 인기 MCP 서버예요.

• GitHub MCP — PR 생성, 브랜치 리뷰, 이슈 검색 자동화
• 데이터베이스 MCP — PostgreSQL, MySQL, MongoDB 등에 직접 쿼리 실행
• Jira/Linear MCP — 이슈 트래커의 컨텍스트를 Claude에게 전달
• Slack/Notion MCP — 팀 협업 도구와 연동하여 정보 공유

OS별 빠른 참고

한국 개발자를 위한 체크리스트

국내 기업 환경에서 업무용으로 Claude Code를 활용할 때 꼭 체크해야 할 사항이에요.

1. 한국어 프롬프트 인식력 / Claude Code는 한국어 자연어 지시에 매우 정확하게 반응해요. 한글 주석이나 한글 변수명이 포함된 코드베이스도 문제없이 이해하고 처리해요. OKKY, velog, 개발바닥 뉴스레터 등 국내 개발자 커뮤니티에서 실제 활용 사례를 쉽게 찾아볼 수 있어요.

2. 기업 보안 및合规 체크 / 업무 코드를 외부 AI 엔진에 전송하므로, 반드시 사내 정보보호팀의 승인을 받아야 해요. Anthropic의 DPA(데이터 처리 계약)는 Team과 Enterprise 플랜에서만 공식 지원되며, Pro와 Max 플랜은 개인용을 전제로 해요. 민감한 업무 소스 코드를 투입하기 전에 사내 가이드라인을 반드시 확인해 주세요.

3. .claudeignore 파일 활용 / .gitignore와 동일한 구문을 사용하여 Claude가 접근하지 말아야 할 파일을 제외할 수 있어요. .env 파일, API 키, 민감한 설정 값 등은 반드시 예외 목록에 포함하세요.

4. Code with Claude 도쿄 (2026년 6월 10일) / Anthropic이 샌프란시스코(5/6), 런던(5/19)에 이어 아시아 첫 개발자 컨퍼런스인 ‘Code with Claude 도쿄’를 개최해요. 한국 개발자를 위한 원격 참여 옵션이 제공될 가능성이 높으며, 신기능 및 신규 플랜 발표가 예상되니 관심 있게 지켜봐 주세요.

이 가이드가 당신에게 주는 의미

터미널 사용이 처음이라면: macOS 기본 터미널이나 Windows WSL 환경을 추천해요. 터미널은 Claude Code를 활용하는 데 필수적인 도구예요. 터미널 명령어 사용에 익숙해져야 실제 개발 워크플로우에 자연스럽게 녹여낼 수 있어요. cd, ls, pwd, git 같은 기본 명령어 습득에만 30분 정도 투자해 주세요.

Claude Code 도입을 고려 중인 개발자라면: 5분 만에 설치를 완료하고, 사이드 프로젝트에 적용해 실제 작업을 맡겨 보세요. Cursor는 IDE 통합형, GitHub Copilot은 자동완성 중심이라면, Claude Code는 정말 다른 차원의 경험을 제공해요. 직접 써봐야 그 차이를 실감할 수 있어요.

팀 공용 환경으로 설정하고 싶다면: 공유 레포지토리에 .claude/ 폴더를 생성하고 팀 전체가 사용할 MCP 설정을 포함해 커밋하세요. 새로 합류한 팀원은 인스톨러 실행과 인증 과정만 거치면 자동으로 팀의 도구 설정을 상속받을 수 있어요.

이미 Claude Code를 사용하고 있다면: 플러그인과 MCP 생태계는 단순한 ‘사용자’를 ‘파워 유저’로 성장시켜 줍니다. FindSkill의 Claude Code Mastery 코스는 Skills, Hooks, MCP 활용법을 심도 있게 다루니 참고해 주세요.

결론

Claude Code 설치는 사용하는 OS에 따라 단 30초에서 5분이면 충분해요. 2026년 4월 기준 기본으로 권장되는 네이티브 인스톨러는 안정적이고 속도가 빠르며, 별도의 외부 의존성도 필요 없어요.

하지만 진정한 학습 곡선은 설치가 아니라, 설치한 후 Claude Code를 어떻게 생산적으로 활용할지를 익히는 과정에서 시작돼요. 작은 작업부터 시작해 점차 큰 워크플로우로 확장하고, 필요할 때만 MCP 도구를 추가하세요. 하루아침에 모든 설정을 끝내려 하기보다는, 천천히 익숙해지는 과정을 추천해요.

마지막으로 구독 예산은 미리 잡아두세요. 무료 티어로는 Claude Code를 지속적으로 사용하기 어려워요. Pro 플랜($20/월)이 본격적인 활용의 시작점이에요.

다음 단계: FindSkill의 Claude Code Mastery 코스는 첫 설치 과정부터 시작해 Skills, Hooks, MCP를 활용한 고급 에이전트 패턴까지 전체 개발 워크플로우를 체계적으로 커버해요. 이미 설치를 마쳤다면 Claude Code 요금 가이드를 참고하여 본인에게 맞는 구독 티어를 선택해 보세요.

출처:

• Claude Code 설치 가이드 — NxCode
• Claude Code 초보자 튜토리얼 2026 — NxCode
• 2026 클로드 코드 사용법 — 하이아웃풋클럽
• 고급 설정 — Claude Code Docs (한국어)
• Claude Code 설치 방법 완전 가이드 — LaoZhang AI
• 클로드 코드 가이드 — WikiDocs
• Claude Code 설치/사용법 — rview
• Claude Code GitHub Repository