클로드 코드 설치 명령어는 운영체제마다 한 줄씩입니다. 맥과 리눅스는 터미널에 curl -fsSL https://claude.ai/install.sh | bash, 윈도우 PowerShell은 irm https://claude.ai/install.ps1 | iex를 붙여 넣고 엔터를 누르면 됩니다. 설치가 끝나면 새 터미널 창을 열고 claude --version을 쳐서 버전 숫자가 나오는지 보는 것까지가 설치입니다.
이 글은 Anthropic이 공개한 Claude Code 공식 문서(빠른 시작, 고급 설정, 터미널 가이드, 설치 문제 해결, 데스크톱 앱 시작하기, 2026년 10월 9일 기준)의 내용만 정리한 것입니다. 클로드코드를 처음 설치하는 분이 어디에서 가장 많이 멈추는지, 그때 화면에 뜨는 문구가 무엇이고 무엇을 하면 되는지를 순서대로 담았습니다.
미리 알아 둘 점이 하나 있습니다. 공식 문서는 Claude Code를 쓰려면 Pro, Max, Team, Enterprise 또는 Console 계정이 필요하고, 무료 claude.ai 플랜에는 Claude Code 접근이 포함되지 않는다고 적고 있습니다. 설치는 무료로 되어도 로그인 단계에서 막힐 수 있으니, 요금제부터 확인하고 시작하는 편이 낫습니다. 앤트로픽 고객센터의 Pro·Max 요금제로 Claude Code 쓰기 문서는 Claude와 같은 계정으로 로그인하라고 안내하고, 환경 변수 ANTHROPIC_API_KEY가 설정돼 있으면 구독 대신 그 키가 쓰여 API 요금이 청구된다고 경고합니다.
설치 전에 확인할 것: 내 컴퓨터와 계정
공식 문서가 적은 지원 환경은 아래와 같습니다. 이 가운데 하나라도 맞지 않으면 설치 명령을 아무리 다시 쳐도 같은 자리에서 막힙니다.
| 항목 | 공식 문서의 요건 |
|---|---|
| 운영체제 | macOS 13.0 이상, Windows 10 1809 이상 또는 Windows Server 2019 이상, Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상 |
| 하드웨어 | 메모리 4GB 이상, x64 또는 ARM64 프로세서 |
| 네트워크 | 인터넷 연결 필수 |
| 셸 | Bash, Zsh, PowerShell, CMD 중 하나 |
| 지역 | Anthropic이 지원하는 국가 |
| 계정 | Pro, Max, Team, Enterprise, Console 중 하나(무료 claude.ai 플랜은 해당 없음) |
맥을 쓴다면 화면 왼쪽 위 사과 메뉴에서 이 Mac에 관하여를 눌러 macOS 버전이 13.0 이상인지 먼저 보세요. 문서의 문제 해결 표에는 dyld: cannot load나 built for Mac OS X 13.0 같은 문구가 뜨면 macOS가 지원 버전보다 낮은 경우라고 적혀 있고, 소프트웨어 업데이트로 올리라고 안내합니다.
윈도우는 Git for Windows가 필수가 아닙니다. 문서는 설치하면 Bash 도구를 쓸 수 있어 권장하지만, 없으면 Claude Code가 PowerShell을 대신 쓴다고 설명합니다. 처음에는 Git 없이 시작해도 됩니다.
내 화면 글자로 고르는 설치 명령어
처음 막히는 곳은 명령어 자체가 아니라 "내가 지금 어느 창에 붙여 넣고 있는지"입니다. 같은 윈도우라도 PowerShell과 CMD는 명령이 다릅니다. 아래 표는 터미널 창의 맨 앞 글자를 기준으로 고르게 만들었습니다.
| 창 맨 앞에 보이는 글자 | 쓰는 창 | 붙여 넣을 명령 |
|---|---|---|
이름@컴퓨터 ~ % 형태 (맥) | 맥 터미널(Zsh) | 맥·리눅스용 install.sh 명령(글 맨 위 첫 번째) |
$ 로 끝나는 줄 (리눅스, WSL) | Bash | 맥·리눅스용 install.sh 명령과 같음 |
PS C:\Users\이름> | 윈도우 PowerShell | PowerShell용 irm 명령(글 맨 위 두 번째) |
C:\Users\이름> (PS 없음) | 윈도우 CMD | curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd |
PowerShell인지 CMD인지는 줄 맨 앞의 PS 두 글자로 구분합니다. 문서가 직접 적은 기준입니다. 터미널을 여는 방법도 문서에 있습니다. 맥은 Cmd + Space를 눌러 Spotlight에 Terminal을 입력하고 엔터, 윈도우는 Win + X를 누르고 Windows PowerShell(또는 Terminal)을 고릅니다.
붙여 넣기는 맥이 Cmd + V, 리눅스가 Ctrl + Shift + V, 윈도우 PowerShell은 Ctrl + V 또는 마우스 오른쪽 클릭입니다. 엔터를 누른 뒤에는 화면에 진행 표시가 없습니다. 문서도 설치 명령은 내려받는 동안 아무것도 보여 주지 않으니 창을 닫지 말고 기다리라고 적었습니다. 끝나면 "Claude Code successfully installed!" 문구가 나옵니다.
설치 확인과 첫 실행: 클로드코드가 켜지는 순서
설치가 끝났다고 바로 claude를 치지 말고, 새 터미널 창을 하나 더 여는 것이 문서가 권하는 순서입니다. 설치기가 바꾼 경로 설정은 새 창에서 읽히기 때문입니다.
1단계: 새 터미널 창을 엽니다.
2단계: claude --version을 입력합니다. 문서는 정상이면 2.1.211 (Claude Code)처럼 버전 번호와 괄호 안의 이름이 나온다고 예시를 들었습니다.
3단계: 작업할 폴더에서 claude를 입력합니다. 처음 실행하면 로그인하라는 안내가 나옵니다.
4단계: 브라우저가 열리면 Claude 계정으로 로그인합니다. 한 번 로그인하면 인증 정보가 저장되어 다시 로그인하지 않아도 됩니다.
5단계: 환영 화면이 보이면 끝입니다. 터미널에서는 마우스로 클릭할 수 없고 방향키로 움직입니다. 실행 중인 Claude를 멈추려면 Esc, 나가려면 exit를 입력하거나 빈 입력 줄에서 Ctrl + D를 두 번 누릅니다. 도움말은 /help입니다.
설치와 설정을 더 꼼꼼히 확인하고 싶다면 claude doctor를 쓰세요. 문서에 따르면 세션을 시작하지 않고 설치 상태와 설정 파일 오류, 경고와 해결 제안을 읽기 전용으로 보여 줍니다.
클로드 코드 설치 안됨: 문구별 원인과 해결
설치 문제 해결 문서에는 증상별 표가 있습니다. 그중 처음 설치하는 분이 가장 많이 만날 만한 것만 골라, 화면에 뜨는 문구를 기준으로 다시 묶었습니다.
| 화면에 뜨는 문구 | 원인(문서 설명) | 해결 |
|---|---|---|
command not found: claude (맥, 리눅스) 또는 'claude' is not recognized (윈도우) | 설치 폴더가 PATH에 없음 | 아래 PATH 항목 참고 후 새 터미널에서 다시 실행 |
syntax error near unexpected token '<' | 설치 주소가 스크립트 대신 웹 페이지를 돌려줌 | 명령을 다시 실행, 반복되면 Homebrew 같은 다른 방법 사용 |
irm is not recognized | CMD 창에서 PowerShell 명령을 침 | PowerShell을 열거나 CMD용 명령 사용 |
The token '&&' is not a valid statement separator | PowerShell 창에서 CMD 명령을 침 | PowerShell용 irm 명령 사용 |
App unavailable in region | 지원되지 않는 지역 | 해결책이 아니라 지원 국가 문제, 공식 지원 국가 목록 확인 |
Claude Code does not support 32-bit Windows | 64비트 PC에서 Windows PowerShell (x86)을 연 경우가 많음 | x86 표시가 없는 PowerShell을 열어 다시 설치 |
Killed 또는 종료 코드 137 (리눅스) | 메모리가 부족한 서버(설치에 여유 메모리 약 512MB 필요) | 메모리를 확보하거나 스왑 공간 추가 |
표에서 눈에 띄는 점은 윈도우의 두 문구입니다. 같은 "명령이 안 먹는다"인데 하나는 CMD에서 PowerShell 명령을 쳤고, 다른 하나는 반대입니다. 문서는 줄 맨 앞의 PS 유무로 구분하라고 안내합니다.
App unavailable in region 문구는 설치 요령으로 풀리지 않습니다. 문서는 해당 국가에서 Claude Code를 쓸 수 없다는 뜻이라고 설명하고 지원 국가 목록 링크를 줍니다. 한국 지원 여부는 이 글이 단정할 수 없으니 Anthropic의 지원 국가 페이지에서 직접 확인하세요.
PATH 문제: 설치했는데 claude가 없다고 나올 때
가장 흔한 막힘은 설치가 끝났는데 claude를 치면 못 찾겠다는 문구가 나오는 경우입니다. 문서는 설치기가 claude를 홈 폴더 아래 .local/bin 폴더($HOME/.local/bin)에 두는데, 그 폴더가 PATH(운영체제가 프로그램을 찾는 폴더 목록)에 없을 때 생긴다고 설명합니다.
맥(Zsh)은 터미널에 아래 두 줄을 차례로 입력하라고 안내합니다.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> $HOME/.zshrc
source $HOME/.zshrc
Linux에서 Bash를 쓴다면 같은 명령에서 $HOME/.zshrc 자리만 $HOME/.bashrc로 바꿉니다. 맥에서 Bash를 쓰는 경우는 $HOME/.bash_profile에 넣으라는 별도 안내가 있습니다. 맥은 Bash를 로그인 셸로 시작해서 $HOME/.bashrc를 읽지 않기 때문이라고 문서가 이유를 적었습니다.
윈도우 PowerShell은 아래 두 줄입니다.
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
실행한 뒤 PowerShell을 닫고 새 창을 열어 claude --version을 다시 확인합니다. 그래도 안 되면 $HOME/.local/bin/claude 파일이 실제로 있는지 보라고 문서는 말합니다. 파일이 없다면 PATH가 아니라 설치가 끝나지 않은 것입니다.
윈도우에는 문서에 따로 적힌 함정도 있습니다. 오래된 Claude Desktop이 WindowsApps 폴더에 Claude.exe를 등록해 두면, 터미널에서 claude를 쳤을 때 CLI 대신 데스크톱 앱이 열릴 수 있습니다. 해결은 Claude Desktop을 최신 버전으로 업데이트하는 것이라고 문서에 적혀 있습니다.
터미널이 부담스러울 때: 데스크톱 앱과 다른 설치 방법
공식 문서는 기본 설치 방법을 "Native Install (Recommended)"로 소개하지만, 다른 길도 같이 보여 줍니다.
| 방법 | 명령 또는 경로 | 문서에 적힌 특징 |
|---|---|---|
| Homebrew(맥) | brew install --cask claude-code | 자동 업데이트 안 됨, brew upgrade claude-code로 직접 올림 |
| WinGet(윈도우) | winget install Anthropic.ClaudeCode | 자동 업데이트 안 됨, winget upgrade Anthropic.ClaudeCode로 직접 올림 |
| npm | npm install -g @anthropic-ai/claude-code | Node.js 22 이상 필요, sudo 사용 금지 |
| 데스크톱 앱 | Claude 앱의 Code 탭 | 터미널 없이 사용, Node.js나 CLI 설치 불필요 |
Homebrew에는 두 가지 이름이 있습니다. claude-code는 보통 최신보다 약 일주일 늦은 안정 채널을 따르고, claude-code@latest는 새 버전이 나오는 즉시 받습니다. 문서가 직접 설명한 차이입니다.
npm 방식은 문서가 "sudo를 붙여 설치하지 말라"고 분명히 적었습니다. 권한 오류가 나더라도 sudo로 밀어붙이면 권한 문제와 보안 위험이 생길 수 있다는 이유입니다. 터미널이 낯선 분이라면 npm보다 위의 기본 명령이나 데스크톱 앱이 단순합니다.
데스크톱 앱은 Code 탭에서 폴더를 고르고 일을 시키는 방식입니다. 문서에 따르면 Code 탭을 눌렀을 때 업그레이드 안내가 나오면 유료 구독이 필요한 경우입니다. 터미널 명령을 한 줄도 치고 싶지 않다면 이쪽이 처음에는 덜 막힙니다. 이미 앱을 쓰고 있어도 터미널에서 claude 명령을 쓰고 싶다면 CLI는 따로 설치해야 한다고 문서가 구분해 둡니다.
로그인에서 막힐 때와 업데이트
설치는 됐는데 로그인에서 멈추는 경우도 문서에 정리되어 있습니다.
브라우저가 자동으로 열리지 않으면 터미널에서 c를 눌러 로그인 주소를 복사한 뒤 브라우저에 직접 붙여 넣습니다. OAuth error: Invalid code 문구는 로그인 코드가 만료됐거나 복사 중에 잘렸다는 뜻이니, 엔터로 다시 시도하고 브라우저가 열리면 빠르게 로그인을 끝내라고 안내합니다. 원인을 모르겠다면 /logout으로 완전히 나가고, Claude Code를 닫은 뒤 claude로 다시 시작해 인증을 처음부터 하는 것이 문서가 권하는 초기화 순서입니다.
403 Forbidden이 뜨면 문서는 Pro나 Max 사용자는 claude.ai 설정에서 구독이 활성 상태인지 확인하라고 말합니다. This organization has been disabled가 구독이 살아 있는데도 뜬다면, 예전 프로젝트에서 쓰던 ANTHROPIC_API_KEY 환경변수가 남아 구독 인증을 덮어쓰는 경우라고 문서가 설명합니다. 회사 노트북을 물려받았거나 예전 키를 셸 설정에 넣어 둔 분이 확인해 볼 부분입니다.
업데이트는 설치 방식에 따라 다릅니다. 기본 설치(Native)는 백그라운드에서 자동으로 업데이트되고, 즉시 올리고 싶으면 claude update를 실행합니다. Homebrew와 WinGet, apt, dnf, apk로 설치한 경우는 자동 업데이트가 기본이 아니라서 각자의 업그레이드 명령을 직접 실행해야 합니다.
정리: 처음 설치할 때 이 순서대로
① 먼저 요금제를 확인합니다. 무료 claude.ai 플랜만으로는 Claude Code를 쓸 수 없다고 문서에 적혀 있습니다.
② 내 창이 PowerShell인지 CMD인지, 맥 터미널인지 맨 앞 글자로 확인하고 맞는 명령 한 줄을 붙여 넣습니다.
③ 진행 표시가 없어도 창을 닫지 말고 기다린 뒤 새 터미널을 열어 claude --version을 칩니다.
④ claude를 찾을 수 없다고 나오면 명령을 다시 치기 전에 $HOME/.local/bin이 PATH에 있는지부터 봅니다.
⑤ 이상하면 claude doctor로 설치 상태를 읽고, 터미널이 부담스러우면 데스크톱 앱의 Code 탭으로 시작합니다.
설치 문구와 지원 환경은 공식 문서가 계속 고치는 내용입니다. 위 표의 버전 숫자와 명령은 2026년 10월 9일에 연 문서 기준이니, 막히면 아래 확인 자료의 최신 화면을 먼저 보세요.