설치와 초기 설정 — Mac·Windows 한 번에

Claude Code 설치는 Mac은 터미널, Windows는 PowerShell에서 명령어 한 줄을 실행하는 것으로 끝납니다. 네이티브 설치 프로그램에 필요한 의존 패키지가 모두 동봉돼 있어 Node.js를 미리 설치할 필요가 없고, 예전처럼 Windows에서 WSL을 먼저 깔아야 하는 것도 아닙니다. 커맨드라인이 낯선 분도 이 글의 명령을 그대로 붙여 넣으면 첫 세션까지 갈 수 있습니다.

핵심 요약

• Mac은 curl -fsSL https://claude.ai/install.sh | bash, Windows는 irm https://claude.ai/install.ps1 | iex 한 줄이면 됩니다.
• 네이티브 설치는 Node.js가 필요 없고, npm 경유는 네이티브가 안 될 때의 대체 수단(Node.js 22 이상)입니다.
• 설치 후에는 claude를 실행해 로그인하고, claude doctor로 환경을 점검합니다.
• 프로젝트 폴더에서 /init으로 CLAUDE.md 초안을 만들어 두면 이후 세션이 훨씬 편해집니다.

설치 전에 준비할 것

OS와 관계없이 아래 세 가지만 있으면 됩니다.

• 터미널 — macOS의 터미널, Windows의 PowerShell 또는 명령 프롬프트. 모두 기본으로 설치돼 있습니다.
• Claude 계정 — Pro·Max·Team·Enterprise 중 하나의 플랜, 또는 Claude Console(API 크레딧) 계정. 무료 Claude.ai 플랜은 대상이 아닙니다.
• 작업 폴더 — 코드 프로젝트, 또는 연습용 빈 폴더. Git 저장소이면 변경 이력 추적과 되돌리기가 쉬워지므로 권장합니다.

Claude.ai는 구독 플랜, Claude Console은 API 접근용 선불 크레딧 방식입니다. 일반적인 개발 용도라면 Claude.ai 구독을 권합니다. 두 방식의 차이는 요금제 비교, 로그인 절차는 로그인과 인증 설정에서 다룹니다.

설치 방법 한눈에 비교

기본적으로 Mac은 네이티브, Windows는 PowerShell을 고르면 문제없습니다. 나머지는 "안 될 때의 대체"로만 기억해 두면 충분합니다. Linux 서버에서는 Mac과 같은 install.sh 명령을 그대로 씁니다.

Mac에 설치하기

네이티브 설치 (추천)

터미널을 열고 아래 명령을 실행하면 설치 스크립트가 다운로드되고 자동으로 셋업이 진행됩니다.

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

설치 위치는 ~/.local/bin(바이너리 본체는 ~/.local/share/claude/versions/ 아래)입니다. 기존 npm 패키지는 Node.js가 전제 조건이었지만 네이티브 설치 덕분에 환경 구축의 문턱이 크게 낮아졌습니다.

npm 경유 설치 (대체)

네이티브 설치가 잘 안 되면 npm으로도 설치할 수 있습니다. 다만 Node.js 22 이상이 필요합니다.

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

sudo npm install -g는 피하세요. sudo를 붙여 npm 글로벌 설치를 하면 권한 문제나 보안 리스크의 원인이 됩니다. 권한 오류가 나면 sudo 대신 npm의 전역 경로를 홈 디렉터리로 바꾸는 쪽을 권합니다.

Windows에 설치하기

PowerShell로 설치하기 (추천)

PowerShell을 열고 아래 명령을 실행하면 끝입니다.

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

irm은 Invoke-RestMethod, iex는 Invoke-Expression의 축약형입니다. 명령을 복사해 붙여 넣기만 하면 돌아가니 PowerShell이 낯선 분도 문제없습니다.

설치 중 권한 오류가 나면 시작 메뉴에서 "PowerShell"을 검색하고 우클릭해 '관리자 권한으로 실행'을 고른 뒤 다시 시도합니다. 다만 가능하면 관리자 권한 없이 설치하는 편이 좋습니다. 관리자 권한이 필요 없는 경우 사용자 디렉터리에 설치되기 때문에 시스템 전체에 영향을 주지 않습니다.

명령 프롬프트로 설치하기

PowerShell을 쓸 수 없으면 명령 프롬프트에서도 설치할 수 있습니다. 아래 한 줄이 스크립트 다운로드·실행·삭제를 한 번에 처리합니다.

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

PowerShell 쪽이 더 현대적이고 Windows 10 이후에서는 표준적으로 쓰이니, 특별한 이유가 없으면 PowerShell을 권합니다.

WSL 경유 설치

예전에는 Windows에서 Claude Code를 쓰려면 WSL(Windows Subsystem for Linux) 안에 설치해야 했습니다. 지금은 네이티브 설치가 권장이지만, WSL 환경에서 개발하는 분은 Mac·Linux와 같은 명령을 WSL 셸에서 실행하면 됩니다.

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

WSL 1에서는 cannot execute binary file: Exec format error라는 알려진 네이티브 바이너리 회귀가 발생할 수 있습니다. 그 경우 WSL 2로 변환하거나 동적 링커 경유 우회책이 필요하며, 공식에서도 WSL 2 사용을 권장합니다. WSL은 Windows 위에서 Linux를 가상으로 돌리는 것이라 네이티브 Windows 설치에 비하면 오버헤드가 있으니, 특별한 이유가 없으면 PowerShell 설치를 고르세요.

npm 경유 설치 (대체)

Windows에서도 네이티브가 안 될 때는 npm으로 설치할 수 있습니다. Node.js 22 이상이 필요하고, 관리자 권한으로 npm 글로벌 설치를 하면 권한 문제의 원인이 될 수 있습니다.

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

설치가 잘 됐는지 확인하기

여기부터는 Mac·Windows 공통입니다. 터미널(Windows는 PowerShell 또는 명령 프롬프트)에서 순서대로 실행합니다.

1. 버전 확인 — claude --version이 버전 번호를 출력하면 설치와 경로 설정이 끝난 것입니다.
2. 첫 실행과 로그인 — claude를 실행하면 브라우저가 열리며 로그인을 요구합니다. Claude.ai 또는 Claude Console 계정으로 로그인하면 인증 정보가 로컬에 저장돼 다음부터는 자동으로 로그인됩니다.
3. 환경 진단 — 문제가 의심되면 claude doctor를 실행합니다.

claude --version
claude
claude doctor

claude doctor는 설치 타입, 버전 정보, 환경 설정 상태를 표시하고 문제가 있으면 경고나 오류 메시지를 출력하므로 트러블슈팅의 첫걸음으로 쓸 수 있습니다. 이 밖의 기본 커맨드는 기본 조작과 명령어에 정리돼 있습니다.

초기에 해두면 좋은 두 가지

작업할 프로젝트 폴더로 이동한 다음 claude를 실행하면 그 프로젝트에 대해 질문하거나 코드 수정을 부탁할 수 있습니다.

cd ~/projects/my-app
claude

1. 프로젝트 지침 파일 만들기

세션 안에서 /init을 실행하면 저장소를 훑어 CLAUDE.md 초안을 만들어 줍니다.

/init

이 파일에는 빌드 명령, 코드 컨벤션, 하지 말아야 할 일 등을 적습니다. 자세한 내용은 CLAUDE.md 작성법을 참고하세요.

2. 권한 모드 이해하기

기본값은 파일 수정이나 명령 실행 전에 매번 확인을 요청하는 모드입니다. 익숙해지기 전까지는 이 기본값을 유지하는 편이 안전합니다. 반복 확인이 번거로우면 자주 쓰는 읽기 전용 명령만 허용 목록에 넣으세요. 설정 방법은 퍼미션 설정 최적화에서 다룹니다.

자주 겪는 문제와 대처법

커맨드를 찾을 수 없는 경우 (공통)

설치 후 claude 커맨드를 찾을 수 없다면 터미널을 닫았다가 다시 열어 주세요. 셸 설정 파일과 환경 변수가 다시 읽히면서 경로가 잡힙니다. Mac에서는 재시작 대신 아래를 실행해도 됩니다.

source ~/.zshrc

이걸로 해결되지 않으면 설치가 정상 완료되지 않았을 가능성이 있습니다. 설치 명령을 다시 실행해 보세요.

원격 서버에서 로그인 창이 안 열리는 경우 (공통)

브라우저를 띄울 수 없는 환경에서는 터미널에 출력된 URL을 로컬 브라우저에 직접 붙여 넣어 인증하면 됩니다.

Mac에서 권한 오류가 나는 경우

네이티브 설치에서 권한 오류가 나면 ~/.local/bin의 소유권을 고친 뒤 재실행하면 해결됩니다.

sudo mkdir -p ~/.local/bin && sudo chown -R $(whoami) ~/.local
curl -fsSL https://claude.ai/install.sh | bash

설치 프로그램 자체에 sudo를 붙여 실행하는 것은 보안 리스크가 따릅니다. sudo는 ~/.local/bin이나 ~/.claude의 소유권 수정에만 쓰고, 설치 자체는 sudo 없이 실행하세요.

Mac에 npm 버전이 이미 설치돼 있는 경우

이전에 npm으로 설치했었다면 먼저 제거하고 터미널을 재시작한 뒤 네이티브 설치를 진행하면 매끄럽게 됩니다.

# npm판 제거
npm uninstall -g @anthropic-ai/claude-code

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

Windows에서 실행 정책 오류가 나는 경우

PowerShell에서 "스크립트 실행이 사용 안 함으로 설정되어 있습니다" 같은 오류가 나면 실행 정책을 바꿔야 합니다. 관리자 권한으로 PowerShell을 열고 아래 명령을 실행하세요.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

실행 정책 변경은 보안에 관련된 설정입니다. 회사 환경 등에서 정책이 제한돼 있다면 IT 관리자와 상의하세요.

Windows 백신 프로그램이 설치를 차단하는 경우

일부 백신 프로그램이 설치 스크립트를 차단합니다. 일시적으로 실시간 보호를 끄고 설치한 뒤, 설치가 끝나면 실시간 보호를 다시 켜는 것을 잊지 마세요.

정리

• Mac은 install.sh, Windows는 install.ps1 한 줄로 설치되며 Node.js는 필요 없습니다.
• npm·명령 프롬프트·WSL은 네이티브가 안 될 때의 대체 경로이고, WSL은 반드시 WSL 2를 씁니다.
• 설치 후 claude --version → claude(로그인) → claude doctor 순으로 확인합니다.
• 명령을 못 찾으면 터미널 재시작, 권한 오류는 sudo·관리자 권한을 최소한으로만 씁니다.
• 프로젝트 폴더에서 /init으로 CLAUDE.md를 만들고 나면 첫 세션 실전으로 넘어가면 됩니다.