클로드 코드 설치 방법(Claude Code install): 윈도우·맥 공식 명령 한 줄

클로드 코드(Claude Code)는 공식 설치 명령 한 줄로 설치합니다. Windows는 PowerShell에 irm https://claude.ai/install.ps1 | iex, Mac·Linux·WSL은 터미널에 curl -fsSL https://claude.ai/install.sh | bash를 붙여 넣으면 됩니다. 설치가 끝나면 터미널 창을 새로 열고 claude --version을 입력해 버전 번호 뒤에 (Claude Code)가 붙어 나오면 성공입니다. 공식 문서의 출력 예시는 2.1.211 (Claude Code)이고, 숫자는 설치한 시점의 버전으로 나와요.

이 글은 2026년 10월 16일 공식 설치 문서 기준입니다. 명령이 무슨 뜻인지, 어디에 붙여 넣는지, 안전한지 확인하는 방법부터 적고 Homebrew·WinGet·npm 같은 다른 설치 방법, 로그인, 자주 나는 오류, 업데이트와 삭제를 차례로 정리했습니다.

irm https://claude.ai/install.ps1 | iex는 무슨 명령인가요

Windows PowerShell용 Claude Code 공식 설치 명령으로, 내려받기(irm)와 실행(iex)을 |로 이은 한 줄입니다. irm은 PowerShell의 Invoke-RestMethod를 줄여 쓴 이름으로, 뒤의 주소에서 설치 스크립트를 내려받습니다. |는 앞 결과를 뒤로 넘기고 iex(Invoke-Expression)가 넘겨받은 스크립트를 실행합니다. 공식 터미널 안내도 "irm은 파일을 가져오고 iex는 실행한다"고 설명합니다.

어디서 실행하나요? PowerShell 창입니다. Win + X를 누르고 Windows PowerShell(또는 터미널)을 고르면 열립니다. 줄 맨 앞에 PS C:\Users\이름>이 보이면 맞게 연 겁니다. 관리자 권한으로 열 필요는 없습니다. CMD에 붙여 넣으면 'irm' is not recognized 오류가 나니 CMD에서는 위 표의 CMD 명령을 씁니다.

진행 표시가 없어요. 내려받는 동안 화면에 아무것도 안 나오는 게 정상입니다. 창을 닫지 말고 기다리면 Claude Code successfully installed!가 뜹니다.

안전한지 어떻게 확인하나요? 이 방식은 주소가 돌려주는 내용을 그대로 실행합니다. 마이크로소프트 문서도 Invoke-Expression으로 명령을 실행할 때는 안전한지 먼저 확인하라고 안내하고요. 그래서 세 가지를 봅니다.

1. 주소가 정확히 https://claude.ai/install.ps1인지 봅니다. 영상이나 블로그에서 복사했다면 공식 설치 문서의 명령과 한 글자씩 대조합니다. 도메인이 다르면 실행하지 않습니다.
2. 실행 전에 내용을 보고 싶다면 | iex를 빼고 irm https://claude.ai/install.ps1만 실행합니다. 공식 문제 해결 문서에 따르면 이렇게 하면 스크립트 글자만 화면에 찍히고 아무것도 설치되지 않습니다.
3. 설치 후 실행 파일 서명을 확인합니다. 공식 문서에 따르면 Windows용 실행 파일은 "Anthropic, PBC" 이름으로 서명돼 있습니다. 설치 위치는 %USERPROFILE%\.local\bin\claude.exe입니다.

$sig = Get-AuthenticodeSignature "$env:USERPROFILE\.local\bin\claude.exe"
$sig.Status
$sig.SignerCertificate.Subject

$sig.Status의 결과는 서명이 손상되지 않았는지 보여 줍니다. Valid면 서명 형식이 올바르다는 뜻이고(마이크로소프트 문서는 이것만으로 신뢰를 뜻하지는 않는다고 적습니다), NotSigned나 HashMismatch면 실행하지 말고 지웁니다. 누가 서명했는지는 $sig.SignerCertificate.Subject의 결과로 봅니다. 여기에 Anthropic, PBC가 들어 있어야 합니다.

설치 전에 확인할 것

프로그램 설치와 사용할 계정은 따로 준비해야 합니다. 공식 문서 기준으로 Claude Code는 Pro, Max, Team, Enterprise 또는 Console 계정이 필요하고 무료 Claude.ai 플랜에는 포함되지 않습니다. 요금 페이지에서도 Free 플랜의 Claude Code 항목은 "No"입니다. Console 계정(API 선불 크레딧)으로도 쓸 수 있는데 구독 한도와 API 토큰 과금은 계산 방식이 다릅니다. 차이는 클로드 요금제 비교에 정리했습니다.

요구 사항(같은 문서):

• 운영체제: macOS 13.0+, Windows 10 1809+ 또는 Windows Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
• 하드웨어: RAM 4GB 이상, x64 또는 ARM64 프로세서
• 셸: Bash, Zsh, PowerShell, CMD
• 인터넷 연결 필요, Anthropic 지원 지역에서만 설치·사용 가능(한국은 목록에 있습니다)

네이티브 설치에는 Node.js가 필요 없습니다. npm 방식만 Node.js 22 이상을 요구합니다. 더 낮은 버전이면 설치 중 EBADENGINE 경고가 뜨지만 설치는 끝나고 claude도 실행됩니다. npm 패키지도 결국 네이티브 설치와 같은 실행 파일을 받아 오기 때문입니다.

Mac·Linux·WSL에서 설치

Mac은 Cmd + Space로 Spotlight를 열고 Terminal을 입력해 터미널을 엽니다. 그다음 공식 명령을 붙여 넣고 Enter를 누릅니다.

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

설치가 끝나면 터미널을 닫았다가 다시 열어 주세요. 컴퓨터가 명령어 위치를 찾는 경로인 PATH가 새로 반영되어야 claude가 실행됩니다.

claude --version

버전 번호 뒤에 (Claude Code)가 붙어 나오면 설치는 된 거예요. 실행 환경까지 점검하려면 claude doctor를 입력합니다. 세션을 시작하지 않고 설치 상태와 설정 파일 오류를 읽기 전용으로 보여 줍니다.

Homebrew를 쓰면 brew install --cask claude-code입니다. cask가 두 개 있습니다. claude-code는 보통 일주일쯤 늦게 따라가는 stable 채널이고 claude-code@latest는 새 버전이 나오자마자 받는 latest 채널입니다.

Alpine은 bash·curl이 기본으로 없어서 공식 설치 명령이 not found 오류로 실패합니다. 실행에 필요한 라이브러리까지 먼저 설치합니다.

apk add bash curl libgcc libstdc++ ripgrep

ripgrep을 못 찾는다고 나오면 Alpine 버전에 맞는 community 저장소를 /etc/apk/repositories에 추가하고 apk update 뒤 다시 설치합니다. 그다음 settings.json의 env에 USE_BUILTIN_RIPGREP을 "0"으로 넣어 시스템 ripgrep을 쓰게 합니다.

클로드 코드 윈도우(Windows) 설치

네이티브 Windows는 PowerShell과 CMD를 모두 지원하고 관리자 권한도 필요 없습니다. 순서는 이렇습니다.

1. Win + X → Windows PowerShell(또는 터미널)을 엽니다.
2. irm https://claude.ai/install.ps1 | iex를 붙여 넣고 Enter를 누릅니다. 진행 표시 없이 한동안 조용한 게 정상입니다.
3. Claude Code successfully installed!가 보이면 PowerShell 창을 새로 엽니다.
4. claude --version으로 버전이 나오는지 확인하고 claude로 실행합니다.

CMD를 쓰고 있다면 아래 명령입니다.

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

셸을 잘못 고르면 오류 메시지로 바로 알 수 있습니다.

• &&가 올바른 구분자가 아니라는 메시지: PowerShell에서 CMD 명령을 실행한 경우입니다.
• irm을 찾을 수 없다는 메시지: CMD에서 PowerShell 명령을 실행한 경우입니다.
• fsSL이라는 매개변수를 찾을 수 없다거나 bash를 인식하지 못한다는 메시지: Mac·Linux용 명령을 Windows에서 실행한 경우입니다. PowerShell 명령으로 바꿉니다.
• 설치는 안 되고 스크립트 글자만 화면에 찍힘: 명령의 앞부분만 실행한 경우입니다. | iex까지 한 줄로 붙여 넣습니다.

Claude Code는 64비트 Windows만 지원합니다. 시작 메뉴에서 Windows PowerShell (x86)을 열면 64비트 PC에서도 32비트 오류가 나니 x86이 붙지 않은 Windows PowerShell을 엽니다.

TLS·인증서 오류, PATH, 실행 정책처럼 Windows에서만 나는 설치 오류는 메시지별 해결 명령을 Windows에서 Claude Code 설치가 안 될 때에 따로 모았습니다.

Git for Windows는 CLI 네이티브 설치에 필수가 아닙니다. 공식 문서가 설치를 권하는 건 Bash 도구 때문입니다. 없으면 PowerShell 도구로 셸 명령을 실행하고 있으면 Git Bash로 Bash 도구를 씁니다. Git Bash 경로를 못 찾으면 settings.json의 env에 CLAUDE_CODE_GIT_BASH_PATH를 넣을 수 있습니다.

WSL을 쓴다면 WSL 터미널 안에서 Linux 설치 명령을 실행합니다. PowerShell에서 claude를 실행하는 것과는 별개입니다. WSL에서는 Git for Windows가 필요 없습니다. 명령 실행을 격리하는 샌드박스 기능은 macOS·Linux·WSL 2에서 동작하고 Windows에서는 WSL 2에서만 쓸 수 있습니다(네이티브 Windows와 WSL 1은 미지원). Linux 도구를 주로 쓰거나 샌드박스가 필요하면 WSL 2가 맞습니다.

터미널 없이 쓰려면: 클로드 데스크탑 앱

터미널이 부담스럽다면 클로드 데스크탑(Claude Desktop) 앱의 Code 탭으로 시작해도 됩니다. 앱 안에 Claude Code가 들어 있어서 Node.js나 CLI를 따로 설치할 필요가 없습니다. Code 탭은 Pro·Max·Team·Enterprise 구독에서 열립니다. 다운로드와 앱 전체 기능은 클로드 데스크탑 설치와 사용법에, Code 탭과 터미널 중 무엇으로 시작할지는 Desktop Code 탭 vs 터미널 CLI에 정리했습니다.

반대로 앱만 설치했다면 터미널의 claude 명령은 생기지 않습니다. 터미널에서 쓰려면 위 명령으로 CLI를 따로 설치합니다. 예전 버전 데스크톱 앱이 Windows에서 claude 명령을 가로채 앱이 열리는 경우가 있는데 공식 문서는 앱을 최신 버전으로 업데이트하라고 안내합니다.

첫 실행과 로그인

작업할 프로젝트 폴더로 이동해서 실행합니다. Claude Code는 실행한 폴더를 기준으로 파일을 읽고 작업하기 때문에 위치가 중요합니다.

cd ~/my-project
claude

처음이면 브라우저로 로그인합니다. 로그인할 수 있는 계정은 Claude 구독(Pro, Max, Team, Enterprise), Claude Console, Amazon Bedrock·Google Cloud Agent Platform·Microsoft Foundry 같은 클라우드 제공자입니다. Console로 처음 로그인하면 비용 추적용 "Claude Code" 워크스페이스가 자동으로 만들어집니다.

ANTHROPIC_API_KEY 환경 변수가 있으면 브라우저 대신 그 키를 쓸지 한 번 묻습니다. 키 값은 채팅에 붙이거나 저장소에 올리지 않습니다.

첫 질문 예:

이 프로젝트 구조를 설명해 줘

계정을 바꾸려면 세션 안에서 /login, 지금 어떤 인증 방식이 쓰이는지는 /status로 봅니다. 설치 다음에 익힐 조작(권한 모드, CLAUDE.md, 슬래시 명령)은 클로드 코드 사용법에 순서대로 모았습니다.

자주 나는 오류

1. command not found: claude

설치는 했는데 명령어를 못 찾는다면 PATH부터 확인합니다. 네이티브 설치는 ~/.local/bin/claude(Windows는 %USERPROFILE%\.local\bin\claude.exe)에 실행 파일을 둡니다. Mac 기본 셸인 Zsh라면 다음처럼 경로를 추가합니다.

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

대부분의 Linux 기본 셸인 Bash라면 ~/.zshrc 자리에 ~/.bashrc를 씁니다. Windows는 사용자 PATH에 %USERPROFILE%\.local\bin을 추가하고 터미널을 다시 엽니다.

VS Code 확장만 설치했다면 이 오류가 나는 게 정상입니다. 확장은 자기 채팅 패널용 CLI를 확장 폴더 안에 따로 두고 PATH에는 추가하지 않거든요. 터미널에서 claude를 쓰려면 위 설치 명령을 따로 실행합니다.

2. 설치 명령이 < 구문 오류나 403을 냄

syntax error near unexpected token '<', PowerShell에서 HTML 태그가 섞인 파싱 오류, System.Xml.XmlDocument 오류, curl: (22) ... 403은 모두 설치 주소가 스크립트 대신 웹 페이지나 오류를 돌려준 경우입니다. 메시지에 "App unavailable in region"이 보이면 지원 지역이 아닌 곳에서 접속한 것입니다. 지원 지역인데도 403이 나면 회사 프록시나 방화벽이 다운로드를 막고 있을 수 있습니다. 일시적인 문제일 때도 있어서 몇 분 뒤 다시 시도해 보고 Mac은 Homebrew, Windows는 WinGet으로 설치하는 방법도 있습니다.

3. npm EACCES

sudo npm install -g는 공식 문서가 권하지 않습니다. 권한 문제와 보안 위험이 있어서입니다. npm 권한 오류가 나면 네이티브 설치로 바꾸는 편이 낫습니다.

npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash

설치가 두 벌 남아 있으면 버전이 엇갈릴 수 있습니다. Mac·Linux에서는 which -a claude로 claude가 몇 개 잡히는지 확인하고 하나만 남깁니다.

4. Windows에서 Git Bash를 찾을 수 없음

터미널에서 쓰는 중인지, 데스크톱 앱의 Code 탭을 쓰는 중인지부터 봅니다. CLI만 쓴다면 Git 없이 PowerShell 도구로도 동작합니다. "Git for Windows 또는 PowerShell이 필요하다"는 오류는 두 셸을 모두 못 찾았다는 뜻이니 PowerShell이 PATH에 있는지 확인합니다. 데스크톱 앱에서 "Git is required"가 뜨면 워크트리를 쓰는 경우 Git for Windows를 설치하고 아니라면 앱을 업데이트합니다.

5. 로그인 창이 안 열리거나 코드를 붙여 넣을 수 없음

브라우저가 자동으로 열리지 않으면 로그인 화면에서 c를 눌러 로그인 주소를 복사하고 브라우저에 직접 붙여 넣습니다. WSL2·SSH·컨테이너에서는 로그인 후 브라우저가 코드를 보여 주는데 이 코드를 터미널의 Paste code here if prompted 자리에 붙여 넣으면 됩니다. 붙여 넣기가 먹히지 않으면 claude auth login으로 다시 로그인합니다.

유료 구독이 있는데 "This organization has been disabled" 오류가 난다면 예전에 설정해 둔 ANTHROPIC_API_KEY가 구독 로그인보다 먼저 쓰이고 있는 경우가 많습니다. 셸 설정 파일에서 해당 줄을 지우고 다시 실행합니다. /status로 지금 쓰는 인증 방식을 확인할 수 있습니다. 원인이 분명하지 않을 때는 /logout으로 로그아웃하고 Claude Code를 닫았다가 다시 claude로 로그인하면 대부분 해결된다고 공식 문서는 안내합니다.

업데이트와 삭제

네이티브 설치는 실행 중 백그라운드에서 새 버전을 받고 다음 실행부터 적용됩니다. 채널은 latest(기본)와 stable(보통 일주일쯤 늦고 큰 문제가 있던 버전은 건너뜀)입니다. /config의 Auto-update channel에서 바꿀 수 있고 바로 업데이트하려면 claude update입니다.

Homebrew와 WinGet은 기본이 수동 업데이트입니다. Homebrew는 설치한 cask 이름에 맞춰 실행합니다(claude-code@latest로 설치했다면 그 이름으로).

brew upgrade claude-code

winget upgrade Anthropic.ClaudeCode

CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1을 설정하면 Claude Code가 Homebrew/WinGet 업그레이드를 대신 실행합니다. apt/dnf/apk는 관리자 권한이 필요해서 계속 수동입니다.

npm 설치는 npm install -g @anthropic-ai/claude-code@latest로 올립니다. npm update -g는 처음 설치한 버전 범위를 따르기 때문에 최신 버전으로 안 올라갈 수 있습니다.

삭제는 설치 방식별로 다릅니다. 네이티브는 Mac·Linux·WSL에서 ~/.local/bin/claude와 ~/.local/share/claude, Windows에서 %USERPROFILE%\.local\bin\claude.exe와 %USERPROFILE%\.local\share\claude를 지웁니다. Homebrew는 brew uninstall --cask claude-code(latest로 설치했다면 claude-code@latest), WinGet은 winget uninstall Anthropic.ClaudeCode, npm은 npm uninstall -g @anthropic-ai/claude-code입니다.

설정까지 지우려면 ~/.claude 폴더와 ~/.claude.json 파일을 삭제합니다. 설정·MCP 서버 구성·세션 기록이 모두 사라집니다. VS Code 확장, JetBrains 플러그인, 데스크톱 앱이 남아 있으면 ~/.claude가 다시 생기니 그쪽을 먼저 지웁니다.

자주 묻는 질문

무료로 쓸 수 있나요?

2026년 10월 16일 기준 공식 문서와 요금 페이지 모두 무료 플랜에는 Claude Code가 없다고 안내합니다. Pro·Max·Team·Enterprise 구독 또는 Console/클라우드 제공자 계정이 필요합니다. 플랜 구성은 바뀔 수 있으니 요금 페이지를 확인합니다.

Node.js를 꼭 설치해야 하나요?

네이티브·Homebrew·WinGet·Linux 패키지·데스크톱 앱은 필요 없습니다. npm 방식만 Node.js가 필요합니다.

관리자 권한으로 PowerShell을 열어야 하나요?

아닙니다. 공식 문서는 네이티브 Windows 설치에 관리자 권한이 필요 없다고 안내합니다. 일반 PowerShell 창에서 실행하면 사용자 폴더(%USERPROFILE%\.local\bin)에 설치됩니다.

VS Code나 Cursor 안에서도 쓸 수 있나요?

가능합니다. 확장 마켓플레이스에서 Claude Code 확장을 설치하면 되고 VS Code는 1.94.0 이상이 필요합니다. Cursor는 VS Code 기반이라 같은 확장을 쓰고 공식 문서에 Cursor용 설치 링크도 따로 있습니다. 다만 확장만 설치하면 터미널의 claude 명령은 생기지 않습니다.

회사 컴퓨터라 브라우저 로그인이 막혀 있습니다

Console API 키를 환경 변수로 넣는 방법이 있습니다. 설치 단계부터 막힌다면 IT팀에 프록시 주소를 받아 HTTPS_PROXY를 설정한 뒤 설치합니다. 회사의 도구 사용 정책을 먼저 확인하고 키 값은 채팅이나 저장소에 올리지 않습니다.

다음 단계

• 클로드 코드 사용법: 첫 세션부터 권한·CLAUDE.md·MCP까지
• Windows에서 Claude Code 설치가 안 될 때
• 클로드 데스크탑 설치와 사용법
• 클로드 요금제 비교
• 읽는 순서를 한눈에 보려면 Claude Code 시작하기, 강의 안내는 홈과 수강료

출처와 확인 (2026-10-16)

• Claude Code Advanced setup(설치·요구 사항·업데이트·삭제·서명 확인, claude --version 출력 예시 2.1.211 (Claude Code))
• Terminal guide for new users(irm·iex 설명, Win+X, 설치 완료 메시지)
• 설치·로그인 문제 해결(오류 메시지별 해결, irm만 실행했을 때 동작, 데스크톱 앱의 claude 명령 충돌)
• Quickstart
• Authentication
• Desktop 빠른 시작
• Desktop (Git 요구 조건)
• VS Code 확장
• Microsoft Learn: Invoke-RestMethod(별칭 irm)
• Microsoft Learn: Invoke-Expression(별칭 iex, 주의 사항)
• Microsoft Learn: SignatureStatus(Valid·NotSigned·HashMismatch 뜻)
• Sandboxing(지원 플랫폼)
• Anthropic 지원 지역
• claude.com/pricing