클로드 코드 설치, 막막하셨죠?
처음 Claude Code(클로드 코드)를 써보려고 했을 때 “터미널에 뭔가 치라는데 어디서부터 시작해야 하지?”라고 막막하셨던 분들 많으실 겁니다. 사실 클로드 코드 설치는 몇 가지 단계만 제대로 따라 하면 10분 안에 끝낼 수 있어요. Node.js(노드JS — 자바스크립트를 컴퓨터에서 실행하게 해주는 프로그램)만 먼저 설치되어 있으면, 나머지는 명령어 한 줄로 끝납니다.
이 글에서는 윈도우(Windows)와 맥(macOS) 각각의 설치 방법을 단계별로 설명드리고, 자주 발생하는 오류와 해결법까지 알려드리겠습니다.
설치 전 필수 확인: 시스템 요구사항
Claude Code를 설치하기 전에 아래 조건을 먼저 확인하세요.
| 항목 | 요구사항 |
|---|---|
| Node.js 버전 | 22 이상 권장 |
| 운영체제 | Windows 10/11, macOS 12 이상 |
| 계정 | Claude Pro/Max/Teams 구독 또는 API 콘솔 계정 |
| 인터넷 연결 | 설치 시 필수 |
Node.js란? 자바스크립트(JavaScript) 코드를 웹 브라우저 밖에서도 실행할 수 있게 해주는 런타임 환경(실행 프로그램)입니다. Claude Code가 이 위에서 동작합니다.
1단계: Node.js 설치하기 (윈도우·맥 공통)
🪟 윈도우 (Windows)
- nodejs.org 공식 사이트에 접속합니다.
- LTS(Long Term Support — 장기 지원 버전) 버튼을 클릭해 설치 파일을 받습니다.
- 다운로드된
.msi파일을 실행하고 “다음 → 다음 → 설치” 순서로 진행합니다. - 설치 완료 후, PowerShell 또는 명령 프롬프트(cmd)를 새로 열어 버전을 확인합니다:
node -v
npm -v
v22.x.x 형태로 버전이 출력되면 성공입니다.
🍎 맥 (macOS)
맥에서도 nodejs.org에서 .pkg 파일을 받아 설치할 수 있습니다. 다만 Homebrew(홈브루 — 맥용 패키지 관리자)를 사용하는 방법이 더 편리합니다:
# Homebrew 설치 (이미 있으면 건너뜁니다)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Node.js 설치
brew install node
설치 후 터미널에서 node -v로 버전을 확인하세요.
2단계: Claude Code 설치하기 (npm 명령어 한 줄)
Node.js 설치가 완료됐다면, 이제 Claude Code를 설치할 차례입니다. npm(Node Package Manager — Node.js에서 사용하는 패키지 설치 도구)을 이용해 전역(컴퓨터 어디서든 실행 가능하도록) 설치합니다.
윈도우 PowerShell 또는 맥 터미널에서 아래 명령어를 실행하세요:
npm install -g @anthropic-ai/claude-code
⚠️ 중요 주의사항: 맥·리눅스에서
sudo를 절대 붙이면 안 됩니다.sudo npm install -g는 권한 문제와 보안 오류를 일으킬 수 있습니다.
설치 후 아래 명령어로 정상 설치 여부를 확인합니다:
claude --version
버전 번호가 출력되면 설치 성공입니다!
3단계: 첫 실행 및 계정 로그인
설치 후 작업할 프로젝트 폴더로 이동해 claude를 실행합니다.
cd 내_프로젝트_폴더
claude
처음 실행 시 Anthropic 계정 로그인 화면이 나타납니다. 브라우저가 자동으로 열리며 로그인 절차가 진행됩니다.
- Claude Pro/Max 구독자: claude.ai 계정으로 로그인
- API 사용자: Anthropic Console 계정으로 로그인 후 API 키 입력
로그인이 완료되면 터미널에 > 프롬프트가 뜨고, 이제 Claude Code와 대화를 시작할 수 있습니다!
윈도우 vs 맥, 이것만 주의하세요
| 구분 | 윈도우 주의사항 | 맥 주의사항 |
|---|---|---|
| 터미널 | PowerShell 권장 | 기본 터미널 또는 iTerm2 |
| Git | 별도 설치 필요 (git-scm.com) | Xcode Command Line Tools로 설치 |
| sudo | 사용 안 함 | 절대 사용 금지 |
| 흔한 오류 | PATH 환경변수 설정 오류 | npm 권한(permission) 오류 |
| 업그레이드 | npm install -g @anthropic-ai/claude-code@latest |
동일 |
Git이란? 코드 변경 이력을 관리하는 버전 관리 도구입니다. Claude Code가 Git 기능을 활용하므로 함께 설치해 두는 것을 권장합니다.
자주 묻는 질문 (FAQ)
Q. claude 명령어를 쳤는데 “명령을 찾을 수 없습니다” 오류가 납니다.
A. Node.js를 설치했어도 PATH 환경변수(프로그램 위치를 운영체제에 알려주는 설정)가 아직 적용되지 않은 경우입니다. 윈도우에서는 터미널을 완전히 닫고 새로 열어보세요. 맥에서는 source ~/.zshrc 또는 source ~/.bash_profile을 실행한 뒤 다시 시도하면 해결되는 경우가 많습니다.
Q. npm install 중 EACCES 또는 permission denied 오류가 납니다.
A. 절대 sudo를 붙이지 마세요. 대신 npm 전역 설치 경로를 사용자 폴더로 변경하면 됩니다. 터미널에 npm config set prefix ~/.npm-global을 실행한 후, PATH에 ~/.npm-global/bin을 추가하면 해결됩니다.
Q. Node.js 버전이 20인데 설치 가능한가요?
A. 기술적으로 설치는 되지만 Node.js 22 이상을 권장합니다. 버전이 낮으면 EBADENGINE 경고 메시지가 뜨고 일부 기능이 불안정할 수 있습니다. nvm(Node Version Manager — 노드 버전 관리 도구)을 사용하면 버전 전환이 간편합니다.
한 줄 요약: Node.js 22 설치 → npm install -g @anthropic-ai/claude-code → claude 실행 → 로그인, 이 네 단계면 클로드 코드 설치가 완료됩니다.
참고 자료
– Claude Code 공식 설치 문서 (code.claude.com)
– @anthropic-ai/claude-code npm 공식 패키지 페이지
– Claude Code GitHub 공식 저장소 (anthropics/claude-code)