클로드 코드 설치 안됨, 성공했는데 안 되는 경우

claude --version이 2.1.197을 찍었어요.

그날 최신은 2.1.231이었습니다. 44일 전 버전이 깔린 건데, 화면에 뜬 건 added 2 packages in 13s 한 줄이 전부였어요. 경고도 빨간 줄도 없었고요.

같은 명령을 Node 16 컨테이너에서 돌리면 경고가 다섯 줄 뜹니다. 그런데 그쪽에 깔린 건 최신 2.1.231이었어요.

시끄러운 쪽이 멀쩡했고, 조용한 쪽이 6주 뒤처져 있었어요.

환경을 바꿔가며 재현해 보니 이런 자리가 셋이었어요. 셋 다 설치가 끝난 다음에 문제가 남습니다. 실패한 게 아니라서 고칠 생각을 못 하는 자리예요. 설치 명령을 치자마자 command not found: npm이 뜨는 경우라면 이 글이 아니라 Node부터 까는 자리고요.

재현은 2026년 8월 13일에 했어요. 호스트는 macOS 26.5.2, 나머지는 Docker 컨테이너(node:16-slim · node:20-slim · node:22-slim · debian:bookworm-slim)입니다. 그날 @anthropic-ai/claude-code의 최신 버전은 2.1.231이었어요. 아래 출력은 전부 그 환경에서 실제로 받은 값이고, 줄을 줄인 자리는 ...로 표시했습니다. 윈도우는 환경이 없어서 못 봤어요. 여기부터는 맥과 리눅스 얘기입니다.

경고가 뜬 쪽이 최신이었어요

Node 20 컨테이너에서 npm install -g @anthropic-ai/claude-code를 돌린 출력 전부예요. npm 자체 광고 줄만 뺐습니다.

added 2 packages in 13s

Node 16에서는 이렇게 나왔어요.

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '@anthropic-ai/claude-code@2.1.231',
npm WARN EBADENGINE   required: { node: '>=22.0.0' },
npm WARN EBADENGINE   current: { node: 'v16.20.2', npm: '8.19.4' }
npm WARN EBADENGINE }

added 3 packages, and audited 4 packages in 35s

경고가 다섯 줄 뜨고 설치는 성공으로 끝나요. 그런데 이쪽에서 claude --version은 2.1.231을 찍습니다. 조용했던 Node 20 쪽이 2.1.197에 묶인 쪽이에요.

화면이 시끄러운 정도와 실제 문제의 크기가 반대로 붙어 있어요.

왜 낮은 Node에서도 실행이 되나

@anthropic-ai/claude-code는 자바스크립트로 짠 프로그램이 아니에요. 패키지 안을 열어보면 이렇게 돼 있습니다.

"bin": { "claude": "bin/claude.exe" },
"engines": { "node": ">=22.0.0" },
"optionalDependencies": {
  "@anthropic-ai/claude-code-darwin-arm64": "2.1.231", ...
}

npm으로 받는 건 껍데기고, 실제로 도는 건 운영체제별로 따로 받아지는 네이티브 바이너리예요. 그래서 Node 버전은 실행을 막지 않습니다. Node 16에 최신이 깔리고도 버전이 찍힌 이유가 이겁니다.

공식 문서도 같은 말을 하는데, 한 대목이 제가 본 것과 어긋나요.

On an older Node.js version, npm prints an EBADENGINE warning during install rather than failing; …

낮은 Node에서는 경고가 뜬다고 적혀 있죠. Node 16은 그랬어요. 그런데 Node 20은 경고를 안 냅니다. 문장이 틀렸다기보다, 낮은 Node 안에서도 결과가 갈리는 구간이 있는 거예요. 그 경계가 어디고 왜 갈리는지가 다음 대목입니다.

44일 차이가 어디서 생기나

이 패키지는 중간에 요구 Node 버전을 올렸어요.

npm의 버전 선택기 문서에 규칙이 그대로 적혀 있어요. “Prioritize versions that have a satisfied engines requirement over those that do not.” 조건을 만족하는 버전이 있으면 번호가 더 높은 쪽보다 그쪽을 먼저 고른다는 뜻입니다. 번호 순서는 그 아래 항목이고요.

여기에 위 표를 대보면 둘이 갈립니다.

• Node 20: >=18.0.0을 만족하는 2.1.197이 있어요. 그래서 그걸 고릅니다. 조건을 만족했으니 경고할 일도 없고요
• Node 16: 만족하는 버전이 하나도 없어요. 가장 낮은 것도 Node 18을 요구하니까요. 고를 게 없으니 그냥 최신을 깔고 경고만 남깁니다

npm 공식 문서는 engines를 두고 engine-strict를 켜지 않는 한 “advisory only and will only produce warnings”라고 설명해요. 설치를 막지는 않는다는 말이지, 버전 선택에 관여하지 않는다는 말이 아닙니다. 저는 이 두 문장 사이가 이번 건의 전부라고 봐요.

무엇이 다른지는 두 버전 사이에 뭐가 들어갔느냐에 달려 있어서 여기서는 못 적어요. 확실한 건 간격뿐입니다. 설치도 됐고 버전도 찍히는데 44일치 릴리스만큼 뒤에 있는 상태고, 그래서 설치 문제로는 안 보입니다.

나가는 길은 Node를 올리는 쪽입니다. nodejs.org에서 LTS 버튼을 눌러 받아 설치하고, 터미널을 새로 연 다음 node -v가 22 이상인지 확인해요. 그다음 npm install -g @anthropic-ai/claude-code를 한 번 더 돌립니다. Node만 올리고 끝내면 안 돼요.

기다리면 알아서 최신이 되지 않을까 싶어 이것도 재현해 봤어요. Node 20에 2.1.197을 깔고 클로드 코드를 한 번 띄운 다음 1분 뒤에 다시 보니 버전은 그대로였습니다. 다만 로그인 없이 한 번 본 것이라 여기까지만 말할 수 있어요. 공식 문서는 시작할 때 업데이트를 확인한다고 적어두고 있고, 자동 갱신이 도는 조건은 이번에 못 봤습니다. 확실한 쪽은 직접 다시 설치하는 겁니다.

sudo로 깔면 그 버전에 묶여요

npm의 전역 설치 위치가 /usr/local로 잡혀 있으면, 일반 사용자 권한으로 설치를 걸 때 막힙니다. 아래는 컨테이너에 일반 사용자로 들어가 받은 값이에요. 전역 위치가 홈 폴더 아래로 잡히는 방식(nvm 같은 것)으로 Node를 깔았다면 이 화면은 안 봅니다.

npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/@anthropic-ai
npm error errno -13
npm error Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@anthropic-ai'
...
npm error permissions of the file and its containing directories, or try running
npm error the command again as root/Administrator.

마지막 두 줄이 함정이에요. npm이 root로 다시 해보라고 권합니다. 실제로 root 권한으로 깔면 설치는 됩니다.

그렇게 깔아둔 컨테이너에 일반 사용자로 들어가 claude doctor를 돌린 결과예요.

Running: npm-global (2.1.231)
Path: /usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude.exe
Auto-updates: enabled
...
1 warning found
- Can't auto-update: npm global folder isn't writable
  Fix: Run claude install to switch to the native installer (no sudo) ...

한 화면 안에서 Auto-updates: enabled와 Can't auto-update가 같이 찍혀요. 자동 갱신이 켜져 있다고 적혀 있지만 실제로는 막혀 있고, 고치기 전까지는 깔린 그 버전에 머뭅니다.

빠져나오는 길은 같은 출력의 Fix: 줄이 안내해요. claude install을 치라고 합니다. 이건 제가 돌려보지 않았어요. 공식 문제 해결 문서는 권한 오류에 대해 네이티브 설치 스크립트를 쓰라고 안내하고요. 어느 쪽이든 자리 잡는 폴더가 ~/.local/bin인데, 그게 바로 다음 자리에서 문제가 되는 그 폴더예요.

애초에 sudo를 쓰지 말라는 건 공식 문서에도 경고 상자로 붙어 있어요. “Do NOT use sudo npm install -g.” 그런데 눈앞에 뜬 npm 메시지는 그걸 모릅니다. npm의 안내는 어떤 패키지에나 나가는 일반 문구고, 이 패키지 사정까지 알고 쓴 게 아니에요.

같은 sudo를 앤트로픽 공식 설치 스크립트는 아예 거부해요. SUDO_USER를 세팅하고 돌린 결과입니다.

Error: do not run this installer with sudo.

Claude Code installs into your home directory and does not need root access.
With sudo, the installation would go into root's home directory instead of
yours, and the 'claude' command would not work from your own shell.
...

npm의 에러 메시지와 공식 설치 스크립트가 정반대를 말하고 있어요. 한쪽은 root로 하라 하고, 한쪽은 root로 하지 말라 합니다. 그런데 공식 문서의 경고는 찾아 들어가야 보이고, npm의 안내는 막힌 그 화면에 떠 있어요.

설치 성공 다음의 command not found

세 번째 자리는 조금 다릅니다. 공식 설치 스크립트를 일반 사용자로 돌리면 성공 표시와 경고가 같이 나와요.

✔ Claude Code successfully installed!

  Version: 2.1.231
  Location: ~/.local/bin/claude
...
⚠ Setup notes:
  ● Native installation exists but ~/.local/bin is not in your PATH. Run:

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

✅ Installation complete!

초록 체크가 위아래로 두 개, 경고는 가운데 한 줄이에요. 그대로 같은 창에서 치면 이렇게 됩니다.

$ claude --version
bash: line 1: claude: command not found

파일은 있어요. ~/.local/bin/claude가 ~/.local/share/claude/versions/2.1.231을 가리키는 링크로 멀쩡히 걸려 있습니다. 명령만 없는 거예요.

맥에서 이게 왜 남느냐면, macOS 기본 경로 목록에 ~/.local/bin이 없기 때문이에요. /etc/paths에는 여섯 줄이 들어 있는데 그 안에 없습니다. 반면 데비안은 .profile이 그 폴더를 자동으로 넣어줘서 새 창만 열면 그냥 됐어요. 되는 사람은 자기가 왜 되는지 모릅니다. 그래서 “저는 그냥 되던데요”라는 답이 여기서는 힘이 없어요.

고치는 건 위 경고가 알려준 그 한 줄인데, 맥이라면 파일 이름이 달라요. 저 출력은 리눅스 컨테이너에서 받은 것이라 .bashrc로 나왔고, 맥의 기본 셸은 zsh입니다. 공식 문제 해결 문서도 맥은 .zshrc로 안내하고요. 터미널에 이걸 붙여넣고 창을 새로 열면 돼요.

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

새 창에서 claude --version이 버전 번호를 찍으면 된 거예요. 제 맥에서 클로드 코드가 도는 것도 .zshrc 121번째 줄에 저 한 줄이 들어 있어서인데, 누가 언제 넣었는지는 저도 기억이 없어요. 확실한 건 그 줄이 있어서 돈다는 것뿐입니다.

공식 스크립트로 깔면 두 자리는 사라져요

지금 새로 깐다면 저도 curl -fsSL https://claude.ai/install.sh | bash 쪽을 씁니다. sudo 문제도 버전 고정 문제도 여기서는 안 생기니까요.

다만 그걸로 이 글이 없어지지는 않아요. 방금 본 세 번째 자리는 공식 스크립트로 깔아도 그대로 걸리고, 앞의 두 자리는 이미 npm으로 깔아둔 사람에게 그대로 남아 있으니까요. 지금 안 되는 걸 고치려고 검색한 사람에게 “처음부터 다른 방법으로 까세요”는 절반짜리 답이에요.

진짜 문제는 도구 선택이 아니라 확인이에요. 셋 다 설치가 성공으로 끝났다는 건, 안 물어보면 자기가 어느 경우인지 모른다는 뜻입니다.

그래서 확인은 두 줄이면 됩니다.

claude --version
claude doctor

첫 줄에서 나온 번호를 npm 페이지의 최신 버전과 눈으로 대조해요. 몇 주씩 벌어져 있으면 Node를 올리고 다시 설치하는 경우입니다. 둘째 줄의 Running: 항목은 설치 방식과 버전을 같이 찍어줘요. 제 쪽에서는 npm-global (2.1.231)이었습니다. 자동 업데이트가 막혔는지와 고치는 명령도 같은 화면에 나오고요.

셋이 다 조용한 데는 공통점이 있어요. 설치 도구가 말하는 성공과 내가 기대한 성공이 서로 다릅니다. npm에게 성공은 조건에 맞는 걸 놓았다는 뜻이고, 스크립트에게 성공은 파일을 복사했다는 뜻이에요. 둘 다 자기 기준으로는 정직합니다. “최신 버전이 내 터미널에서 돈다”만 아무도 안 맡고 있는 거예요.

Supabase 로그인 편에서는 실패가 값으로 돌아와 있기라도 했어요. 여기서는 실패한 쪽이 아예 없습니다.

claude --version이 명령을 못 찾으면 세 번째 자리고, 번호를 찍으면 그 번호가 최신인지만 보면 됩니다. 이 한 줄이 남에게 물어볼 때 붙일 수 있는 유일한 물증이기도 해요. “설치가 안 돼요”보다 “2.1.197이 깔렸어요”가 훨씬 빨리 풀립니다.

로그인 화면 다음부터는 이번 재현에 없고, 요금이나 사용량에서 막힌 거라면 무료 한도를 정리한 편이 그 자리예요.