설치 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”을 직접 검색해서 열었는지 확인하세요.

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

문제 해결 요약표

증상	원인	해결
Permission denied	설치 스크립트 권한 문제	sudo 쓰지 말고 터미널 재시작
명령어 미인식	터미널이 새 경로를 아직 못 읽음	터미널 완전 종료 후 재실행
PowerShell 스크립트 실패	CMD에서 실행한 경우	PowerShell을 직접 검색해서 실행
로그인 창 안 뜸	브라우저 자동 실행 실패	터미널의 인증 링크 직접 복사·붙여넣기

첫 실행이 성공했다면

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

자주 묻는 질문

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

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

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

설치 후 처음 해볼 미니 실습

설치가 끝났다면, 바로 복잡한 프로젝트에 투입하기보다 작은 작업으로 감각을 익히는 게 좋습니다.

빈 폴더 하나 만들고 진입: mkdir claude-practice && cd claude-practice
Claude Code 실행: 터미널에서 claude만 입력하면 대화형 세션이 시작됩니다.
파일 생성 요청: “할 일 목록을 관리하는 간단한 Python CLI 스크립트를 만들어줘” 같은 요청을 해봅니다.
결과 실행: Claude Code가 만든 파일을 실제로 실행해서 동작하는지 확인합니다.
수정 요청: “완료된 항목은 체크 표시가 나오게 해줘” 처럼 기존 코드를 수정하는 요청을 이어서 해봅니다.

이 다섯 단계를 거치면 파일 생성 → 실행 → 피드백 기반 수정이라는 Claude Code의 기본 루프를 체감할 수 있습니다. 이후 실제 프로젝트에 투입할 때도 같은 루프를 반복하게 됩니다.

추가로 자주 묻는 질문

Q. 기존 코드베이스가 있는 프로젝트 폴더에서 바로 써도 되나요? 가능합니다. 다만 처음에는 git으로 버전 관리가 되는 프로젝트에서 시작하는 걸 권장합니다. Claude Code가 만든 변경사항을 git diff로 바로 검토하고, 마음에 안 들면 되돌릴 수 있기 때문입니다.

Q. 여러 프로젝트를 오가며 쓰면 설정이 꼬이지 않나요? 설정은 프로젝트 폴더 단위(.claude 디렉터리)로 분리되므로, 폴더를 이동해서 실행하면 해당 프로젝트의 설정만 적용됩니다.

설치 후 바로 확인할 6가지

claude --version으로 설치와 PATH가 정상인지 확인했는가
Windows에서는 PowerShell로 실행했는가 (CMD에서는 설치 스크립트가 동작하지 않음)
로그인 후 구독 또는 API 계정 상태가 사용 가능한지 확인했는가
실습용 빈 폴더를 만들어 그 안에서만 실행하고 있는가
첫 요청(예: 텍스트 파일 만들기)으로 파일 생성 권한이 정상인지 확인했는가
에러가 날 때 메시지 전체를 저장해 두고 있는가 (검색과 질문에 가장 도움이 된다)

추가로 자주 나오는 질문

Q. 설치 후 claude 명령을 못 찾는다고 나옵니다. 대부분 환경 변수(PATH) 문제입니다. 터미널을 완전히 닫았다가 다시 열어 보고, 그래도 안 되면 설치 경로가 PATH에 포함되어 있는지 확인하세요.

Q. 무료 계정으로도 실습할 수 있나요? 글 작성 시점 기준으로 무료 플랜에는 포함되지 않으며 구독이나 API 계정이 필요합니다. 요금 정책은 바뀔 수 있으니 공식 안내를 확인하세요.

Q. 처음 실행할 때 안전하게 시작하는 방법은 무엇인가요? 중요한 코드가 들어 있는 폴더가 아니라 실습 전용 폴더에서 시작하고, 파일 변경을 승인하기 전에 무엇을 바꾸는지 읽어 보세요.