Claude Code 설치 가이드 - 네이티브 설치와 npm 방식 비교

확인·정정: 2026년 9월 15일. 설치 방식과 요구사항은 Claude Code 공식 설치 문서를 기준으로 수정했다. 아래의 전환 배경·커뮤니티 반응은 2026년 2월 작성 당시의 기록이다.

Claude Code는 네이티브 설치와 npm 설치를 모두 지원한다. 2026년 9월 15일 공식 문서 확인 결과, npm 패키지도 같은 네이티브 바이너리를 설치하며 실행할 때 Node.js를 사용하지 않는다. 이 글의 기존 “npm 폐지” 설명을 정정한다.

네이티브 설치는 터미널에서 curl -fsSL https://claude.ai/install.sh | bash 한 줄이면 끝난다. 실행할 때 Node.js가 필요 없다. Windows에서도 PowerShell 명령어 한 줄이면 된다.

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

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

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

Anthropic은 이 문제를 근본적으로 해결하기로 했다. Claude Code 창시자 Boris Cherny가 Threads에서 직접 밝힌 내용에 따르면, Bun 팀과 수개월간 협력해서 실행할 때 Node.js가 필요 없는 네이티브 실행 파일을 만들었다.

여기서 더 흥미로운 건 후속 행보다. 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 네이티브 바이너리 비교

2026년 9월 공식 설치 안내에 따른 비교다.

항목	npm 설치	네이티브 설치
설치 시 요구사항	v2.1.198 이후 Node.js 22 이상	Node.js 불필요
실행 파일	플랫폼별 네이티브 바이너리	같은 네이티브 바이너리
업데이트 방식	`npm install -g @anthropic-ai/claude-code@latest`	자동 업데이트

설치 방식만으로 Claude Code가 몇 배 빨라진다고 단정할 수 없다. npm도 같은 네이티브 바이너리를 설치하므로, 일반적인 Bun·Node.js 벤치마크를 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에서 Git for Windows는 필수가 아니라 선택 사항이다. 설치하지 않으면 Claude Code가 PowerShell을 사용한다. Git Bash를 쓰고 싶은데 경로를 자동으로 찾지 못하면 settings.json에서 직접 지정할 수 있는데, 이 경로 설정이 듣지 않는 경우도 있다.

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

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

npm 설치도 계속 지원되므로 반드시 옮겨야 하는 것은 아니다. 네이티브 설치로 바꾸고 싶다면 두 가지 방법이 있다.

방법 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 install -g @anthropic-ai/claude-code@latest로 업데이트한다.

릴리스 채널 설정

업데이트 속도를 조절하고 싶다면 릴리스 채널을 바꿀 수 있다. 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

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

네이티브 바이너리 전환에 대한 커뮤니티 반응은 양극단이다. "드디어 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 기반 버전 고정보다는 번거롭다.

지원 플랫폼을 먼저 확인해야 한다

npm 설치도 지원 플랫폼에 맞는 네이티브 바이너리가 필요하다. Node.js가 설치됐다는 이유만으로 모든 운영체제에서 실행되는 것은 아니다.

지원 운영체제와 플랫폼 패키지는 공식 설치 문서에서 확인한다.

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 각 플랫폼용 실행 파일이 만들어진다.

이전 버전의 일반 런타임 속도·메모리 비교 수치는 Claude Code를 직접 측정한 근거가 확인되지 않아 제외했다.

자주 묻는 질문

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

쓸 수 있다. 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는 PowerShell을 사용한다. Git Bash를 쓰려면 git-scm.com에서 설치하고, 경로를 자동으로 인식하지 못하면 settings.json의 CLAUDE_CODE_GIT_BASH_PATH로 지정한다. 이 경로 지정이 듣지 않는 경우도 있어, 문제가 생기면 설치 문제 해결 문서를 확인한다.

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

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

정리하면

Claude Code의 네이티브 설치 지원은 단순한 설치 방법 변경이 아니다. 실행에 별도 런타임이 필요 없다는 점, 자동 업데이트, 그리고 비개발자까지 포용하는 접근성 확보까지 — AI 코딩 도구가 "개발자 전용"에서 "누구나 쓸 수 있는 도구"로 진화하는 과정이다. 다만 npm 설치도 함께 지원되므로, 설치 방식에 따라 성능이 달라진다는 식으로 읽으면 안 된다.

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

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