import Install from "/snippets/cli/install.mdx";

기본 사용법

bun install react
bun install react@19.1.1 # 특정 버전
bun install react@latest # 특정 태그

bun CLI 는 Node.js 와 호환되는 패키지 관리자를 포함하며 npm, yarn, pnpm 보다 훨씬 빠른 대체품으로 설계되었습니다. 이는 독립적인 도구로 기존 Node.js 프로젝트에서 작동합니다. 프로젝트에 package.json 이 있는 경우 bun install 을 사용하여 워크플로우를 가속화할 수 있습니다.

NOTE

⚡️ 25 배 더 빠름 — 모든 Node.js 프로젝트에서 npm install 에서 bun install 로 전환하여 설치를 최대 25 배 더 빠르게 만드세요.

Linux 사용자용

권장 최소 Linux 커널 버전은 5.6 입니다. Linux 커널 5.1 - 5.5 를 사용하는 경우 bun install 은 작동하지만 io_uring 의 connect() 작업 지원 부재로 인해 HTTP 요청이 느려집니다.

Ubuntu 20.04 를 사용하는 경우 최신 커널 을 설치하는 방법은 다음과 같습니다.

# 5.6 이상의 버전을 반환하면 아무것도 할 필요가 없습니다.
uname -r

# 공식 Ubuntu 하드웨어 활성화 커널 설치
sudo apt install --install-recommends linux-generic-hwe-20.04

프로젝트의 모든 의존성을 설치하려면:

bun install

bun install 을 실행하면 다음이 수행됩니다.

• 설치 모든 dependencies, devDependencies 및 optionalDependencies. Bun 은 기본적으로 peerDependencies 를 설치합니다.
• 실행 프로젝트의 {pre|post}install 및 {pre|post}prepare 스크립트를 적절한 시간에 실행합니다. 보안상의 이유로 Bun 은 설치된 의존성의 라이프사이클 스크립트를 실행하지 않습니다.
• 작성 bun.lock lockfile 을 프로젝트 루트에 작성합니다.

---

로깅

로깅 상세도를 수정하려면:

bun install --verbose # 디버그 로깅
bun install --silent  # 로깅 없음

---

라이프사이클 스크립트

다른 npm 클라이언트와 달리 Bun 은 설치된 의존성에 대해 postinstall 과 같은 임의의 라이프사이클 스크립트를 실행하지 않습니다. 임의의 스크립트를 실행하는 것은 잠재적인 보안 위험을 나타냅니다.

특정 패키지에 대해 라이프사이클 스크립트를 허용하도록 Bun 에 알려려면 package.json 에서 패키지를 trustedDependencies 에 추가합니다.

{
  "name": "my-app",
  "version": "1.0.0",
  "trustedDependencies": ["my-trusted-package"] 
}

그런 다음 패키지를 재설치합니다. Bun 은 이 필드를 읽고 my-trusted-package 에 대한 라이프사이클 스크립트를 실행합니다.

라이프사이클 스크립트는 설치 중에 병렬로 실행됩니다. 동시 스크립트의 최대 수를 조정하려면 --concurrent-scripts 플래그를 사용합니다. 기본값은 보고된 cpu 수 또는 GOMAXPROCS 의 두 배입니다.

bun install --concurrent-scripts 5

Bun 은 어떤 스크립트를 실행해야 하는지 결정하여 인기 있는 패키지 (예: esbuild, sharp 등) 에 대한 postinstall 스크립트를 자동으로 최적화합니다. 이러한 최적화를 비활성화하려면:

BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install

---

워크스페이스

Bun 은 package.json 에서 "workspaces" 를 지원합니다. 전체 문서는 패키지 관리자 > 워크스페이스 를 참조하세요.

{
  "name": "my-app",
  "version": "1.0.0",
  "workspaces": ["packages/*"], 
  "dependencies": {
    "preact": "^10.5.13"
  }
}

---

특정 패키지에 대한 의존성 설치

모노레포에서 --filter 플래그를 사용하여 패키지 하위 집합의 의존성을 설치할 수 있습니다.

# `pkg-c` 를 제외한 모든 워크스페이스의 의존성 설치
bun install --filter '!pkg-c'

# `./packages/pkg-a` 의 `pkg-a` 에 대한 의존성만 설치
bun install --filter './packages/pkg-a'

bun install 로 필터링하는 방법에 대한 자세한 내용은 패키지 관리자 > 필터링 을 참조하세요.

---

Overrides 와 resolutions

Bun 은 package.json 에서 npm 의 "overrides" 와 Yarn 의 "resolutions" 를 지원합니다. 이는 메타의존성 (의존성의 의존성) 에 대한 버전 범위를 지정하는 메커니즘입니다. 전체 문서는 패키지 관리자 > Overrides 와 resolutions 를 참조하세요.

{
  "name": "my-app",
  "dependencies": {
    "foo": "^2.0.0"
  },
  "overrides": { 
    "bar": "~4.4.0"
  } 
}

---

전역 패키지

패키지를 전역으로 설치하려면 -g/--global 플래그를 사용합니다. 일반적으로 명령줄 도구 설치에 사용됩니다.

bun install --global cowsay # 또는 `bun install -g cowsay`
cowsay "Bun!"

 ______
< Bun! >
 ------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

---

프로덕션 모드

프로덕션 모드 (devDependencies 또는 optionalDependencies 없이) 로 설치하려면:

bun install --production

재현 가능한 설치를 위해 --frozen-lockfile 을 사용합니다. 이는 lockfile 에 지정된 각 패키지의 정확한 버전을 설치합니다. package.json 이 bun.lock 과 일치하지 않으면 Bun 은 오류로 종료됩니다. lockfile 은 업데이트되지 않습니다.

bun install --frozen-lockfile

Bun 의 lockfile bun.lock 에 대한 자세한 내용은 패키지 관리자 > Lockfile 을 참조하세요.

---

의존성 생략

--omit 플래그를 사용하여 dev, peer 또는 optional 의존성을 생략합니다.

# 설치에서 "devDependencies" 제외. 이는 루트 패키지와
# 워크스페이스 (있는 경우) 에 적용됩니다. 전이적 의존성은
# "devDependencies" 를 갖지 않습니다.
bun install --omit dev

# "dependencies" 의 의존성만 설치
bun install --omit=dev --omit=peer --omit=optional

---

Dry run

dry run 을 수행하려면 (실제로 아무것도 설치하지 않음):

bun install --dry-run

---

비 npm 의존성

Bun 은 Git, GitHub, 로컬 또는 원격 호스팅 tarball 에서 의존성을 설치하는 것을 지원합니다. 전체 문서는 패키지 관리자 > Git, GitHub 및 tarball 의존성 을 참조하세요.

{
  "dependencies": {
    "dayjs": "git+https://github.com/iamkun/dayjs.git",
    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
    "moment": "git@github.com:moment/moment.git",
    "zod": "github:colinhacks/zod",
    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",
    "bun-types": "npm:@types/bun"
  }
}

---

설치 전략

Bun 은 의존성이 node_modules 에 구성되는 방식을 결정하는 두 가지 패키지 설치 전략을 지원합니다.

Hoisted 설치

의존성을 공유 node_modules 디렉토리로 평평하게 하는 기존 npm/Yarn 접근 방식입니다.

bun install --linker hoisted

격리된 설치

팬텀 의존성을 방지하기 위해 엄격한 의존성 격리를 생성하는 pnpm 스타일의 접근 방식입니다.

bun install --linker isolated

격리된 설치는 node_modules/.bun/ 에 중앙 패키지 저장소를 생성하고 최상위 node_modules 에 심볼릭 링크를 생성합니다. 이는 패키지가 선언된 의존성에만 액세스할 수 있도록 보장합니다.

기본 전략

기본 링커 전략은 새로 시작하는지 기존 프로젝트가 있는지에 따라 달라집니다.

• 새 워크스페이스/모노레포: isolated (팬텀 의존성 방지)
• 새 단일 패키지 프로젝트: hoisted (기존 npm 동작)
• 기존 프로젝트 (v1.3.2 이전에 생성): hoisted (하위 호환성 유지)

기본값은 lockfile 의 configVersion 필드로 제어됩니다. 자세한 설명은 패키지 관리자 > 격리된 설치 를 참조하세요.

---

최소 릴리스 연령

악성 패키지가 빠르게 게시되는 공급망 공격으로부터 보호하기 위해 npm 패키지에 대한 최소 연령 요구 사항을 구성할 수 있습니다. 지정된 임계값 (초) 보다 최근에 게시된 패키지 버전은 설치 중에 필터링됩니다.

# 최소 3 일 전에 게시된 패키지 버전만 설치
bun add @types/bun --minimum-release-age 259200 # 초

bunfig.toml 에서 이것을 구성할 수도 있습니다.

[install]
# 최소 3 일 전에 게시된 패키지 버전만 설치
minimumReleaseAge = 259200 # 초

# 신뢰할 수 있는 패키지를 연령 게이트에서 제외
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

최소 연령 필터가 활성화되면:

• 새 패키지 해결에만 영향을 미치며 bun.lock 의 기존 패키지는 변경되지 않은 상태로 유지됩니다.
• 모든 의존성 (직접 및 전이적) 은 해결될 때 연령 요구 사항을 충족하도록 필터링됩니다.
• 버전이 연령 게이트에 의해 차단되면 안정성 검사는 급격한 버그 수정 패턴을 감지합니다.
  • 연령 게이트 바로 바깥에서 여러 버전이 가까이 게시된 경우 필터를 확장하여 잠재적으로 불안정한 해당 버전을 건너뛰고 더 오래되고 성숙한 버전을 선택합니다.
  • 연령 게이트 이후 최대 7 일까지 검색하지만 여전히 빠른 릴리스를 찾으면 안정성 검사를 무시합니다.
  • 정확한 버전 요청 (예: package@1.1.1) 은 연령 게이트를 따르지만 안정성 검사는 우회합니다.
• time 필드가 없는 버전은 연령 검사를 통과한 것으로 처리됩니다 (npm 레지스트리는 항상 타임스탬프를 제공해야 함).

서비스 및 사용자 정의 필터링과의 통합을 포함한 고급 보안 스캐닝에 대해서는 패키지 관리자 > 보안 스캐너 API 를 참조하세요.

---

구성

bunfig.toml 로 bun install 구성

bunfig.toml 은 bun install, bun remove 및 bun add 에서 다음 경로에서 검색됩니다.

1. $XDG_CONFIG_HOME/.bunfig.toml 또는 $HOME/.bunfig.toml
2. ./bunfig.toml

둘 다 발견되면 결과가 병합됩니다.

bunfig.toml 로 구성하는 것은 선택 사항입니다. Bun 은 일반적으로 제로 구성을 목표로 하지만 항상 가능한 것은 아닙니다. bun install 의 기본 동작은 bunfig.toml 에서 구성할 수 있습니다. 기본 값은 아래와 같습니다.

[install]

# optionalDependencies 설치 여부
optional = true

# devDependencies 설치 여부
dev = true

# peerDependencies 설치 여부
peer = true

# `--production` 플래그와 동일
production = false

# `--save-text-lockfile` 플래그와 동일
saveTextLockfile = false

# `--frozen-lockfile` 플래그와 동일
frozenLockfile = false

# `--dry-run` 플래그와 동일
dryRun = false

# `--concurrent-scripts` 플래그와 동일
concurrentScripts = 16 # (cpu 수 또는 GOMAXPROCS) x2

# 설치 전략: "hoisted" 또는 "isolated"
# 기본값은 lockfile configVersion 과 workspaces 에 따라 다름:
# - configVersion = 1: workspaces 사용 시 "isolated", 그렇지 않으면 "hoisted"
# - configVersion = 0: "hoisted"
linker = "hoisted"


# 최소 연령 구성
minimumReleaseAge = 259200 # 초
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

환경 변수로 구성

환경 변수는 bunfig.toml 보다 높은 우선순위를 가집니다.

이름	설명
BUN_CONFIG_REGISTRY	npm 레지스트리 설정 (기본값: https://registry.npmjs.org)
BUN_CONFIG_TOKEN	auth 토큰 설정 (현재 아무 작업도 수행하지 않음)
BUN_CONFIG_YARN_LOCKFILE	Yarn v1 스타일 yarn.lock 저장
BUN_CONFIG_LINK_NATIVE_BINS	package.json 의 bin 을 플랫폼별 의존성으로 지정
BUN_CONFIG_SKIP_SAVE_LOCKFILE	lockfile 저장 안 함
BUN_CONFIG_SKIP_LOAD_LOCKFILE	lockfile 로드 안 함
BUN_CONFIG_SKIP_INSTALL_PACKAGES	패키지 설치 안 함

Bun 은 항상 대상 플랫폼에 사용할 수 있는 가장 빠른 설치 방법을 사용하려고 합니다. macOS 에서는 clonefile 이고 Linux 에서는 hardlink 입니다. --backend 플래그를 사용하여 사용되는 설치 방법을 변경할 수 있습니다. 사용할 수 없거나 오류가 발생하면 clonefile 과 hardlink 는 플랫폼별 파일 복사 구현으로 폴백합니다.

Bun 은 npm 에서 설치된 패키지를 ~/.bun/install/cache/${name}@${version} 에 저장합니다. semver 버전에 build 또는 pre 태그가 있는 경우 긴 파일 경로로 인한 오류 가능성을 줄이기 위해 해당 값의 해시로 대체됩니다. 하지만 불행히도 패키지가 디스크의 어디에 설치되었는지 파악하는 것이 복잡해집니다.

node_modules 폴더가 있는 경우 설치 전에 Bun 은 예상 node_modules 폴더의 package/package.json 에 있는 "name" 과 "version" 이 예상 name 과 version 과 일치하는지 확인합니다. 이것이 설치 여부를 결정하는 방법입니다. "name" 과 "version" 을 찾는 즉시 파싱을 중지하는 사용자 정의 JSON 파서를 사용합니다.

bun.lock 이 존재하지 않거나 package.json 이 의존성을 변경한 경우 tarball 은 해결하는 동안 즉시 다운로드 및 추출됩니다.

bun.lock 이 존재하고 package.json 이 변경되지 않은 경우 Bun 은 누락된 의존성을 지연 다운로드합니다. name 과 version 이 일치하는 패키지가 node_modules 내의 예상 위치에 이미 있는 경우 Bun 은 tarball 을 다운로드하지 않습니다.

CI/CD

공식 oven-sh/setup-bun 액션을 사용하여 GitHub Actions 파이프라인에서 bun 을 설치합니다.

name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun install
      - name: Build app
        run: bun run build

재현 가능한 빌드를 강제하려는 CI/CD 환경의 경우 bun ci 를 사용하여 package.json 이 lockfile 과 동기화되지 않으면 빌드를 실패합니다.

bun ci

이는 bun install --frozen-lockfile 과 동일합니다. bun.lock 에서 정확한 버전을 설치하고 package.json 이 lockfile 과 일치하지 않으면 실패합니다. bun ci 또는 bun install --frozen-lockfile 을 사용하려면 bun.lock 을 버전 관리에 커밋해야 합니다.

그리고 bun install 을 실행하는 대신 bun ci 를 실행합니다.

name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun ci
      - name: Build app
        run: bun run build

플랫폼별 의존성?

bun 은 npm 의 정규화된 cpu 와 os 값을 해결된 패키지와 함께 lockfile 에 저장합니다. 런타임에 현재 대상에 대해 비활성화된 패키지 다운로드, 추출 및 설치를 건너뜁니다. 이는 궁극적으로 설치된 패키지가 변경되더라도 lockfile 이 플랫폼/아키텍처 간에 변경되지 않음을 의미합니다.

--cpu 및 --os 플래그

패키지 선택을 위해 대상 플랫폼을 재정의할 수 있습니다.

bun install --cpu=x64 --os=linux

이것은 현재 시스템 대신 지정된 플랫폼용 패키지를 설치합니다. 크로스 플랫폼 빌드나 다른 환경을 위한 배포를 준비할 때 유용합니다.

--cpu 에 허용되는 값: arm64, x64, ia32, ppc64, s390x

--os 에 허용되는 값: linux, darwin, win32, freebsd, openbsd, sunos, aix

피어 의존성?

피어 의존성은 yarn 과 유사하게 처리됩니다. bun install 은 피어 의존성을 자동으로 설치합니다. 의존성이 peerDependenciesMeta 에서 optional 로 표시된 경우 가능한 경우 기존 의존성이 선택됩니다.

Lockfile

bun.lock 은 Bun 의 lockfile 형식입니다. 텍스트 lockfile 에 대한 블로그 게시물 을 참조하세요.

Bun 1.2 이전에는 lockfile 이 이진수였으며 bun.lockb 라고 불렸습니다. 기존 lockfile 은 bun install --save-text-lockfile --frozen-lockfile --lockfile-only 를 실행한 후 bun.lockb 를 삭제하여 새 형식으로 업그레이드할 수 있습니다.

캐시

캐시를 삭제하려면:

bun pm cache rm
# 또는
rm -rf ~/.bun/install/cache

플랫폼별 백엔드

bun install 은 플랫폼에 따라 의존성을 설치하기 위해 다른 시스템 호출을 사용합니다. 이는 성능 최적화입니다. --backend 플래그로 특정 백엔드를 강제할 수 있습니다.

hardlink 는 Linux 에서 기본 백엔드입니다. 벤치마킹 결과 Linux 에서 가장 빠른 것으로 나타났습니다.

rm -rf node_modules
bun install --backend hardlink

clonefile 는 macOS 에서 기본 백엔드입니다. 벤치마킹 결과 macOS 에서 가장 빠른 것으로 나타났습니다. macOS 에서만 사용할 수 있습니다.

rm -rf node_modules
bun install --backend clonefile

clonefile_each_dir 는 clonefile 과 유사하지만 디렉토리별로 각 파일을 개별적으로 복제합니다. macOS 에서만 사용할 수 있으며 일반적으로 clonefile 보다 느립니다. clonefile 과 달리 하나의 시스템 호출에서 하위 디렉토리를 재귀적으로 복제하지 않습니다.

rm -rf node_modules
bun install --backend clonefile_each_dir

copyfile 는 위 항목 중 하나가 실패할 때 사용되는 폴백이며 가장 느립니다. macOS 에서는 fcopyfile() 을 사용하고 Linux 에서는 copy_file_range() 를 사용합니다.

rm -rf node_modules
bun install --backend copyfile

symlink 는 일반적으로 내부적으로 file: 의존성 (그리고 궁극적으로 link:) 에만 사용됩니다. 무한 루프를 방지하기 위해 node_modules 폴더의 심볼릭 링크를 생성하지 않습니다.

--backend=symlink 로 설치하면 Node.js 는 각 의존성에 자체 node_modules 폴더가 있거나 node 또는 bun 에 --preserve-symlinks 를 전달하지 않는 한 의존성의 node_modules 를 해결하지 않습니다. --preserve-symlinks 에 대한 Node.js 문서 를 참조하세요.

rm -rf node_modules
bun install --backend symlink
bun --preserve-symlinks ./my-file.js
node --preserve-symlinks ./my-file.js # https://nodejs.org/api/cli.html#--preserve-symlinks

npm 레지스트리 메타데이터

Bun 은 NPM 레지스트리 응답을 캐시하기 위해 이진 형식을 사용합니다. 이는 JSON 보다 훨씬 빠르게 로드되며 디스크에서 더 작은 경향이 있습니다. ~/.bun/install/cache/*.npm 에서 이러한 파일을 볼 수 있습니다. 파일명 패턴은 ${hash(packageName)}.npm 입니다. 스코프된 패키지에 대해 추가 디렉토리를 생성할 필요가 없도록 해시입니다.

Bun 의 Cache-Control 사용은 Age 를 무시합니다. 이는 성능을 향상시키지만 Bun 이 npm 에서 최신 패키지 버전 메타데이터를 받는 데 약 5 분 정도 늦어질 수 있음을 의미합니다.

pnpm 마이그레이션

Bun 은 pnpm 에서 bun 으로 프로젝트를 자동으로 마이그레이션합니다. pnpm-lock.yaml 파일이 감지되고 bun.lock 파일이 없는 경우 Bun 은 설치 중에 lockfile 을 bun.lock 으로 자동으로 마이그레이션합니다. 원본 pnpm-lock.yaml 파일은 수정되지 않은 상태로 유지됩니다.

bun install

참고: 마이그레이션은 bun.lock 이 없을 때만 실행됩니다. 현재 pnpm 마이그레이션에 대한 opt-out 플래그가 없습니다.

마이그레이션 프로세스는 다음을 처리합니다.

Lockfile 마이그레이션

• pnpm-lock.yaml 을 bun.lock 형식으로 변환
• 패키지 버전 및 해결 정보 유지
• 의존성 관계 및 피어 의존성 유지
• 무결성 해시가 있는 패치된 의존성 처리

워크스페이스 구성

pnpm-workspace.yaml 파일이 있는 경우 Bun 은 워크스페이스 설정을 루트 package.json 으로 마이그레이션합니다.

packages:
  - "apps/*"
  - "packages/*"

catalog:
  react: ^18.0.0
  typescript: ^5.0.0

catalogs:
  build:
    webpack: ^5.0.0
    babel: ^7.0.0

워크스페이스 패키지 목록과 카탈로그는 package.json 의 workspaces 필드로 이동됩니다.

{
  "workspaces": {
    "packages": ["apps/*", "packages/*"],
    "catalog": {
      "react": "^18.0.0",
      "typescript": "^5.0.0"
    },
    "catalogs": {
      "build": {
        "webpack": "^5.0.0",
        "babel": "^7.0.0"
      }
    }
  }
}

카탈로그 의존성

pnpm 의 catalog: 프로토콜을 사용하는 의존성은 유지됩니다.

{
  "dependencies": {
    "react": "catalog:",
    "webpack": "catalog:build"
  }
}

구성 마이그레이션

다음 pnpm 구성은 pnpm-lock.yaml 과 pnpm-workspace.yaml 모두에서 마이그레이션됩니다.

• Overrides: pnpm.overrides 에서 루트 레벨 overrides 로 package.json 에 이동
• Patched Dependencies: pnpm.patchedDependencies 에서 루트 레벨 patchedDependencies 로 package.json 에 이동
• Workspace Overrides: pnpm-workspace.yaml 에서 루트 package.json 으로 적용

요구 사항

• pnpm lockfile 버전 7 이상 필요
• 워크스페이스 패키지는 package.json 에 name 필드가 있어야 함
• 카탈로그에서 참조하는 모든 의존성은 카탈로그 정의에 존재해야 함

마이그레이션 후 pnpm-lock.yaml 과 pnpm-workspace.yaml 파일을 안전하게 제거할 수 있습니다.

---