클로드 코드 처음 설치, 맥·윈도우 명령 한 줄 | 설치가 막힐 때 볼 세 곳

클로드 코드(Claude Code)를 써 보려고 마음먹었는데 첫 화면이 검은 터미널이라 멈칫하는 분이 많습니다. 설치 자체는 명령 한 줄이면 끝나지만, 윈도우에서 창을 잘못 열었거나 설치 위치가 경로에 안 잡혀 "claude를 찾을 수 없다"는 말에서 막히곤 합니다.

한 줄 요약: 맥은 터미널에 curl -fsSL https://claude.ai/install.sh | bash, 윈도우는 PowerShell에 irm https://claude.ai/install.ps1 | iex 한 줄이면 설치된다. 새 터미널 창을 열고 claude --version으로 버전이 나오면 성공이다. 이후 claude를 실행해 브라우저로 로그인하는데, 클로드 무료 플랜으로는 쓸 수 없고 Pro·Max·Team·Enterprise 또는 Console 계정이 필요하다. "claude를 찾을 수 없다"가 나오면 PATH부터 본다.

목차

1. 설치 전에 확인할 세 가지

2. 맥에 설치하기

3. 윈도우에 설치하기

4. 처음 실행하고 로그인하기

5. 설치·실행이 막힐 때 볼 세 곳

1. 설치 전에 확인할 세 가지

항목	공식 요구 사항
운영체제	macOS 13.0 이상, Windows 10 1809 이상, Ubuntu 20.04·Debian 10 이상 등
하드웨어	메모리 4GB 이상, x64 또는 ARM64 프로세서
계정	Pro·Max·Team·Enterprise 또는 Console 계정. 클로드 무료 플랜은 포함되지 않음

핵심 지원 운영체제와 지역 요건을 맞추면 설치는 되지만, 실행하려면 유료 계정이 필요합니다. 공식 문서는 "free claude.ai plan does not include Claude Code access"라고 적어 두었습니다. 무료로 클로드를 쓰는 중이라면 결제 전에 이 점부터 확인하세요.

터미널이 처음이라면 클로드 데스크톱 앱 안에서 클로드 코드를 쓰는 방법도 있습니다. 공식 문서는 그래픽 화면을 원하면 맥·윈도우용 데스크톱 앱을 받으라고 안내합니다. 이 글은 터미널 설치를 기준으로 합니다.

3줄 선택 가이드

• 맥이고 터미널이 처음이다 → 아래 curl 한 줄(자동 업데이트됨)
• Homebrew로 앱을 관리하는 편이다 → brew install --cask claude-code(업데이트는 직접)
• 윈도우다 → PowerShell에서 irm 한 줄. CMD 창이면 CMD용 명령을 따로 쓴다

2. 맥에 설치하기

Spotlight(⌘+스페이스)에서 "터미널"을 찾아 열고, 아래 명령을 붙여 넣습니다.

맥·리눅스·WSL 설치

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

재구성한 예시 화면(명령 기준: Claude Code 공식 문서)

설치가 끝나면 새 터미널 창을 열어 버전을 확인합니다. 공식 문서 예시처럼 "2.1.211 (Claude Code)" 같은 형식으로 번호가 나오면 성공입니다.

설치 확인

claude --version

출처: Claude Code 공식 문서 갈무리

Homebrew를 쓴다면 brew install --cask claude-code로도 설치됩니다. 다만 공식 문서 기준 Homebrew 설치는 자동으로 업데이트되지 않으니 가끔 brew upgrade claude-code를 실행해야 합니다. curl로 설치한 기본(네이티브) 설치는 백그라운드에서 알아서 업데이트됩니다.

3. 윈도우에 설치하기

시작 메뉴에서 PowerShell(또는 Windows 터미널)을 엽니다. 관리자 권한은 필요 없습니다. 프롬프트가 PS C:\Users\이름>처럼 PS로 시작하면 PowerShell입니다.

윈도우 PowerShell 설치

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

재구성한 예시 화면(명령 기준: Claude Code 공식 문서)

PS 없이 C:\Users\이름>만 보이는 검은 창은 CMD(명령 프롬프트)입니다. CMD에서는 아래 명령을 씁니다.

윈도우 CMD 설치

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

WinGet을 쓰면 winget install Anthropic.ClaudeCode로도 됩니다. 이 방식도 자동 업데이트가 안 되므로 winget upgrade Anthropic.ClaudeCode를 가끔 실행합니다. 공식 문서는 윈도우에서 Git for Windows 설치를 권장하지만 필수는 아니고, 없으면 클로드 코드가 PowerShell로 명령을 실행합니다.

4. 처음 실행하고 로그인하기

작업할 폴더로 이동한 뒤 claude를 입력하면 터미널 안에서 대화형 세션이 열립니다. 처음 실행할 때 브라우저가 열리며 로그인 안내가 나오고, 그 안내를 따라 클로드 계정으로 로그인하면 됩니다.

프로젝트 폴더에서 시작

cd 내프로젝트폴더
claude

출처: Claude Code 공식 문서 갈무리

환경 변수에 ANTHROPIC_API_KEY가 들어 있으면 브라우저 대신 그 키를 쓸지 한 번 묻습니다. 구독 계정으로 쓰려던 경우라면 예전에 넣어 둔 API 키가 남아 있지 않은지 확인하세요.

설치 상태를 더 자세히 보고 싶으면 claude doctor를 실행합니다. 공식 문서 설명으로는 세션을 열지 않고 설치 상태와 설정 오류, 해결 제안을 읽기 전용으로 보여 줍니다.

5. 설치·실행이 막힐 때 볼 세 곳

첫째, PATH. 설치는 됐는데 command not found: claude나 "인식되지 않습니다"가 나오면 설치 폴더가 PATH에 없는 경우입니다. 공식 문서 기준 설치 위치는 맥·리눅스 ~/.local/bin/claude, 윈도우 %USERPROFILE%\.local\bin\claude.exe입니다. 맥 기본 셸(zsh)이라면 아래처럼 추가합니다.

맥 PATH 확인과 추가(zsh)

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

재구성한 예시 화면(명령 기준: Claude Code 공식 문서)

윈도우는 PowerShell 설치가 끝났는데 claude를 못 찾으면, 공식 문서 안내대로 %USERPROFILE%\.local\bin을 PATH에 추가한 뒤 새 터미널을 엽니다. 옛 버전이 나온다면 PATH와 함께 다른 방법으로 설치한 claude가 먼저 잡히는지도 확인합니다.

둘째, 창 종류와 설치 중복. PowerShell에 CMD용 명령을 넣으면 "The token '&&' is not a valid statement separator", CMD에 PowerShell 명령을 넣으면 "'irm' is not recognized"가 나옵니다. 창에 맞는 명령으로 다시 실행하면 됩니다. 예전에 npm 등으로 따로 설치했다면 다른 버전이 먼저 잡힐 수 있으니, 공식 문서의 "conflicting installations" 항목을 보고 하나만 남깁니다.

재구성한 예시 화면(명령 기준: Claude Code 공식 문서)

셋째, 요금제. 이건 "claude를 찾을 수 없다"와는 다른 경우입니다. 명령은 실행되는데 로그인 뒤 쓸 수 없다면 계정 문제입니다. 무료 플랜은 클로드 코드를 포함하지 않습니다. 구독을 했는데도 인식이 안 되면 공식 문서는 claude.ai에서 Get help로 문의하라고 안내합니다.

출처: Claude Code 공식 문서 갈무리

Q. 클로드 코드는 무료로 쓸 수 있나요?

공식 설치 문서 기준으로는 아닙니다. Pro·Max·Team·Enterprise 또는 Console(API) 계정이 필요하고 클로드 무료 플랜은 포함되지 않습니다.

Q. npm으로 설치해도 되나요?

됩니다. 공식 문서는 Node.js 22 이상에서 npm install -g @anthropic-ai/claude-code를 안내합니다. 다만 sudo npm install -g는 쓰지 말라고 적어 두었고, 처음이라면 위의 한 줄 설치가 더 간단합니다.

Q. 윈도우에서 관리자 권한으로 열어야 하나요?

아닙니다. 공식 문서는 PowerShell이나 CMD에서 관리자 권한 없이 설치 명령을 실행하면 된다고 안내합니다.

Q. 업데이트는 어떻게 하나요?

curl·irm으로 한 기본 설치는 자동으로 업데이트됩니다. 바로 올리고 싶으면 claude update를 실행합니다. Homebrew·WinGet 설치는 brew upgrade, winget upgrade로 직접 올려야 합니다.

3줄 핵심 요약

1. 맥은 curl 한 줄, 윈도우는 PowerShell irm 한 줄로 설치하고 새 창에서 claude --version으로 확인한다.
2. 실행에는 Pro 이상 유료 계정이나 Console 계정이 필요하다. 무료 플랜으로는 쓸 수 없다.
3. claude를 못 찾으면 PATH와 창 종류·설치 중복을, 로그인 뒤 막히면 요금제를 확인한다.

마치며

설치를 마쳤다면 오늘은 작은 연습용 폴더 하나를 만들어 그 안에서 claude를 실행해 보세요. 중요한 프로젝트보다 버려도 되는 폴더에서 먼저 써 보면, 클로드 코드가 파일을 고치기 전에 무엇을 묻는지 부담 없이 익힐 수 있습니다.

NEXT READ

이어서 읽어 볼 글

01  클로드 코드 Mods 나왔다, 플러그인·훅·스킬과 뭐가 다른가 · 설치 다음 단계

02  클로드 코드 세션끼리 대화한다 · 여러 세션 쓰는 법

03  클로드 소네트 5.5, 무료 플랜에서도 쓴다 · 요금제 고를 때

#클로드코드,#ClaudeCode,#클로드코드설치,#AI코딩,#터미널,#PowerShell,#바이브코딩,#코딩입문,#Anthropic,#코드노트