리눅스에서 Claude Code 설치 오류 5가지와 해결법

발행 2026.10.23출처 Medium · Nandan Priyadarshi

EACCES, EBADENGINE, 네이티브 바이너리 누락, command not found, 그리고 중복 설치를 Debian 13에서 재현했습니다.

7분 읽기방금 전

표지: 이 글의 native-installer 테스트에서 나온 실제 오류의 일부입니다. 이미지 제공: 작성자.

AI의 도움을 받아 작성했습니다. 아래의 모든 명령과 출력은 임시 홈 디렉터리와 npm prefix 폴더를 사용한 깨끗한 Debian 13 머신에서 수행한 통제된 테스트에서 나온 것입니다.

Linux에 Claude Code를 설치하는 데 실패했거나, “성공”한 뒤 claude가 실행되지 않았다면, 표시된 메시지가 원인을 가리킵니다. 2026년 10월 9일 우리는 Claude Code 2.1.295로 이 각각의 방식으로 설치를 의도적으로 깨뜨렸고, 정확한 출력을 기록했으며, 각 경우에 대한 해결책도 확인했습니다.

테스트 환경은 Debian 13 x86_64, Node.js 20.19.2, npm 9.2.0, 그리고 Claude Code 2.1.295(npm 패키지 및 native installer)였습니다. 모든 테스트에서 자동 업데이트는 꺼두었습니다.

메시지 찾기

EACCES: permission denied, mkdir '/usr/lib/node_modules': npm이 소유하지 않은 시스템 폴더에 설치하고 있습니다(1장 참조)
npm WARN EBADENGINE ... required: { node: '>=22.0.0' }: 현재 Node 버전이 패키지가 요구하는 버전보다 오래되었습니다(경고일 뿐입니다)(2장 참조)
Error: claude native binary not installed.: npm postinstall 단계가 실행되지 않았습니다(3장 참조)
네이티브 설치 직후 claude: command not found: ~/.local/bin이 PATH에 없습니다(4장 참조)
오류는 없지만 동작이 업데이트한 버전과 맞지 않습니다: PATH에 Claude Code가 두 개 있습니다(5장 참조)

오류를 보기 전에, 중요한 결정 하나가 있습니다. Claude Code 문서는 native installer(curl -fsSL https://claude.ai/install.sh | bash)를 권장하며, 이 설치 방식은 백그라운드에서 자기 자신을 업데이트하고 실행기를 ~/.local/bin/claude에 둡니다. npm 패키지는 Node.js 22 이상이 필요하고, 문서에는 분명히 "Do NOT use sudo npm install -g"라고 적혀 있습니다. 아래 메시지의 대부분은 이 두 경로를 혼동해서 발생합니다.

1. EACCES: permission denied

보이는 내용

코드

12345678910$ NPM_CONFIG_PREFIX=/usr npm install -g @anthropic-ai/claude-code@2.1.295
npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/lib/node_modules
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied, mkdir '/usr/lib/node_modules'
...
npm ERR! If you believe this might be a permissions issue, please double-check the
npm ERR! permissions of the file and its containing directories, or try running
npm ERR! the command again as root/Administrator.

종료 코드는 243이었습니다.

시스템 기본값 /usr를 prefix로 하는 전역 npm 설치가 /usr/lib/node_modules에서 EACCES로 실패했습니다. 테스트 스크립트가 npm 출력 일부를 필터링했기 때문에 힌트가 잘려 있습니다(Node.js 20.19.2, npm 9.2.0, Debian 13). 이미지 제공: 작성자.

원인. 전역 prefix가 시스템 기본값 /usr로 설정되어 있으면 일반 사용자는 /usr/lib/node_modules를 만들 수 없습니다. npm 자체의 힌트는 이 명령을 root로 실행하라고 말합니다. 그러나 Claude Code 문서는 그렇게 하지 말라고 안내합니다(sudo npm install -g 금지).

해결. 소유한 prefix에 설치하세요. 테스트에서는 NPM_CONFIG_PREFIX로 명령마다 설정했습니다. npm config set prefix를 사용하면 같은 설정을 영구적으로 적용할 수 있습니다:

코드

1234mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g @anthropic-ai/claude-code

새 터미널에서도 유지되도록 이 export PATH=... 줄을 셸 설정 파일에 추가하세요.

정상 동작 확인. 사용자 소유 prefix를 사용하니 sudo 없이 설치가 완료되었고 바이너리가 실행되었습니다:

코드

added 3 packages in 4s
2.1.295 (Claude Code)

npm 경로에서 알아둘 점 하나가 있습니다. npm이 claude-code-linux-x64와 claude-code-linux-x64-musl 두 플랫폼 패키지를 모두 가져오기 때문에 설치가 디스크에서 483 MB를 차지했습니다.

2. Node 20에서 EBADENGINE

보이는 내용

코드

12345npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '@anthropic-ai/claude-code@2.1.295',
npm WARN EBADENGINE   required: { node: '>=22.0.0' },
npm WARN EBADENGINE   current: { node: 'v20.19.2', npm: '9.2.0' }
npm WARN EBADENGINE }

원인. Claude Code 2.1.295는 node >=22를 선언합니다. 이것은 오류가 아니라 경고입니다. Node 20.19.2에서는 설치가 완료되었고 claude --version은 2.1.295 (Claude Code)를 출력했습니다. 문서에 따르면, 이 패키지는 런타임에서 Node를 사용하지 않는 네이티브 바이너리를 포함하므로 그렇게 동작합니다.

해결. 지금 당장 망가지는 것은 아니지만, 그 동작에 의존하지는 마세요. Node 22 이상으로 업그레이드하거나 native installer로 전환하세요.

3. “claude native binary not installed”

보이는 내용. npm 설치는 성공했다고 나오지만, 그 뒤 claude가 아래 메시지를 출력합니다(Claude Code 자체의 문구이며, 정확히 인용했습니다):

코드

1234567891011added 3 packages in 4s
Error: claude native binary not installed.

Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).

Run the postinstall manually (adjust path for local vs global install):
  node node_modules/@anthropic-ai/claude-code/install.cjs

Or reinstall without --ignore-scripts / --omit=optional.

원인. 우리는 npm install -g --ignore-scripts로 이를 재현했습니다. scripts를 건너뛰면 패키지의 postinstall 단계가 실행되지 않습니다.

이 메시지와 문서에서는 --omit=optional도 원인으로 언급합니다. npm 9.2.0에서는 이것이 재현되지 않았습니다: --omit=optional을 사용해도 플랫폼 패키지는 여전히 설치되었고 claude --version은 2.1.295 (Claude Code)를 출력했습니다. 우리는 npm 9.2.0만 테스트했으므로, 다른 npm 버전이나 설정에서 이 문제가 발생하는지는 말할 수 없습니다.

해결. 설치한 global prefix를 사용해 postinstall 스크립트를 직접 실행하세요:

코드

node <your-npm-prefix>/lib/node_modules/@anthropic-ai/claude-code/install.cjs

정상 동작 확인. install.cjs를 실행한 뒤 같은 바이너리가 다음을 출력했습니다:

코드

2.1.295 (Claude Code)

--ignore-scripts 없이 다시 설치하는 것도 메시지가 제안하는 또 다른 해결책입니다.

4. 네이티브 설치 후 “claude: command not found”

보이는 현상. 설치 프로그램은 성공했다고 말하지만, 셸은 그렇지 않다고 합니다. 우리는 PATH에 ~/.local/bin이 포함되어 있지 않은 셸에서 설치 스크립트(버전 2.1.295)를 실행했습니다:

코드

1234567891011121314151617Installing Claude Code native build 2.1.295...
Setting up launcher and shell integration...
⚠ Setup notes:
  ● Native installation exists but ~/.local/bin is not in your PATH. Run:

    echo 'export PATH="$HOME/.local/bin:$PATH"' >> your shell config file && source your shell config file

✔ Claude Code successfully installed!

  Version: 2.1.295

  Location: ~/.local/bin/claude
...
✅ Installation complete!

## same shell, PATH unchanged:
bash: line 1: claude: command not found

아래 스크린샷은 임시 홈 폴더에서 다시 실행한 더 짧은 예시입니다. 바이너리를 내려받은 뒤 install.sh가 호출하는 설치 단계를 실행하고, 그다음 PATH 확인과 수정까지 보여 줍니다.

기본 설치에서 ~/.local/bin이 PATH에 없다는 경고가 나오고, 테스트 스크립트에서는 claude: command not found가 표시된 뒤, export 후에는 2.1.295가 표시됩니다(Claude Code 2.1.295 네이티브 설치, Debian 13). 이미지 제공: 작성자.

이유. 실행 파일은 ~/.local/bin/claude에 있으며, 이는 ~/.local/share/claude/versions/로 연결된 심볼릭 링크입니다. 그 폴더가 PATH에 없다면 셸은 이를 찾지 못합니다. 설치 프로그램은 경고를 두 번 출력하지만, 초록색 “successfully installed” 줄 위에 있어서 쉽게 놓칠 수 있습니다.

문서에 나온 명령으로 PATH를 확인하세요. 아무 출력도 없으면 해당 폴더가 빠져 있다는 뜻입니다:

코드

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

수정. 설치 프로그램의 안내대로 해당 폴더를 PATH에 추가하고, 같은 줄을 셸 설정에도 넣습니다:

코드

export PATH="$HOME/.local/bin:$PATH"

작동 여부 확인. 같은 셸에서 export한 뒤:

코드

2.1.295 (Claude Code)

문서에 따르면 VS Code 확장은 자체 번들된 CLI를 사용하며 claude를 PATH에 넣지 않으므로, 확장을 설치해도 이 문제는 해결되지 않습니다.

5. 두 번 설치되어 있고, `claude doctor`는 문제가 없다고 말함

보이는 현상. 아무것도 보이지 않는 것이 문제입니다. 우리는 npm 복사본과 네이티브 복사본을 같은 PATH에 두고, which -a와 claude doctor 둘 다 실행해 보았습니다:

코드

123456789101112$ which -a claude
.../prefix-t2/bin/claude
.../home-t5/.local/bin/claude

$ claude doctor
Claude Code doctor

Running: npm-global (2.1.295)
...
Config install method: native
...
No installation issues found.

PATH에 있는 두 개의 Claude Code 복사본: claude doctor는 Running: npm-global 옆에 Config install method: native를 표시하면서도 여전히 No installation issues found라고 말합니다(Claude Code 2.1.295, Debian 13). 이미지 제공: 작성자.

중요한 이유. doctor는 실행 중인 복사본이 npm 버전이라고 보고했고, 설정은 native라고 표시했지만, 끝내 No installation issues found.로 마무리했습니다. 이 테스트에서 which -a claude는 중복을 보여 주었지만 doctor는 이를 잡아내지 못했습니다. claude doctor는 로그인 없이 실행되고 세션도 시작하지 않으므로 언제든 안전하게 실행할 수 있습니다.

열려 있는 GitHub 이슈에는 업데이트 과정에서 npm-global 설치가 잘못되는 사례가 설명되어 있습니다: #84224(PATH로 해석된 npm prefix에 자동 업데이트가 설치되면서 다른 설치를 덮어씀), #88091(npm 자동 업데이트 중 동시 세션이 경쟁 상태를 일으킴), #95297(claude upgrade가 대체 스텁을 남김). 우리는 어떤 자동 업데이트 동작도 재현하지 않았고(업데이트는 꺼져 있었음), 이슈 제목만 읽었습니다.

수정. 원하지 않는 복사본을 제거하세요. 우리는 npm 버전을 제거했습니다:

코드

npm uninstall -g @anthropic-ai/claude-code
hash -r
which -a claude

작동 여부 확인. 한 경로만 남았고, 이제 doctor는 네이티브 복사본을 보고했습니다:

코드

1234.../home-t5/.local/bin/claude
Claude Code doctor

Running: native (2.1.295)

제한 사항

Debian 13 x86_64와 Node 20.19.2, npm 9.2.0에서만 테스트했습니다. 테스트하지 않은 항목: Node 22+, npm 10~12, pnpm, yarn, macOS, WSL, Alpine/musl, ARM.
apt/dnf 저장소 설치는 테스트하지 않았습니다(sudo가 필요함).
문서와 Claude Code 자체 메시지에는 누락된 바이너리 오류의 원인으로 --omit=optional이 나열되어 있습니다. npm 9.2.0에서는 재현되지 않았고, 다른 npm 버전은 테스트하지 않았습니다.
GitHub 이슈에서 언급된 자동 업데이트 문제는 재현하지 않았습니다. 모든 테스트에서 자동 업데이트는 비활성화되어 있었습니다.
로그인은 하지 않았으므로, 설치 이후의 내용(첫 세션, /login)은 테스트하지 않았습니다.

핵심 정리

설치 방법은 하나만 고르세요. 문서에서 권장하는 것은 네이티브 설치입니다.
sudo npm install -g로 EACCES를 해결하지 마세요. 직접 소유한 prefix를 사용하세요.
EBADENGINE은 실패의 원인이 아니라 Node 22+로 옮겨야 한다는 신호로 보세요.
네이티브 설치 프로그램이 PATH 관련 메모를 출력하면, 다른 작업보다 먼저 ~/.local/bin을 PATH에 추가하세요.
재설치한 뒤에는 항상 which -a claude를 실행하세요. 우리의 테스트에서는 claude doctor가 놓친 중복을 이 명령이 잡아냈습니다.

이 중 어떤 문제를 겪으셨나요? 그리고 어떤 배포판과 npm 버전을 사용하셨나요?

참고 자료

Claude Code docs, Claude Code 설정: https://code.claude.com/docs/en/setup
Claude Code docs, 설치 문제 해결: https://code.claude.com/docs/en/troubleshoot-install
anthropics/claude-code 이슈 #84224: https://github.com/anthropics/claude-code/issues/84224
anthropics/claude-code 이슈 #88091: https://github.com/anthropics/claude-code/issues/88091
anthropics/claude-code 이슈 #95297: https://github.com/anthropics/claude-code/issues/95297

마지막 확인: 2026년 10월 9일, Claude Code 2.1.295, Node.js 20.19.2, npm 9.2.0. 새 버전에서 이것이 바뀌면 이야기를 업데이트하겠습니다.

출처

원문: https://nandanpriyadarshi.medium.com/claude-code-install-errors-on-linux-five-problems-and-the-fix-for-each-9959e862c189?source=rss------claude_code-5 (2026-10-23 · Nandan Priyadarshi)

자료 기준 · 변경 기록

이 글은 클로드 코드 2.1.308 판 기준그 뒤 변경 없음

자료 변경 기록을 불러오는 중입니다.

이 글이 속한 모듈

코딩 에이전트 설치하고 개발 환경 갖추기

전체 14개 자료 중 6번째입니다. 모듈 로드맵에서 학습 순서와 전체 자료를 확인합니다.

모듈 로드맵 보기 로그인 후 모듈 저장

다음 자료를 불러오는 중입니다.

더 넓은 학습 과정

AI로 개발하기

‘코딩 에이전트 설치하고 개발 환경 갖추기’ 모듈이 포함된 7개 모듈의 패키지입니다. 코딩 에이전트를 설치하고 앱 하나를 끝까지 만들기

패키지 전체 보기 로그인 후 패키지 저장

후기

아직 후기가 없습니다

직접 적용한 결과와 주의할 점을 공유하는 공간입니다.

로그인하고 후기 쓰기

참고 자료 · 도구와 릴리스 노트

도구

클로드 코드122

릴리스 노트

10.222.1.309 업무 흐름과 보안 안내를 강화한 변경 10.222.1.308 버그 수정과 안정성 개선 10.212.1.305 샌드박스와 허용 서버, 확인 흐름 개선

자세히 보기 →

코딩 에이전트 설치하고 개발 환경 갖추기 관련 자료

Claude Code 설치와 첫 사용 FAQ Claude Code를 무료 토큰으로 쓰는 설정법 Claude Code 설치용 셸별 명령과 자주 나는 오류 윈도우에서 Claude Code가 조용히 망가지는 15가지 함정 Claude Code 사용 시작 안내

EACCES, EBADENGINE, 네이티브 바이너리 누락, command not found, 그리고 중복 설치를 Debian 13에서 재현했습니다.

메시지 찾기

1. EACCES: permission denied

2. Node 20에서 EBADENGINE

3. “claude native binary not installed”

4. 네이티브 설치 후 “claude: command not found”

5. 두 번 설치되어 있고, claude doctor는 문제가 없다고 말함

제한 사항

핵심 정리

참고 자료

출처

코딩 에이전트 설치하고 개발 환경 갖추기

AI로 개발하기

후기

아직 후기가 없습니다

댓글

AI로 개발하기

코딩 에이전트 설치하고 개발 환경 갖추기

5. 두 번 설치되어 있고, `claude doctor`는 문제가 없다고 말함