설치 5분, 에러 해결 30분 — Claude Code 실습 환경 만들기

설치는 5분, 그런데 다들 여기서 막힌다

Claude Code 설치 명령어 자체는 한 줄입니다. 그런데 실제로 처음 설치해본 사람 중 상당수가 이 한 줄을 실행한 직후 나오는 에러 메시지 앞에서 멈춥니다. 이 글은 설치 절차를 순서대로 안내하면서, 그 과정에서 실제로 자주 나오는 에러 세 가지를 미리 짚어둡니다.

시작 전에 확인할 것

Claude Code는 무료 플랜에는 포함되지 않습니다. Pro($20/월) 이상 구독이나 API 계정이 필요합니다. Cursor 같은 다른 AI 코딩 도구로 실습을 대체할 수도 있지만, 이 글은 Claude Code 기준으로 설명합니다.

필요한 건 이게 전부입니다.

• 터미널을 쓸 수 있는 컴퓨터 (macOS / Windows / Linux)
• Claude 계정
• 인터넷 연결

별도 프로그램을 미리 설치할 필요는 없습니다.

설치 단계별로 따라가기

1단계 — 터미널 열기. macOS는 Cmd + Space로 스포트라이트를 열고 “터미널”을 검색합니다. Windows는 반드시 PowerShell을 써야 합니다. CMD(명령 프롬프트)에서는 설치 스크립트가 작동하지 않습니다.

2단계 — 설치 명령어 실행.

# macOS / Linux
curl -fsSL claude.ai/install.sh | bash

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

3단계 — 설치 확인. claude --version을 입력해서 버전이 표시되는지 확인합니다.

4단계 — 로그인. claude 명령을 입력하면 브라우저가 열리면서 인증 절차가 진행됩니다.

5단계 — 첫 실행 테스트. 아무 폴더나 만들고 그 안에서 Claude Code를 실행한 뒤, “간단한 텍스트 파일 하나 만들어줘” 같은 요청을 해봅니다. 파일이 실제로 생성되면 정상 작동하는 겁니다.

실제로 여기서 막힌다 — 자주 나는 에러 3가지

에러 1. “Permission denied”가 뜬다. 설치 스크립트를 실행했는데 권한 오류가 납니다. 이때 sudo를 붙여서 강제로 실행하고 싶은 유혹이 듭니다. 여기서 sudo를 쓰면 안 됩니다. 대신 터미널을 완전히 종료했다가 다시 여는 것부터 시도하세요. 대부분 이걸로 해결됩니다.

에러 2. 설치는 됐다는데 claude 명령어를 못 찾는다. “command not found: claude” 같은 메시지가 나온다면, 설치는 성공했지만 터미널이 아직 새로 추가된 명령어 경로를 인식하지 못한 상태입니다. 터미널 창을 완전히 닫고 새로 열면 대부분 해결됩니다.

에러 3. Windows에서 스크립트가 아예 안 먹힌다. CMD에 명령어를 입력했는데 아무 반응이 없거나 오류가 난다면, PowerShell이 아니라 CMD를 쓰고 있었을 가능성이 높습니다. 작업 표시줄 검색에서 “PowerShell”을 직접 검색해서 열었는지 확인하세요.

그 외. 로그인 창이 자동으로 뜨지 않는다면, 터미널에 표시된 인증 링크를 직접 복사해서 브라우저 주소창에 붙여넣으면 됩니다.

문제 해결 요약표

첫 실행이 성공했다면

폴더 하나를 만들고 그 안에서 Claude Code가 실제로 파일을 생성하는 걸 확인했다면 환경 설정은 끝났습니다. 여기서부터는 이 폴더를 실습 프로젝트의 시작점으로 삼아, 다음 실습 가이드로 넘어가면 됩니다.

자주 묻는 질문

Q. Mac과 Windows 중 어디서 실습하는 게 더 편한가요? 큰 차이는 없습니다. 다만 Windows에서는 반드시 PowerShell을 쓰고 CMD를 쓰지 않는다는 점만 기억하면, 설치 과정에서의 차이는 거의 없습니다.

Q. 회사 노트북처럼 관리자 권한이 제한된 환경에서도 설치되나요? 설치 스크립트 자체는 사용자 권한만으로 동작하도록 설계되어 있지만, 회사 보안 정책에 따라 스크립트 실행 자체가 막혀 있을 수 있습니다. 이 경우 IT 부서에 방화벽·실행 정책 예외를 문의해야 합니다.

Q. 설치 후 업데이트는 어떻게 하나요? 동일한 설치 명령어를 다시 실행하면 최신 버전으로 갱신됩니다.