← 목록으로AI WORKFLOW

설치 전에 깔아야 할 프로그램은 0개입니다 — 비개발자를 위한 클로드 코드 설치, 명령어 한 줄

seungjin15 min2026-09-20
설치 전에 깔아야 할 프로그램은 0개입니다 — 비개발자를 위한 클로드 코드 설치, 명령어 한 줄

결론부터 말씀드립니다. Claude Code(클로드 코드) 설치는 명령어 한 줄이면 끝나고 그 전에 따로 깔아야 하는 프로그램은 하나도 없습니다.

맥이라면 이 줄입니다.

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

윈도우라면 이 줄입니다.

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

이 글을 찾아오신 분들이 진짜로 막히는 지점은 명령어 자체가 아니라 이 줄을 어디에 쳐야 하는지입니다. 대부분의 설치 가이드가 “터미널을 여세요”로 시작하는데, 터미널을 한 번도 열어본 적 없는 사람에게는 그 한 문장이 벽입니다.

그래서 이 글은 그 한 줄 앞에서 시작합니다. 검은 창이 무엇이고 어디서 여는지, 무엇이 나오면 성공인지까지 다룹니다.

2026년 9월 기준입니다. 명령어와 오류 메시지는 공식 문서를 기준으로 삼았고 실행 결과는 필자의 맥(Claude Code v2.1.278)에서 직접 확인했습니다.

먼저 확인할 것 두 가지

설치를 시작하기 전에 확인할 게 두 가지 있습니다. 여기서 걸리면 명령어를 백 번 쳐도 안 됩니다.

1. 내 컴퓨터가 되는지

공식 문서가 명시한 최소 사양입니다.

항목 요구 사양
맥 macOS 13.0 이상
윈도우 Windows 10 1809 이상 (또는 Windows Server 2019 이상)
리눅스 Ubuntu 20.04+ / Debian 10+ / Alpine 3.19+
메모리 4GB 이상
프로세서 x64 또는 ARM64

맥 버전은 화면 왼쪽 위 사과 메뉴 → ’이 Mac에 관하여’에서 확인합니다. macOS 13은 2022년 10월에 나온 버전입니다.

이 표에서 눈여겨볼 건 없는 항목입니다. Python도 Node.js도 Git도 요구 사양에 없습니다.

2. 내 계정으로 되는지

이쪽이 실제로 더 많이 걸립니다. 무료 claude.ai 계정으로는 Claude Code를 쓸 수 없습니다. 공식 문서에 이렇게 적혀 있습니다.

The free claude.ai plan does not include Claude Code access.

필요한 것은 Pro, Max, Team, Enterprise 구독 중 하나, 또는 Claude Console 계정(API 크레딧 선결제)입니다. 설치는 무료 계정으로도 되지만 로그인 단계에서 막힙니다. 다 깔아놓고 나중에 알면 시간만 버리니 지금 확인해 두세요.

검은 창을 여는 법

터미널은 명령어를 글자로 입력하는 창입니다. 마우스로 클릭할 게 없고 타이핑한 다음 엔터를 치면 컴퓨터가 그 줄을 실행합니다. 그게 전부입니다.

맥에서 여는 법

  1. ⌘ + 스페이스를 누릅니다. 화면 가운데 검색창이 뜹니다.
  2. 터미널이라고 칩니다. (영문 환경이면 Terminal)
  3. 엔터를 누릅니다.

흰색이나 검은색 창이 하나 뜨고 커서가 깜빡이면, 그게 터미널입니다.

윈도우에서 여는 법

  1. Win + X를 누릅니다. 작업 표시줄 근처에 메뉴가 뜹니다.
  2. 목록에서 Windows PowerShell 또는 터미널을 클릭합니다.

시작 메뉴에서 PowerShell을 검색해도 됩니다. 다만 검색 결과에 Windows PowerShell (x86)이 같이 뜨는데, 이건 누르면 안 됩니다. 64비트 컴퓨터에서 x86 쪽을 열면 설치할 때 Claude Code does not support 32-bit Windows라는 오류가 납니다. 이름 뒤에 (x86)이 안 붙은 항목을 여세요.

윈도우는 검은 창이 두 종류입니다

맥 사용자는 이 단락을 건너뛰셔도 좋습니다. 윈도우 독자의 절반이 여기서 갈립니다.

윈도우에는 명령어를 입력하는 프로그램이 PowerShell과 CMD 두 가지 있습니다. 생긴 게 거의 똑같은데 쓰는 명령어가 다릅니다. 지금 내가 어느 쪽에 있는지는 커서 앞에 붙은 글자로 구분합니다.

PS C:\Users\내이름>     ← PS가 붙어 있으면 PowerShell
C:\Users\내이름>        ← PS가 없으면 CMD

잘못 열었을 때 나오는 오류 메시지도 정해져 있습니다.

나온 오류 실제 상황 할 일
'irm' is not recognized as an internal or external command CMD인데 PowerShell 명령을 침 PowerShell을 열거나 아래 CMD용 명령어 사용
The token '&&' is not a valid statement separator PowerShell인데 CMD 명령을 침 위의 irm 명령어 사용

CMD에서 그대로 설치하고 싶다면 이 명령어를 씁니다.

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

설치: 명령어 한 줄

창을 열었으면 이제 한 줄입니다. 타이핑하지 말고 복사해서 붙여넣으세요. 오타 하나가 그대로 오류가 됩니다.

맥·리눅스·WSL 환경 (붙여넣기는 ⌘ + V):

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

윈도우 PowerShell (붙여넣기는 Ctrl + V 또는 마우스 오른쪽 클릭):

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

붙여넣고 엔터를 치면 글자가 주르륵 올라갑니다. 다 끝나면 Claude Code successfully installed!가 나옵니다.

제대로 깔렸는지 확인하기

설치가 끝났다는 메시지를 못 봤거나 못 믿겠으면 이 명령어를 칩니다.

claude --version

필자의 맥에서는 이렇게 나옵니다.

2.1.278 (Claude Code)

버전 숫자 뒤에 (Claude Code)가 붙어야 제대로 설치된 것입니다. 숫자는 사람마다 다른데, 매주 새 버전이 나오기 때문입니다.

더 자세히 보고 싶으면 이 명령어도 있습니다.

claude doctor

Claude Code를 실행하지 않고 설치 상태와 설정 문제만 점검해서 보여줍니다. 나중에 뭔가 이상할 때 제일 먼저 쳐볼 명령어입니다.

필요한 것과 필요 없는 것

국내 설치 가이드 중에는 Node.js를 먼저 설치하게 하거나, VS Code에 Python 확장을 깔게 하는 글이 있습니다. 따라 하다 보면 설치 전에 프로그램을 세 개쯤 깔게 됩니다.

틀렸다기보다 기준이 다른 경로입니다. 예전에는 Claude Code를 npm(개발자들이 프로그램을 설치할 때 쓰는 도구)으로 설치했고, 그 경로는 Node.js(자바스크립트를 실행해 주는 프로그램)가 필요합니다. 지금 공식 문서가 권장하는 네이티브 설치는 그쪽이 아닙니다.

필요한가 설명
터미널 (PowerShell) 필요 윈도우·맥 모두 기본 설치돼 있습니다
Pro·Max·Team·Enterprise 또는 Console 계정 필요 무료 계정은 사용 불가
Python 필요 없음 네이티브·npm 어느 경로에서도 쓰지 않습니다
Node.js 필요 없음 npm 설치를 고집할 때만 필요(v2.1.198부터 Node.js 22 이상)
Git for Windows 선택 없으면 PowerShell이 셸(명령어를 받아 실행하는 프로그램)로 쓰입니다
WSL(윈도우 안에서 리눅스를 돌리는 기능) 필요 없음 윈도우에서 그냥 설치됩니다

사전에 깔아야 할 프로그램은 0개입니다. 제목의 숫자는 여기서 나왔습니다.

설치 방식 4가지 — 진짜 차이는 자동 업데이트

방법이 여러 개라 헷갈리지만 실제로 갈리는 건 하나, 알아서 최신 버전이 되느냐입니다.

방식 명령어 자동 업데이트
네이티브 (권장) 위의 한 줄 됩니다
Homebrew (맥) brew install --cask claude-code 안 됩니다
WinGet (윈도우) winget install Anthropic.ClaudeCode 안 됩니다
npm npm install -g @anthropic-ai/claude-code 조건부

Homebrew나 WinGet으로 깔면 직접 올려야 합니다.

brew upgrade claude-code          # 맥
winget upgrade Anthropic.ClaudeCode   # 윈도우

Homebrew를 쓸 거라면 cask가 두 개라는 점도 알아두세요. claude-code는 안정 채널이라 최신보다 일주일 정도 뒤처지는 대신 큰 문제가 있는 버전을 건너뜁니다. claude-code@latest는 나오는 즉시 받습니다.

처음 설치하신다면 네이티브 한 줄을 권합니다. 업데이트를 신경 쓸 일이 없습니다.

로그인

설치가 끝났으면 실행합니다.

claude

처음 실행하면 로그인하라고 나옵니다. 안내를 따라가면 브라우저가 열리고 거기서 로그인하면 터미널로 돌아옵니다. 한 번 하면 다음부터는 안 물어봅니다.

계정을 바꾸고 싶으면 Claude Code가 실행된 상태에서 /login을 칩니다.

여기까지 왔으면 설치는 끝났습니다. 이제 한글로 질문하면 답이 옵니다. 몇 가지만 알아두세요.

  • 터미널 안에서는 클릭이 안 됩니다. 방향키로 움직입니다.
  • Claude가 뭔가 하는 중에 멈추고 싶으면 Esc입니다.
  • 나가려면 /exit을 치거나 Ctrl + D를 두 번 누릅니다.
  • 뭘 할 수 있는지 모르겠으면 /help입니다.

여기서 막힙니다

설치가 한 번에 되면 좋겠지만 안 될 때가 있습니다. 공식 문제 해결 문서의 오류 목록에서 맨 첫 줄에 있는 오류부터 순서대로 정리했습니다. 그만큼 자주 납니다.

1. command not found: claude / 'claude' is not recognized

가장 흔합니다. 설치는 됐는데 컴퓨터가 claude라는 파일이 어디 있는지 모르는 상태라, 위치를 직접 알려주면 해결됩니다. 필자의 맥에서는 ~/.local/bin/claude에 들어가 있었습니다.

맥(zsh):

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

윈도우 PowerShell:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

그다음 창을 닫고 새로 여세요. 기존 창에서는 반영이 안 됩니다.

2. syntax error near unexpected token '<' 또는 403

명령어가 설치 스크립트 대신 웹페이지를 받아온 경우입니다. 한 번 더 실행해 본 뒤 계속 같으면 Homebrew로 설치합니다. 받아온 페이지에 App unavailable in region이라고 적혀 있다면 해당 국가에서 서비스되지 않는다는 뜻이라 명령어 문제가 아닙니다.

3. dyld: cannot load 또는 built for Mac OS X 13.0

맥 버전이 낮습니다. 사과 메뉴 → ’이 Mac에 관하여’에서 확인하고 13.0 미만이면 macOS를 업데이트합니다.

4. Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

셸을 하나도 못 찾은 경우입니다. powershell.exe가 C:\Windows\System32\WindowsPowerShell\v1.0\ 경로에 있는지 확인하거나, Git for Windows를 설치합니다.

여기 없는 오류는 공식 문제 해결 문서에 오류 메시지별 표로 정리돼 있습니다. 터미널에 뜬 문장을 그대로 찾으면 됩니다.

터미널이 답이 아닐 때도 있습니다

지금까지 터미널 기준으로 썼지만, 터미널을 안 쓰는 방법도 있습니다.

Claude Code에는 데스크톱 앱이 있습니다. 공식 문서도 설치 안내 첫머리에 이 문장을 달아 뒀습니다.

Don’t want to use the terminal? The Claude Code desktop app lets you skip the terminal entirely. (터미널을 쓰고 싶지 않으신가요? 데스크톱 앱을 쓰면 터미널을 통째로 건너뛸 수 있습니다.)

맥·윈도우·리눅스 모두 지원하고, VS Code 확장과 JetBrains 플러그인, 웹(claude.ai/code)까지 있습니다.

그런데도 이 시리즈가 터미널로 가는 건 이어지는 글들이 전부 터미널 화면을 기준으로 쓰이기 때문입니다. CLAUDE.md, 스킬, 훅, 권한 모드는 데스크톱 앱과 VS Code에서도 쓸 수 있지만, 설명하고 따라 하기에는 터미널 쪽이 가장 깔끔합니다. 지금 검은 창에 10분 투자하면 앞으로 읽을 글이 그대로 통합니다.

“일단 뭔지만 보고 싶다”면 데스크톱 앱이 빠릅니다. “제대로 쓸 생각”이라면 터미널을 권합니다.

설치 전에 Cursor 같은 다른 도구와 저울질 중이시라면 Claude Code가 있는데 Cursor를 또 결제해야 할까를 먼저 읽어보셔도 좋습니다.

다음 편

창은 열었고 설치도 됐습니다. 그런데 커서만 깜빡이는 화면 앞에서 또 막힙니다. 뭘 쳐야 하는지가 다음 문제입니다.

그 전에 알아둘 게 있습니다. Claude Code는 지금 열려 있는 폴더를 기준으로 움직입니다. 엉뚱한 폴더에서 실행하면 엉뚱한 파일을 읽습니다. 다음 편은 그 폴더와 경로 이야기입니다.