bun install

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

基本的な使用方法

bash

bun install react
bun install react@19.1.1 # 特定のバージョン
bun install react@latest # 特定のタグ

bun CLI は、npm、yarn、pnpm の劇的に高速な代替として設計された Node.js 互換のパッケージマネージャーを含んでいます。これはスタンドアロンのツールで、既存の 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 を使用している場合、新しいカーネルをインストールする方法は次のとおりです。

bash

# 5.6 以上のバージョンが返された場合、何もする必要はありません
uname -r

# 公式の Ubuntu ハードウェア有効化カーネルをインストール
sudo apt install --install-recommends linux-generic-hwe-20.04

プロジェクトのすべての依存関係をインストールするには:

bash

bun install

bun install を実行すると:

インストール すべての dependencies、devDependencies、optionalDependencies がインストールされます。Bun はデフォルトで peerDependencies をインストールします。
実行プロジェクトの {pre|post}install および {pre|post}prepare スクリプトが適切なタイミングで実行されます。セキュリティ上の理由から、Bun はインストールされた依存関係のライフサイクルスクリプトを 実行しません。
書き込み bun.lock ロックファイルがプロジェクトルートに書き込まれます。

ログ

ログの冗長性を変更するには:

bash

bun install --verbose # デバッグログ
bun install --silent  # ログなし

ライフサイクルスクリプト

他の npm クライアントとは異なり、Bun はインストールされた依存関係の postinstall のような任意のライフサイクルスクリプトを実行しません。任意のスクリプトを実行することは潜在的なセキュリティリスクを表します。

特定のパッケージのライフサイクルスクリプトを Bun に許可させるには、package.json の trustedDependencies にパッケージを追加します。

json

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

その後、パッケージを再インストールします。Bun はこのフィールドを読み取り、my-trusted-package のライフサイクルスクリプトを実行します。

ライフサイクルスクリプトはインストール中に並列で実行されます。同時実行スクリプトの最大数を調整するには、--concurrent-scripts フラグを使用します。デフォルトは、報告された CPU 数または GOMAXPROCS の 2 倍です。

bash

bun install --concurrent-scripts 5

Bun は、どのスクリプトを実行する必要があるかを決定することで、人気のあるパッケージ（esbuild、sharp など）の postinstall スクリプトを自動的に最適化します。これらの最適化を無効にするには:

bash

BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install

ワークスペース

Bun は package.json の "workspaces" をサポートしています。完全なドキュメントはパッケージマネージャー > ワークスペースを参照してください。

json

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

特定のパッケージの依存関係をインストールする

モノレポでは、--filter フラグを使用して、パッケージのサブセットの依存関係をインストールできます。

bash

# `pkg-c` 以外のすべてのワークスペースの依存関係をインストール
bun install --filter '!pkg-c'

# `./packages/pkg-a` の `pkg-a` のみをインストール
bun install --filter './packages/pkg-a'

bun install でのフィルタリングの詳細については、パッケージマネージャー > フィルタリングを参照してください。

オーバーライドと解決

Bun は package.json 内の npm の "overrides" と Yarn の "resolutions" をサポートしています。これらは メタ依存関係（依存関係の依存関係）のバージョン範囲を指定するメカニズムです。完全なドキュメントはパッケージマネージャー > オーバーライドと解決を参照してください。

json

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

グローバルパッケージ

パッケージをグローバルにインストールするには、-g/--global フラグを使用します。通常、これはコマンドラインツールのインストールに使用されます。

bash

bun install --global cowsay # または `bun install -g cowsay`
cowsay "Bun!"

txt

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

本番モード

本番モード（つまり、devDependencies または optionalDependencies なし）でインストールするには:

bash

bun install --production

再現可能なインストールの場合は、--frozen-lockfile を使用します。これにより、ロックファイルで指定された各パッケージの正確なバージョンがインストールされます。package.json が bun.lock と一致しない場合、Bun はエラーで終了します。ロックファイルは更新されません。

bash

bun install --frozen-lockfile

Bun のロックファイル bun.lock の詳細については、パッケージマネージャー > ロックファイルを参照してください。

依存関係の省略

開発、ピア、またはオプションの依存関係を省略するには、--omit フラグを使用します。

bash

# インストールから "devDependencies" を除外します。これはルートパッケージと
# ワークスペース（存在する場合）に適用されます。推移的な依存関係には
# "devDependencies" が含まれません。
bun install --omit dev

# "dependencies" のみからインストール
bun install --omit=dev --omit=peer --omit=optional

ドライラン

ドライランを実行するには（つまり、実際に何もインストールしない）:

bash

bun install --dry-run

非 npm 依存関係

Bun は Git、GitHub、ローカルまたはリモートでホストされる tarball からの依存関係のインストールをサポートしています。完全なドキュメントはパッケージマネージャー > Git、GitHub、および tarball 依存関係を参照してください。

json

{
  "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 での依存関係の整理方法を決定する 2 つのパッケージインストール戦略をサポートしています。

巻き上げインストール

依存関係を共有 node_modules ディレクトリにフラット化する従来の npm/Yarn アプローチ:

bash

bun install --linker hoisted

分離インストール

ファントム依存関係を防止するための厳格な依存関係の分離を作成する pnpm ライクなアプローチ:

bash

bun install --linker isolated

分離インストールは、node_modules/.bun/ に中央パッケージストアを作成し、トップレベルの node_modules にシンボリックリンクを作成します。これにより、パッケージは宣言された依存関係のみにアクセスできます。

デフォルト戦略

デフォルトのリンカ戦略は、新規作成か既存プロジェクトかによって異なります。

新しいワークスペース/モノレポ: isolated（ファントム依存関係を防止）
新しい単一パッケージプロジェクト: hoisted（従来の npm 動作）
既存のプロジェクト（v1.3.2 より前に作成）: hoisted（後方互換性を保持）

デフォルトはロックファイルの configVersion フィールドによって制御されます。詳細な説明については、パッケージマネージャー > 分離インストールを参照してください。

最小リリース期間

悪意のあるパッケージがすばやく公開されるサプライチェーン攻撃から保護するために、npm パッケージの最小期間要件を構成できます。指定されたしきい値（秒単位）より最近公開されたパッケージバージョンは、インストール中にフィルタリングされます。

bash

# 少なくとも 3 日前に公開されたパッケージバージョンのみをインストール
bun add @types/bun --minimum-release-age 259200 # 秒

bunfig.toml でこれを構成することもできます。

toml

[install]
# 少なくとも 3 日前に公開されたパッケージバージョンのみをインストール
minimumReleaseAge = 259200 # 秒

# 信頼されたパッケージを期間制限から除外
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

最小期間フィルターがアクティブな場合:

新しいパッケージの解決にのみ影響します - bun.lock に既存のパッケージは変更されません
解決中にすべての依存関係（直接および推移的）が期間要件を満たすようにフィルタリングされます
バージョンが期間ゲートによってブロックされた場合、安定性チェックは急速なバグ修正パターンを検出します
- 複数のバージョンが期間ゲートのすぐ外でclose together 公開された場合、フィルターを拡張してそれらの潜在的に不安定なバージョンをスキップし、より古く、より成熟したバージョンを選択します
- 期間ゲートの後最大 7 日間検索しますが、それでも急速なリリースが見つかった場合、安定性チェックを無視します
- 正確なバージョン要求（package@1.1.1 など）は期間ゲートを尊重しますが、安定性チェックをバイパスします
time フィールドのないバージョンは、期間チェックに合格したものとみなされます（npm レジストリは常にタイムスタンプを提供する必要があります）

サービスとの統合やカスタムフィルタリングを含む、より高度なセキュリティスキャンについては、パッケージマネージャー > セキュリティスキャナー API を参照してください。

設定

`bunfig.toml` での `bun install` の設定

bunfig.toml は、bun install、bun remove、bun add で次のパスで検索されます。

$XDG_CONFIG_HOME/.bunfig.toml または $HOME/.bunfig.toml
./bunfig.toml

両方が見つかった場合、結果はマージされます。

bunfig.toml での設定はオプションです。Bun は一般的にゼロ設定を目指していますが、常に可能とは限りません。bun install のデフォルトの動作は bunfig.toml で設定できます。デフォルト値を以下に示します。

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"
# デフォルトはロックファイルの configVersion とワークスペースに依存:
# - configVersion = 1: ワークスペース使用の場合は "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`	認証トークンを設定（現在は機能しません）
`BUN_CONFIG_YARN_LOCKFILE`	Yarn v1 スタイルの yarn.lock を保存
`BUN_CONFIG_LINK_NATIVE_BINS`	package.json の `bin` をプラットフォーム固有の依存関係にポイント
`BUN_CONFIG_SKIP_SAVE_LOCKFILE`	ロックファイルを保存しない
`BUN_CONFIG_SKIP_LOAD_LOCKFILE`	ロックファイルを読み込まない
`BUN_CONFIG_SKIP_INSTALL_PACKAGES`	パッケージをインストールしない

Bun は常にターゲットプラットフォームで利用可能な最速のインストール方法を使用しようとします。macOS では clonefile、Linux では hardlink です。--backend フラグで使用されるインストール方法を変更できます。利用できない場合、またはエラーが発生した場合、clonefile と hardlink はプラットフォーム固有のファイルコピー実装にフォールバックします。

Bun は npm からインストールされたパッケージを ~/.bun/install/cache/${name}@${version} に保存します。セマンティックバージョンに 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 は不足している依存関係を遅延ダウンロードします。node_modules 内の予想される場所に name と version が一致するパッケージが既に存在する場合、Bun は tarball をダウンロードしようとしません。

CI/CD

公式の oven-sh/setup-bun アクションを使用して、GitHub Actions パイプラインで bun をインストールします。

yaml

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 がロックファイルと同期していない場合にビルドを失敗させます。

bash

bun ci

これは bun install --frozen-lockfile と同等です。bun.lock から正確なバージョンをインストールし、package.json がロックファイルと一致しない場合に失敗します。bun ci または bun install --frozen-lockfile を使用するには、bun.lock をバージョン管理にコミットする必要があります。

bun install を実行する代わりに、bun ci を実行します。

yaml

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 値を解決されたパッケージと一緒にロックファイルに保存します。ランタイム時に現在のターゲットに対して無効化されたパッケージのダウンロード、抽出、インストールをスキップします。これは、プラットフォーム/アーキテクチャ間で最終的にインストールされるパッケージが変更された場合でも、ロックファイルが変更されないことを意味します。

`--cpu` および `--os` フラグ

パッケージ選択のターゲットプラットフォームを上書きできます。

bash

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

これにより、現在のシステムの代わりに指定されたプラットフォームのパッケージがインストールされます。クロスプラットフォームビルドや、異なる環境向けのデプロイを準備するときに役立ちます。

--cpu の受け入れ値: arm64、x64、ia32、ppc64、s390x

--os の受け入れ値: linux、darwin、win32、freebsd、openbsd、sunos、aix

ピア依存関係？

ピア依存関係は yarn と同様に処理されます。bun install はピア依存関係を自動的にインストールします。依存関係が peerDependenciesMeta でオプションとしてマークされている場合、既存の依存関係が可能な場合に選択されます。

ロックファイル

bun.lock は Bun のロックファイル形式です。テキストロックファイルに関するブログ投稿を参照してください。

Bun 1.2 より前、ロックファイルはバイナリで bun.lockb と呼ばれていました。古いロックファイルは、bun install --save-text-lockfile --frozen-lockfile --lockfile-only を実行し、その後 bun.lockb を削除することで、新しい形式にアップグレードできます。

キャッシュ

キャッシュを削除するには:

bash

bun pm cache rm
# または
rm -rf ~/.bun/install/cache

プラットフォーム固有のバックエンド

bun install は、プラットフォームに応じて依存関係をインストールするために異なるシステムコールを使用します。これはパフォーマンスの最適化です。--backend フラグで特定のバックエンドを強制できます。

hardlink は Linux でのデフォルトのバックエンドです。ベンチマークでは Linux で最速であることが示されました。

bash

rm -rf node_modules
bun install --backend hardlink

clonefile は macOS でのデフォルトのバックエンドです。ベンチマークでは macOS で最速であることが示されました。macOS でのみ利用可能です。

bash

rm -rf node_modules
bun install --backend clonefile

clonefile_each_dir は clonefile と似ていますが、ディレクトリごとに各ファイルを個別にクローンします。macOS でのみ利用可能で、clonefile よりもパフォーマンスが低下する傾向があります。clonefile とは異なり、これは 1 つのシステムコールでサブディレクトリを再帰的にクローンしません。

bash

rm -rf node_modules
bun install --backend clonefile_each_dir

copyfile は上記のいずれかが失敗した場合のフォールバックで、最遅です。macOS では fcopyfile() を使用し、Linux では copy_file_range() を使用します。

bash

rm -rf node_modules
bun install --backend copyfile

symlink は通常、内部的に file: 依存関係（および最終的には link:）にのみ使用されます。無限ループを防ぐために、node_modules フォルダのシンボリックリンクをスキップします。

--backend=symlink でインストールすると、各依存関係に独自の node_modules フォルダがない限り、または node または bun に --preserve-symlinks を渡さない限り、Node.js は依存関係の node_modules を解決しません。--preserve-symlinks に関する Node.js ドキュメントを参照してください。

bash

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 はインストール中にロックファイルを bun.lock に自動的に移行します。元の pnpm-lock.yaml ファイルは変更されずに残ります。

bash

bun install

注: 移行は bun.lock がない場合にのみ実行されます。現在、pnpm 移行のオプトアウトフラグはありません。

移行プロセスは次のことを処理します。

ロックファイルの移行

pnpm-lock.yaml を bun.lock 形式に変換します
パッケージバージョンと解決情報を保持します
依存関係とピア依存関係の関係を維持します
整合性ハッシュを持つパッチされた依存関係を処理します

ワークスペース設定

pnpm-workspace.yaml ファイルが存在する場合、Bun はワークスペース設定をルートの package.json に移行します。

yaml

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 フィールドに移動されます。

json

{
  "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: プロトコルを使用する依存関係は保持されます。

json

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

設定の移行

次の pnpm 設定は pnpm-lock.yaml と pnpm-workspace.yaml の両方から移行されます。

オーバーライド: pnpm.overrides からルトレベルの overrides に package.json に移動
パッチされた依存関係: pnpm.patchedDependencies からルトレベルの patchedDependencies に package.json に移動
ワークスペースオーバーライド: pnpm-workspace.yaml からルート package.json に適用

要件

pnpm ロックファイルバージョン 7 以上が必要です
ワークスペースパッケージは package.json に name フィールドが必要です
カタログで参照されるすべての依存関係エントリは、カタログ定義に存在する必要があります

移行後、pnpm-lock.yaml と pnpm-workspace.yaml ファイルを安全に削除できます。

基本的な使用方法 ​

Linux ユーザー向け ​

ログ ​

ライフサイクルスクリプト ​

ワークスペース ​

特定のパッケージの依存関係をインストールする ​

オーバーライドと解決 ​

グローバルパッケージ ​

本番モード ​

依存関係の省略 ​

ドライラン ​

非 npm 依存関係 ​

インストール戦略 ​

巻き上げインストール ​

分離インストール ​

デフォルト戦略 ​

最小リリース期間 ​

設定 ​

bunfig.toml での bun install の設定 ​

環境変数での設定 ​

CI/CD ​

プラットフォーム固有の依存関係？ ​

--cpu および --os フラグ ​

ピア依存関係？ ​

ロックファイル ​

キャッシュ ​

プラットフォーム固有のバックエンド ​

npm レジストリメタデータ ​

pnpm からの移行 ​

ロックファイルの移行 ​

ワークスペース設定 ​

カタログ依存関係 ​

設定の移行 ​

要件 ​

基本的な使用方法

Linux ユーザー向け

ログ

ライフサイクルスクリプト

ワークスペース

特定のパッケージの依存関係をインストールする

オーバーライドと解決

グローバルパッケージ

本番モード

依存関係の省略

ドライラン

非 npm 依存関係

インストール戦略

巻き上げインストール

分離インストール

デフォルト戦略

最小リリース期間

設定

`bunfig.toml` での `bun install` の設定

環境変数での設定

CI/CD

プラットフォーム固有の依存関係？

`--cpu` および `--os` フラグ

ピア依存関係？

ロックファイル

キャッシュ

プラットフォーム固有のバックエンド

npm レジストリメタデータ

pnpm からの移行

ロックファイルの移行

ワークスペース設定

カタログ依存関係

設定の移行

要件