Claude Code 네이티브 바이너리 설치 가이드 - npm 폐지 이후 달라진 모든 것

Claude Code의 설치 방법이 바뀌었다. 2026년 1월(v2.1.15)부터 npm 설치가 deprecated되고, 네이티브 바이너리가 공식 설치 방법이 됐다. Node.js를 먼저 깔고, npm으로 글로벌 패키지를 설치하는 과정이 통째로 사라진 것이다.

터미널에서 curl -fsSL https://claude.ai/install.sh | bash 한 줄이면 끝난다. Node.js도 필요 없고, npm도 필요 없다. Windows에서도 PowerShell 명령어 한 줄이면 된다.

이 글에서는 Claude Code가 npm을 버리고 네이티브 바이너리로 전환한 배경, 실제 설치 방법, npm에서 마이그레이션하는 방법, 그리고 이 변화가 AI 코딩 도구 생태계에서 어떤 의미를 갖는지 정리한다.

Claude Code 네이티브 바이너리 전환, 왜 일어났나

Claude Code npm에서 네이티브 바이너리로 전환된 개발 환경과 코딩 작업 화면

Claude Code는 원래 npm install -g @anthropic-ai/claude-code로 설치하는 도구였다. Node.js 18 이상을 먼저 설치하고, npm으로 글로벌 패키지를 깔아야 했다. 개발자에게는 익숙한 과정이지만, 비개발자에게는 꽤 높은 진입 장벽이었다.

Anthropic은 이 문제를 근본적으로 해결하기로 했다. Claude Code 창시자 Boris Cherny가 Threads에서 직접 밝힌 내용에 따르면, Bun 팀과 수개월간 협력해서 Node.js/npm 의존성을 완전히 제거한 네이티브 실행 파일을 만들었다.

여기서 더 흥미로운 건 후속 행보다. 2025년 12월, Anthropic은 Bun을 아예 인수했다. Claude Code가 연간 매출 10억 달러를 달성한 시점에서 내린 결정이다. Bun의 Jarred Sumner가 "Claude Code is now a Bun single-file executable"라고 직접 확인했을 정도로, 두 회사의 기술적 통합은 이미 깊게 진행되어 있었다.

쉽게 말해, "Git for Windows" 방식이다. Git for Windows가 bash 셸과 도구를 하나의 인스톨러에 번들해서 배포하는 것처럼, Claude Code도 Bun 런타임을 내장한 단일 바이너리로 배포된다. 별도 런타임 설치가 필요 없다.

npm 설치 vs 네이티브 바이너리 비교

기존 npm 설치 방식과 새로운 네이티브 바이너리 방식의 차이를 한눈에 비교하면 이렇다.

비교 항목	npm 설치 (deprecated)	네이티브 바이너리 (권장)
사전 요구사항	Node.js 18+, npm	없음
설치 명령어	npm install -g @anthropic-ai/claude-code	curl 한 줄
설치 용량	수백 MB (node_modules 포함)	약 60MB (단일 바이너리)
업데이트 방식	npm update -g (수동)	백그라운드 자동 업데이트
시작 속도	Node.js 기반 (보통)	Bun 기반 (5~8배 빠름)
버전 관리자 충돌	nvm, asdf와 충돌 가능	충돌 없음
설치 경로	npm 글로벌 디렉토리	~/.local/bin/claude
버전 다운그레이드	npm install -g @version 으로 쉬움	특정 버전 지정 설치 가능

가장 체감이 큰 차이는 시작 속도다. Bun은 Node.js 대비 콜드 스타트가 13배 이상 빠르고, HTTP 처리량은 약 4배 높다는 벤치마크 결과가 있다. Claude Code를 열 때마다 느끼는 체감 속도가 달라진다.

Claude Code 네이티브 바이너리 설치 방법

Claude Code 네이티브 바이너리 설치를 위한 터미널 코드 입력 화면

운영체제별 설치 방법을 정리한다. 2026년 2월 기준이다.

macOS / Linux

터미널을 열고 아래 명령어를 실행한다.

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

설치가 끝나면 claude 명령어를 바로 쓸 수 있다. 별도 PATH 설정도 자동으로 처리된다.

Windows PowerShell

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

Windows CMD

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

패키지 관리자로 설치하기

macOS에서 Homebrew를 쓴다면 이 방법도 가능하다.

brew install --cask claude-code

Windows에서 WinGet을 쓴다면 이렇게 설치할 수 있다.

winget install Anthropic.ClaudeCode

Windows에서 Git for Windows 필수

Windows 사용자는 한 가지 더 챙겨야 한다. Claude Code가 내부적으로 Git Bash를 사용하기 때문에, Git for Windows가 반드시 설치되어 있어야 한다. Git Bash 경로를 Claude Code가 자동으로 찾지 못하는 경우, settings.json에서 직접 지정할 수 있다.

{"env": {"CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"}}

npm에서 네이티브 바이너리로 마이그레이션

이미 npm으로 Claude Code를 쓰고 있다면, 마이그레이션은 간단하다. 두 가지 방법이 있다.

방법 1. 직접 설치 후 기존 제거

네이티브 바이너리를 설치한다 - curl -fsSL https://claude.ai/install.sh | bash
기존 npm 패키지를 제거한다 - npm uninstall -g @anthropic-ai/claude-code

방법 2. 기존 Claude Code 세션에서 설치

이미 Claude Code가 실행 중이라면, 세션 안에서 claude install을 실행하면 된다. 네이티브 바이너리를 자동으로 설치하고 npm 버전에서 전환해준다.

마이그레이션 후에도 기존 설정(CLAUDE.md, 프로젝트 설정 등)은 모두 유지된다. 설치 경로만 바뀌고, 사용 경험은 동일하다.

자동 업데이트와 버전 관리

네이티브 바이너리의 가장 큰 변화 중 하나는 자동 백그라운드 업데이트다. npm 시절에는 npm update -g를 직접 실행해야 했지만, 이제는 Claude Code가 백그라운드에서 알아서 최신 버전으로 업데이트된다.

릴리스 채널 설정

업데이트 속도를 조절하고 싶다면 릴리스 채널을 바꿀 수 있다. settings.json에 아래 설정을 추가하면 된다.

{"autoUpdatesChannel": "stable"}

latest 채널은 새 버전이 나오면 바로 업데이트된다. stable 채널은 약 1주일 딜레이가 있어서, 최신 버전에서 발생하는 초기 이슈를 피할 수 있다. 안정성을 중시하는 팀이라면 stable을 추천한다.

자동 업데이트 비활성화

CI/CD 파이프라인이나 에어갭 환경에서는 자동 업데이트를 끄는 게 나을 수 있다. 환경변수로 비활성화할 수 있다.

DISABLE_AUTOUPDATER=1

특정 버전 설치

특정 버전을 고정해야 하는 경우, 설치 스크립트에 버전 번호를 지정할 수 있다.

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

커뮤니티 반응과 실제 우려사항

Claude Code 네이티브 바이너리 전환에 대한 개발자 커뮤니티 논의와 협업 장면

네이티브 바이너리 전환에 대한 커뮤니티 반응은 양극단이다. "드디어 Node.js 지옥에서 벗어났다"는 환영과 "왜 잘 되던 걸 바꾸냐"는 불만이 공존한다.

GitHub 이슈에서 나온 주요 우려사항을 정리하면 이렇다.

버전 다운그레이드가 어렵다

npm에서는 npm install -g @anthropic-ai/claude-code@1.0.50처럼 원하는 버전으로 쉽게 돌아갈 수 있었다. 네이티브 바이너리에서도 버전 지정 설치는 가능하지만, npm만큼 직관적이지 않다는 의견이 많다. GitHub Issue #20058에서는 "npm을 deprecate하려면 최소한 동등한 수준의 버전 관리 기능을 먼저 갖춰라"는 요구가 나왔다.

curl | bash 방식의 보안 우려

엔터프라이즈 환경에서 curl | bash 패턴은 보안 정책에 걸리는 경우가 많다. 에어갭 네트워크에서는 아예 사용할 수 없다. Anthropic 측 담당자 Kurt는 dnf, apt 같은 Linux 공식 패키지 저장소 지원을 검토 중이라고 밝혔다.

CI/CD에서 버전 고정이 까다롭다

자동 업데이트는 개인 개발자에게는 편하지만, CI/CD 파이프라인에서는 빌드 재현성을 깨뜨릴 수 있다. DISABLE_AUTOUPDATER=1과 버전 지정 설치로 해결할 수 있지만, npm의 lockfile 기반 버전 고정보다는 번거롭다.

비주류 OS 지원 부족

illumos, OpenBSD, Solaris 같은 비주류 플랫폼에서는 네이티브 바이너리가 지원되지 않는다. npm은 Node.js가 돌아가는 곳이면 어디서든 작동했기 때문에, 이런 환경의 사용자들은 불편함을 호소하고 있다.

다행히 npm 패키지는 deprecated 상태이지만 여전히 발행되고 있다. 네이티브 바이너리가 맞지 않는 환경에서는 당분간 npm을 계속 쓸 수 있다.

Anthropic의 Bun 인수가 의미하는 것

Claude Code의 네이티브 바이너리 전환과 Anthropic의 Bun 인수는 같은 맥락에서 읽어야 한다.

Bun은 JavaScript 런타임, 패키지 매니저, 번들러, 테스트 러너를 하나로 합친 올인원 도구다. 월간 다운로드 700만 건 이상, GitHub 스타 82,000개를 기록하고 있다. Midjourney, Lovable 같은 회사에서 이미 프로덕션에 채택한 검증된 런타임이다.

Anthropic이 Bun을 인수한 이유는 명확하다. Claude Code뿐 아니라 Claude Agent SDK, 그리고 앞으로 나올 AI 코딩 제품 전체의 인프라로 Bun을 쓰겠다는 전략이다. Bun은 인수 이후에도 오픈소스(MIT 라이선스)를 유지한다.

실무 관점에서 이것이 의미하는 건 3가지다.

성능 향상이 지속적으로 이어진다 - Bun 팀이 Anthropic 내부에서 Claude Code 최적화에 집중하기 때문에, 시작 속도와 실행 성능이 계속 개선될 가능성이 높다
AI 코딩 도구의 진입 장벽이 더 낮아진다 - Node.js를 모르는 기획자, 디자이너, 마케터도 터미널에서 명령어 한 줄로 Claude Code를 쓸 수 있게 됐다
CLI 도구의 배포 전략이 바뀌고 있다 - Cursor나 Windsurf 같은 IDE 기반 도구와 달리, Claude Code는 CLI 도구로서 "설치의 단순화"를 통해 접근성을 확보하는 전략을 택했다

Bun 기반 단일 실행 파일의 기술적 배경

기술적으로 궁금한 사람을 위해 좀 더 깊이 들어가 보자.

Claude Code의 네이티브 바이너리는 Bun의 bun build --compile 기능으로 만들어진다. 이 기능은 JavaScript/TypeScript 코드를 Bun 런타임과 함께 하나의 실행 파일로 패키징한다. macOS, Linux, Windows 각 플랫폼용으로 약 60MB 크기의 바이너리가 생성된다.

성능 벤치마크를 보면 차이가 선명하다.

측정 항목	Node.js	Bun	차이
콜드 스타트	1,270ms	95ms	13.4배 빠름
HTTP 처리량	32,000 req/s	120,000 req/s	3.75배 빠름
유휴 메모리	기준치	39% 적음	메모리 효율
부하 시 메모리	기준치	41% 적음	메모리 효율

콜드 스타트 13.4배 차이는 체감에서도 크다. Claude Code를 열 때마다 1초 이상 기다리던 것이 100ms 이내로 줄어든다. 하루에 수십 번 실행하는 도구라면 누적 시간 절약이 상당하다.

다만 Bun 바이너리가 Node.js보다 RSS(Resident Set Size) 메모리를 20~40% 더 사용한다는 벤치마크 결과도 있다. 60MB짜리 자체 포함 실행 파일이 런타임을 언팩해야 하기 때문이다. 대부분의 현대 컴퓨터에서는 이 정도 차이가 문제되지 않지만, 메모리가 극도로 제한된 환경에서는 고려할 부분이다.

자주 묻는 질문

npm으로 설치한 Claude Code를 계속 쓸 수 있나?

쓸 수 있다. npm 패키지는 deprecated 상태이지만 계속 발행되고 있다. 다만 Anthropic은 네이티브 바이너리로의 전환을 강력히 권장하고 있고, 향후 npm 패키지 지원이 완전히 중단될 가능성이 있다. 가능하면 빠르게 마이그레이션하는 게 좋다.

설치 후 기존 프로젝트 설정이 유지되나?

유지된다. CLAUDE.md, .claude/ 디렉토리, MCP 서버 설정, 프로젝트별 설정 파일 등은 모두 그대로 작동한다. 설치 경로와 실행 방식만 바뀌는 것이고, 사용자 입장에서의 기능은 동일하다.

자동 업데이트를 끌 수 있나?

끌 수 있다. DISABLE_AUTOUPDATER=1 환경변수를 설정하면 된다. CI/CD 파이프라인이나 엔터프라이즈 환경에서 빌드 재현성이 중요한 경우에 유용하다. 특정 버전으로 고정하려면 curl -fsSL https://claude.ai/install.sh | bash -s [버전번호]로 설치하면 된다.

코딩을 몰라도 설치할 수 있나?

할 수 있다. macOS에서는 터미널을 열고 명령어 한 줄을 붙여넣으면 끝이다. 기존 npm 방식에서는 Node.js가 뭔지, npm이 뭔지부터 알아야 했지만, 이제는 그럴 필요가 없다. macOS에서 Homebrew를 쓴다면 brew install --cask claude-code가 더 쉬울 수 있다.

Windows에서 추가로 설치해야 하는 게 있나?

Git for Windows가 필요하다. Claude Code가 내부적으로 Git Bash를 사용하기 때문이다. git-scm.com에서 다운로드할 수 있다. Git for Windows를 설치한 뒤 Claude Code를 설치하면 자동으로 Git Bash를 인식한다.

stable 채널과 latest 채널의 차이는 뭔가?

latest는 새 버전이 나오면 즉시 업데이트된다. stable은 약 1주일의 딜레이가 있다. 그 사이에 커뮤니티에서 발견된 이슈가 수정된 버전이 내려오기 때문에, 안정성을 중시한다면 stable이 낫다. settings.json에서 "autoUpdatesChannel": "stable"로 설정할 수 있다.

정리하면

Claude Code의 npm 폐지와 네이티브 바이너리 전환은 단순한 설치 방법 변경이 아니다. Node.js 의존성 제거, Bun 기반의 성능 향상, 자동 업데이트, 그리고 비개발자까지 포용하는 접근성 확보까지 — AI 코딩 도구가 "개발자 전용"에서 "누구나 쓸 수 있는 도구"로 진화하는 과정이다.

이미 npm으로 Claude Code를 쓰고 있다면, curl -fsSL https://claude.ai/install.sh | bash 한 줄로 마이그레이션할 수 있다. 새로 시작하는 사람이라면 더 간단하다. 같은 명령어 한 줄이면 된다.

AI 코딩 도구 활용법이 더 궁금하다면 자동화 사례에서 다양한 실전 가이드를 확인할 수 있다. Claude Code 관련 영상 튜토리얼은 영상 레시피에서 볼 수 있다.