클로드 코드 설치 방법: Mac·Windows 명령어와 막히는 오류

클로드 코드 설치 명령어를 Mac, Windows, Linux별로 정리했다. 무료 계정 제한, PATH 오류, PowerShell과 CMD 혼동까지 2026년 11월 공식 문서로 확인했다.

공유
클로드 코드 설치 방법: Mac·Windows 명령어와 막히는 오류

클로드 코드(Claude Code)는 터미널에 명령어 한 줄을 붙여 넣으면 설치된다. 설치보다 자주 막히는 곳은 그다음이다. 무료 계정으로는 쓸 수 없고, Windows에서는 PowerShell과 CMD의 명령어가 다르다. 아래 내용은 2026년 11월 1일에 Anthropic 공식 설치 문서에서 확인했다.

본문의 "Astra 첨언"은 OpenAI Codex의 GPT-6 Astra가 이 글을 읽고 남긴 말이다. 사람의 사용 경험담이 아니라 코딩 에이전트 관점의 판단이다.

클로드 코드 설치 전에 확인할 조건

  • 운영체제: macOS 13.0 이상, Windows 10 1809 이상 또는 Windows Server 2019 이상, Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상.
  • 하드웨어: RAM 4GB 이상, x64 또는 ARM64 프로세서.
  • 인터넷: 연결이 필요하다.
  • 계정: Pro, Max, Ultra, Team, Enterprise 또는 Console 계정이 필요하다. 무료 claude.ai 플랜에는 Claude Code가 포함되지 않는다.

요금이 고민이라면 클로드 코드 가격 정리를 먼저 보면 된다.

운영체제별 클로드 코드 설치 명령어

공식 문서가 권장하는 방식은 네이티브 설치다. 터미널을 열고 자기 환경에 맞는 줄만 실행한다.

macOS, Linux, WSL

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

Windows PowerShell (프롬프트가 PS C:\로 시작한다)

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

Windows CMD (프롬프트가 PS 없이 C:\로 시작한다)

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

설치 명령은 다운로드 중에 진행 상황을 보여 주지 않는다. 멈춘 것처럼 보여도 끝날 때까지 기다린다.

Alpine Linux는 예외가 있다. 기본 설치에 없는 bash와 curl이 설치 명령에 필요하고, 실행에는 libgcc, libstdc++, ripgrep이 필요하다. 설정에 USE_BUILTIN_RIPGREP=0도 넣어야 한다. 절차는 공식 문서의 Alpine 항목에 있다.

Homebrew, WinGet, npm으로 설치하기

패키지 관리자를 쓰고 싶다면 아래 명령을 쓴다.

brew install --cask claude-code
winget install Anthropic.ClaudeCode
npm install -g @anthropic-ai/claude-code

방식마다 업데이트가 다르다.

  • 네이티브 설치: 백그라운드에서 자동 업데이트된다.
  • Homebrew: 기본으로 자동 업데이트되지 않는다. brew upgrade claude-code를 직접 실행한다. claude-code 캐스크는 안정 채널이라 보통 약 일주일 늦다. 최신판은 claude-code@latest다.
  • WinGet: 기본으로 자동 업데이트되지 않는다. winget upgrade Anthropic.ClaudeCode를 직접 실행한다.
  • npm: Node.js 22 이상이 필요하다. Node.js 18이라고 적힌 글은 현재 공식 문서와 다르다. 공식 문서는 sudo npm install -g를 쓰지 말라고 경고한다. 권한 문제와 보안 위험이 생길 수 있기 때문이다.

Windows 설치는 네이티브와 WSL 중 하나를 고른다

네이티브 Windows는 관리자 권한 없이 설치된다. Git for Windows는 선택 사항이지만 공식 문서가 권장한다. 필수라고 적힌 글도 있는데, 2026년 11월 1일 공식 문서에서는 필수가 아니다. 있으면 Claude Code가 Git Bash로 Bash 도구를 쓰고, 없으면 PowerShell로 명령을 실행한다.

명령을 격리해 실행하는 샌드박스 기능이 필요하면 WSL 2로 간다. 네이티브 Windows와 WSL 1은 샌드박스를 지원하지 않는다. WSL에 설치했다면 claude도 PowerShell이 아니라 WSL 터미널 안에서 실행해야 한다.

Astra 첨언. 에이전트를 실행할 환경은 프로젝트의 빌드와 테스트가 이미 돌아가는 쪽에 맞추는 편이 낫다. 환경을 함께 바꾸면 코드 문제와 개발 환경 문제를 한 번에 추적해야 한다.

설치됐는지 확인하기

새 터미널 창을 열고 버전을 확인한다.

claude --version

버전 번호 뒤에 (Claude Code)가 붙어 나오면 설치된 것이다. 더 자세히 보려면 claude doctor를 실행한다. 세션을 시작하지 않고 설치 상태와 설정 파일 오류를 읽기 전용으로 보여 준다.

Astra 첨언. 설치 확인과 프로젝트 실행 확인은 따로 한다. 첫 수정 전에 프로젝트의 기존 테스트 명령을 실행해 결과를 남겨 두면, 나중에 생긴 실패가 에이전트의 변경 때문인지 구분하기 쉽다.

첫 실행과 로그인

작업할 프로젝트 폴더에서 실행한다.

cd 프로젝트_폴더
claude

처음 실행하면 브라우저가 열리고 로그인을 안내한다. 로그인 정보는 저장되므로 다음부터는 다시 묻지 않는다. 다른 계정으로 바꿀 때는 실행 중인 세션에서 /login을 입력한다.

구독자는 환경 변수 하나를 조심해야 한다. ANTHROPIC_API_KEY가 설정된 상태에서 Claude Code가 묻는 사용 여부를 승인하면 구독 대신 그 API 키를 쓴다. 그러면 플랜에 포함된 사용량이 아니라 API 요금이 나간다.

자주 만나는 오류

화면에 나온 말뜻할 일
command not found 또는 claude를 인식하지 못함설치 폴더가 PATH에 아직 없다새 터미널을 연다. 그래도 안 되면 공식 문제 해결 문서의 Fix your PATH를 따른다
The token '&&' is not a valid statement separatorCMD용 명령을 PowerShell에서 실행했다PowerShell용 명령을 쓴다
'irm' is not recognizedPowerShell용 명령을 CMD에서 실행했다CMD용 명령을 쓴다
syntax error near unexpected token '<' 또는 403설치 명령이 실패했다공식 문제 해결 문서에서 같은 오류를 찾는다

지역 조건도 있다. Claude Code는 Anthropic이 지원하는 국가에서만 쓸 수 있다.

터미널이 낯설다면, 그리고 지우고 싶다면

터미널이 낯설면 데스크톱 앱으로 시작해도 된다. 공식 문서는 macOS, Windows, Linux용 앱을 안내한다. VS Code를 쓴다면 공식 VS Code 확장도 있다.

네이티브 설치를 지우는 명령은 macOS, Linux, WSL 기준으로 아래와 같다.

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

설정까지 지우려면 ~/.claude와 ~/.claude.json도 삭제한다. 이때 설정, MCP 서버 구성, 세션 기록이 함께 사라진다. 필요한 것이 있으면 지우기 전에 복사해 둔다.

설치를 마쳤다면 다음은 클로드 코드 사용법이다.

설치가 끝나면 에이전트가 "완료했다"고 보고하기 시작한다. 내 사이트는 그 보고 뒤에서 100일 넘게 깨져 있었다. 무료로 사건 읽기

더 읽기