--- title: "gemとBundlerの使い方｜bundle install・削除・Bundler自身の更新と4系の変更点【4.0.23対応】" url: "https://www.issoh.co.jp/tech/details/4221/" published: 2024-11-15 updated: 2026-11-03 categories: ["Ruby"] publisher: "株式会社一創" --- # gemとBundlerの使い方｜bundle install・削除・Bundler自身の更新と4系の変更点【4.0.23対応】 古い手順書どおりに `bundle install --path vendor/bundle` と打つとエラーで止まります。2025年12月3日公開のBundler 4.0.0で、2系の定番オプションがまとめて削除されたためです。4系はその後も更新が続き、2026年11月3日時点の最新安定版は4.0.23（10月14日公開）、次の4.1は4.1.0.beta3（10月28日公開）まで出ています。この記事では、gemとBundlerの役割分担、Gemfileの書き方、`bundle install` と `bundle exec`、gemの追加・更新・削除、Bundler自身の更新までを、実行結果とあわせて整理します。出力はmacOS上のRuby 4.0.6・Bundler 4.0.23で採取しました。 ## まとめ gemはRubyのライブラリを配る単位で、Bundlerはプロジェクトごとに使うgemの版の組み合わせを決めて固定する道具です。Gemfileに条件を書き、`bundle install` が確定させた版をGemfile.lockに記録します。共有するのは両方です。 gemを外すときは `bundle remove` を使います。`bundle uninstall` というコマンドはありません。`bundle clean` と `gem uninstall` は設定や対象のgem格納先によって他のプロジェクトにも影響するため、使う前に対象を確認してください。 Bundler自身の版を上げるときは `bundle update --bundler=4.0.23` のように版を明示します。Ruby 4.0.6に標準添付の4.0.16で版を付けずに実行すると、ベータ版の4.1.0.beta3がGemfile.lockに書き込まれました（4.0.21で修正済み）。 4系はRuby 3.2以上が必要です。`--path` などの記憶されるフラグは廃止され、設定は `bundle config set` に一本化されました。 ## gemとBundlerの役割分担 ### gemの読み方とRubyGemsの位置づけ gemは「ジェム」と読みます。Rubyのライブラリを配布するパッケージ形式であり、その1つ1つを指す呼び名でもあります。配布元の中心がRubyGems.orgで、付属の `gem` コマンドはRuby全体で共有するgemの置き場を操作します。`-v` には版番号だけでなく範囲も渡せます。 ``` $ gem install rake -v '~> 13.2.0' Successfully installed rake-13.2.1 1 gem installed $ gem list rake rake (13.4.2, 13.3.1, 13.2.1) ``` この方法で入れたgemはどのプロジェクトからも見えますが、どのプロジェクトがどの版を必要としているかは記録されません。同じgemの版が並んでいる上の状態が、Bundlerを使う理由です。なお、RubyGems 4.0で `gem query` は削除され、実行すると `Unknown command query` になります。検索は `gem search`、一覧は `gem list` を使います。 ### bundleとbundlerの違い 同じものです。gemとしての名前が `bundler`、実行するコマンド名が `bundle` です。`bundler install` でも動きますが、公式ドキュメントやヘルプは `bundle install` の形で書かれています。BundlerもRubyGems.orgで配布されるgemの1つで、[RubyGems.orgのbundlerのページ](https://rubygems.org/gems/bundler)で版と公開日を確認できます。4系からはRubyGemsと同じ版番号で同じ日に公開されています。 ## Bundlerの導入確認とバージョンの見方 ### bundle versionの日付が示すもの Bundlerは現行のRubyに標準添付されているので、多くの環境では入れ直す必要がありません。確認は `bundle version` で行います。 ``` $ bundle version 4.0.23 (2026-10-14 commit 642a23e) $ gem list bundler bundler (4.0.23, default: 4.0.16) ``` `gem list` の `default:` がRubyに標準添付された版です。Homebrewで入れたRuby 4.0.6では4.0.16でした。括弧内の日付には注意が要ります。`gem install` で入れた4.0.23は公開日の2026-10-14を表示しましたが、標準添付の4.0.16は実行した日（2026-11-03）を表示しました。ビルド日時が埋め込まれていないとき現在時刻で代用する実装のためです。版の新旧をこの日付で判断しないでください。 複数のRubyが入っている環境では、`which bundle` の結果が意図しない場所を指すことがあります。Rubyの切り替えは[rbenvとは？Rubyバージョン管理の仕組みとRVMとの違い・1.3系の導入手順](/tech/details/7474/)で扱っています。 ### Ruby 3.2未満で4系が入らない場合 Bundler 4系の動作条件はRuby 3.2.0以上です。古いRubyで `gem install bundler` を実行すると、条件を満たす最後の版が入るだけで4系にはなりません。Bundlerだけを無理に上げるのは避けてください。Ruby 3.2は2026年4月1日にサポートが終わっており、本来の課題はRuby本体の更新です。Rubyの現行版と各系列のサポート期限は[Rubyの最新バージョンは4.0.9｜正規表現の脆弱性修正・3系との違い・サポート期限（2026年11月）](/tech/details/10592/)にまとめています。 ## Gemfileの書き方 ### bundle initで作る初期Gemfile ``` $ bundle init Writing new Gemfile to /private/tmp/b4221/app/Gemfile $ cat Gemfile # frozen_string_literal: true source "https://rubygems.org" # gem "rails" ``` 1行目はRubyのマジックコメントで、Bundlerの設定ではありません。 ### バージョン指定演算子の使い分け `gem` 行の第2引数で許す版の範囲を決めます。範囲を省略すると新規解決時には条件を満たす最新版が候補になりますが、既存のGemfile.lockがある通常のインストールではロック済みの版が優先されます。更新時の許容範囲を制御するには、Gemfileにも範囲を書きます。 | 書き方 | 許容範囲 | 向く場面 | | ------------------------------- | -------------- | -------- | | gem “rake” | 制限なし | 試用 | | gem “rake”, “13.3.1” | 13.3.1のみ | 版を完全固定 | | gem “rake”, “\~> 13.0” | 13.0以上14.0未満 | 一般的な指定 | | gem “rake”, “\~> 13.4.2” | 13.4.2以上13.5未満 | 修正版だけ許容 | | gem “rake”, “>= 13.0”, “< 13.5” | 明示した範囲 | 上限を細かく制御 | `~>` は桁数で意味が変わります。`~> 13.0` は13.0以上14.0未満を許すので、13.10.0などのマイナー更新も対象です。修正版だけに絞るなら3桁の `~> 13.4.2` と書きます。 ### 複数のsourceとpathのブロック指定 社内のgemサーバーとRubyGems.orgを併用する構成は、4系で書き方が変わりました。`source` を2行並べると、`bundle install` は次のエラーで止まります。 ``` This Gemfile contains multiple global sources. Each source after the first must include a block to indicate which gems should come from that source ``` 2つ目以降のsourceは、そこから取るgemをブロックで指定します。`path` を単独で書いた場合も `[REMOVED] You can no longer specify a path source by itself.` で止まるので、同じ形に直します。 ``` source "https://rubygems.org" source "https://gems.example.com" do gem "internal-tool" end path "../libs" do gem "my-lib" end ``` 取得元を明示させるのは、社内gemと同じ名前のgemを公開側に置かれたときに取り違えないためです。社内向けのsourceを使っているなら先に書き換えてください。 ## bundle installとGemfile.lock ### install出力の読み方 Gemfileに `gem "rake", "13.3.1"` と `gem "rack", "~> 3.1.0"` を書いて実行した結果です。 ``` $ bundle install Fetching gem metadata from https://rubygems.org/.. Resolving dependencies... Fetching rack 3.1.23 Installing rack 3.1.23 Bundle complete! 2 Gemfile dependencies, 2 gems now installed. ``` 「2 Gemfile dependencies」はGemfileに自分で書いた数、「2 gems now installed」は依存を含めて使う数です。後者のほうが大きければ、書いていないgemが依存として入っています。rake 13.3.1は導入済みだったので取得の行が出ていません。 ### CHECKSUMSとBundler自身のハッシュ 4系で新しく作ったGemfile.lockには、各gemのSHA-256を記録するCHECKSUMSが入ります。4.0.11（2026年4月30日）からは[Bundler自身のハッシュも記録する変更](https://github.com/ruby/rubygems/pull/9366)が入り、通常のgemとして導入したBundlerでは、下のように `bundler` の行も出ます。標準添付のdefault gemだけを使う場合は、自身のチェックサムが新規追加されないことがあります。 ``` CHECKSUMS bundler (4.0.23) sha256=407ba8a1d928f412847f819aa5f8b6aef7c59fb51feb517112af8a165487287b rack (3.1.23) sha256=f4aa63ad9e7afe7c8aeb0916419d09afcc2c9436e133fda7b9c9749a98b67560 rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c BUNDLED WITH 4.0.23 ``` 2系で作った既存のGemfile.lockは、4系で `bundle install` してもCHECKSUMSが足されません。実際にCHECKSUMSを削ったロックファイルで試しても0件のままでした。追加するには `bundle lock --add-checksums` を1回実行してコミットします。Gemfile.lockを `.gitignore` に入れる運用は、アプリケーションでは避けてください。このハッシュごと共有されなくなります。 ### Linuxの本番・CI向けプラットフォームの確認と追加 Macで作ったGemfile.lockの `PLATFORMS` を実測すると、`ruby` と開発機の `x86_64-darwin-23` の2つで、`x86_64-linux` は入っていませんでした。本番やCIがLinuxなら、まずこの欄を確認し、無ければ追加しておくとネイティブ拡張を持つgemの解決がずれません。 ``` $ bundle lock --add-platform x86_64-linux $ sed -n '/PLATFORMS/,/^$/p' Gemfile.lock PLATFORMS ruby x86_64-darwin-23 x86_64-linux ``` ### CIのfrozen設定とbundle check CIでは `bundle config set frozen true` を設定し、Gemfile.lockと食い違う変更があればビルドを落とします。4.0.19以降は警告で済ませず失敗させる動きになり、4.0.23ではGemfileに1行足しただけの状態で `bundle install` も `bundle check` も終了コード16を返しました。 ``` The dependencies in your gemfile changed, but the lockfile can't be updated because frozen mode is set You have added to the Gemfile: * json ``` `bundle check` はネットワークに出ずに導入状態だけを確かめるので、CIの前段に向きます。`bundle list --format=json` を使えば依存一覧をそのままスクリプトに渡せます。 ## bundle execによる実行時のgemバージョン固定 `bundle exec` は、Gemfile.lockで確定した版の環境でコマンドを実行します。違いが出るのは、同じgemの複数の版がシステムに入っているときです。Gemfileで `gem "rake", "13.3.1"` と固定し、システムには13.4.2も入っている状態で比べました。 ``` $ rake --version rake, version 13.4.2 $ bundle exec rake --version rake, version 13.3.1 ``` 前者はシステムの最新版、後者はプロジェクトが固定した版です。テストやRakeタスクのようにプロジェクトの依存を使うコマンドは `bundle exec` を付けて実行してください。毎回付けるのが手間なら `bundle binstubs --all` で専用の実行ファイルを作れます。`rackup` などRackのサーバー起動も同じ考え方で、詳しくは[Rackとは？Rubyのサーバーとアプリをつなぐ仕様・config.ru・ミドルウェアの書き方【Rack 3.2】](/tech/details/5598/)で扱っています。 ## gemの追加・更新・削除のコマンド ### bundle addによるGemfileへの追記 ``` $ bundle add rack Fetching rack 3.2.8 Installing rack 3.2.8 $ grep rack Gemfile gem "rack", "~> 3.2" ``` Gemfileへの追記とインストールが1回で済みます。4.0系の既定では、入った版から `~>` 形式の範囲が書き込まれます。 ### bundle outdatedによる新しいgemバージョンの確認 更新の前に、新しい版が出ているgemを一覧にします。`Requested` 列がGemfileの条件です。 ``` $ bundle outdated Gem Current Latest Requested Groups Release Date rack 3.1.23 3.2.8 ~> 3.1.0 default rake 13.3.1 13.4.2 = 13.3.1 default $ bundle outdated --filter-patch No patch updates to display. ``` 古いgemがあると終了コード1、無ければ0を返すので、CIで検知に使えます。`--filter-patch`・`--filter-minor`・`--filter-major` で更新の幅を絞れます。上の例は2件ともマイナー更新なので、パッチ更新に絞ると何も出ません。 ### bundle updateの更新対象と更新幅の制御 引数なしの `bundle update` は、Gemfileの条件が許す限りすべてのgemを更新します。差分を小さく保つなら、次の順で絞ってください。 - `bundle update rake`：指定したgemとその依存を更新 - `bundle update --conservative rake`：指定したgemだけを更新し、依存の版は据え置く - `bundle update --patch --strict`：パッチ更新に限る 依存の更新を自動でプルリクエストにするなら、[Dependabotとは｜料金は無料・dependabot.ymlの書き方とRenovateとの違い【2026年10月】](/tech/details/6796/)がBundlerに対応しています。 ### gemの削除：bundle remove・bundle clean・gem uninstall `bundle uninstall` を打つと、コマンドが無いと返ります。 ``` $ bundle uninstall rake Could not find command "uninstall". Did you mean? "install" ``` 削除したい対象が場面によって違うためです。次の3つを取り違えると、消したつもりで残るか、他のプロジェクトを壊します。 | 目的 | コマンド | 影響範囲 | | --------------- | ---------------------------- | ------------- | | Gemfileから外す | bundle remove rack | そのプロジェクト | | 使っていないgemの実体を消す | bundle clean | path設定の有無で変わる | | Rubyから消す | gem uninstall rake -v 13.2.1 | Ruby全体 | 通常の整理は `bundle remove` で終わります。Gemfileの該当行を消し、Gemfile.lockも書き換えます。 ``` $ bundle remove rack Removing gems from /private/tmp/b4221/app/Gemfile rack (~> 3.1.0) was removed. ``` 危ないのは残りの2つです。`bundle clean` は、`bundle config set path` でプロジェクト配下を指定していない既定の構成だと、対象がシステム全体のgemになります。Bundlerはそこで止まります。 ``` $ bundle clean Cleaning all the gems on your system is dangerous! If you're sure you want to remove every system gem not in this bundle, run `bundle clean --force`. ``` ここで `--force` を付けると、今のGemfileに無いgemがシステムから一括で消えます。path未設定の環境では実行しないでください。`gem uninstall` もRuby全体に効くので、`-v` で版を指定しないと、他のプロジェクトが使っている版まで消すおそれがあります。 ## Bundler自身の更新とBUNDLED WITH ### BUNDLED WITHで指定された版への自動切り替え Gemfile.lockの末尾にある `BUNDLED WITH` は、そのロックファイルを書いたBundlerの版です。実行中のBundlerと違う版が書かれていると、Bundlerはその版に切り替えて動きます。未導入なら取得してから再起動します。 ``` $ bundle install Bundler 4.1.0.beta3 is running, but your lockfile was generated with 4.0.20. Installing Bundler 4.0.20 and restarting using that version. ``` ロックファイルの版が導入済みなら、このメッセージも出さずに切り替わります。4.0.23を入れても、`BUNDLED WITH` が4.0.16のままのプロジェクトでは4.0.16が動きます（`bundle install --verbose` で `with bundler 4.0.16` と表示されました）。切り替えを止めて実行中の版を使うなら `bundle config set --local version system`（環境変数は `BUNDLE_VERSION=system`）を設定します。チーム全体の版を上げるには、この行を更新します。 ### bundle update –bundlerでベータ版が入る落とし穴 `BUNDLED WITH` を上げるコマンドが `bundle update --bundler` です。ここに、版によって結果が変わる落とし穴があります。`BUNDLED WITH` が4.0.16のプロジェクトで、版を付けずに実行した結果です。 ``` $ tail -2 Gemfile.lock BUNDLED WITH 4.0.16 $ bundle update --bundler Bundle updated! $ tail -2 Gemfile.lock BUNDLED WITH 4.1.0.beta3 ``` ベータ版がロックされ、そのまま導入もされました。以後はプロジェクトの外でも `bundle -v` が4.1.0.beta3を返します。自動切り替えで4.0.16が更新を担当したためで、同じ操作を4.0.23が担当した場合は4.0.23のまま変わりませんでした。プレリリースを選ばない修正は[4.0.21（2026年9月16日）で入った](https://github.com/ruby/rubygems/pull/9869)ものです。Ruby 4.0.6の標準添付は4.0.16なので、ロックファイルが標準添付の版のままのプロジェクトはこの条件に当てはまります。 対策は版を明示することです。`bundle update --bundler=4.0.23` と書けば、実行するBundlerの版に関係なく4.0.23になります。CIやDockerfileで更新を自動化している場合も、版を付けておいてください。 ### BUNDLER\_VERSIONで未導入の版を指定した場合の挙動 環境変数 `BUNDLER_VERSION` で版を指定しても、その版が入っていなければ警告なしで導入済みの最新版が動きます。`BUNDLER_VERSION=4.0.19 bundle -v` は4.0.23を表示し、終了コードは0でした。指定する前に `gem install bundler -v 4.0.19` で導入しておきます。 ## cooldownによる公開直後のバージョンの除外 4.0.13（2026年6月3日）で、公開から指定日数が経っていない版を解決の候補から外す [cooldown](https://github.com/ruby/rubygems/pull/9576) が加わりました。乗っ取られたアカウントから悪意のある版が公開されても、日数を空けていれば取り込む前に取り下げられる可能性が高い、という考え方です。2026年10月30日公開のrack 3.2.8で試しました。 ``` $ bundle install --cooldown 30 Bundle complete! 1 Gemfile dependency, 1 gem now installed. The following gem versions were skipped by the cooldown setting: * rack 3.2.8 (available in 26 days), resolved 3.2.7 instead $ bundle outdated --cooldown 30 Gem Current Latest Requested Groups Release Date rack 3.2.7 3.2.8 (cooldown 26d) >= 0 default ``` cooldownは依存関係の解決時に作用し、既存のGemfile.lockに固定済みの版は除外しません。継続して設定するなら `bundle config set cooldown 7`（環境変数は `BUNDLE_COOLDOWN`）、取得元ごとなら `source "https://rubygems.org", cooldown: 7` と書きます。優先順位はコマンドの `--cooldown`、設定、Gemfileの順で、`0` を渡すとその回だけ無効にできます。 どの環境でも効くわけではありません。cooldownの判定はgemサーバーが版ごとの公開日時を返すことが前提で、返さない古い形式の社内サーバーでは全版が候補に残ると[bundle configのリファレンス](https://guides.rubygems.org/command-reference/bundle-config/)に書かれています。脆弱性の修正版をすぐ入れたい場面とは相反するので、緊急時は `--cooldown 0` で外します。依存の脆弱性の検出は[OSV-Scannerの使い方｜インストール・コマンド・GitHub Actions設定とTrivyとの違い【v2.7.0】](/tech/details/12926/)と組み合わせてください。 ## Bundler 4系で削除・変更された2系のオプション 2系向けの手順書やDockerfileをそのまま使うと、次の書き方で止まります。[RubyGems公式ブログの4系移行ガイド](https://blog.rubygems.org/2025/12/03/upgrade-to-rubygems-bundler-4.html)に挙がっている変更のうち、踏みやすいものです。 | 2系までの書き方 | 4系での挙動 | 代わりの書き方 | | ------------------------- | ------ | --------------------------- | | bundle install –path PATH | エラー | bundle config set path PATH | | bundle install –binstubs | エラー | bundle binstubs –all | | bundle inject | 削除 | bundle add | | bundle viz | 削除 | bundler-graph プラグイン | | sourceを複数行 | エラー | 2つ目以降はブロック | | bundle gem –rubocop | エラー | bundle gem –linter=rubocop | | gem query | 削除 | gem search / gem list | 影響が大きいのは `--path` です。実行すると理由まで表示されます。 ``` $ bundle install --path vendor/bundle The `--path` flag has been removed because it relied on being remembered across bundler invocations, which bundler no longer does. Instead please use `bundle config set path 'vendor/bundle'`, and stop using this flag $ bundle config set path 'vendor/bundle' $ cat .bundle/config --- BUNDLE_PATH: "vendor/bundle" ``` 2系では一度渡したフラグが記憶され、手元とCIの食い違いを生んでいました。4系では設定を `.bundle/config` に明示的に書く形です。RuboCopの導入は[RuboCopとは？読み方・使い方と-a/-Aの違い、.rubocop.yml設定【1.92で実測】](/tech/details/3570/)を参照してください。 引数なしの `bundle` は、4.0.23でも警告を出したうえで `bundle install` を実行しました。リファレンスには既定がヘルプ表示と書かれていますが、実際の動きは警告付きのインストールです。いずれヘルプ表示に変わるので、CIやスクリプトでは `bundle install` と書いてください。今の挙動に固定するなら `bundle config set default_cli_command install --global` を設定します。 ### 4.1.0ベータで変わる既定値 4.1.0.beta3を入れて試すと、`bundle add rack` が `gem "rack", ">= 3.2"` を書き込みました。ソースでも既定が `~>` から `>=` に変わり、従来の書き方には `--pessimistic` を付けます。上限の無い範囲が書き込まれるので、4.1に上げたあとは追記された行を確認してください。[4.1.0.beta1のリリースノート](https://github.com/ruby/rubygems/releases/tag/v4.1.0.beta1)では、このほか `bundle env` から外部ツールの版表示が外れ、beta2以降でgemの依存を差し替える `override` が加わっています。正式版の公開日は告知されていません。 ## よくある質問 ### BundleとBundlerの違いは何ですか？ 同じものです。gemとしての名前が bundler、実行するコマンド名が bundle です。bundler install でも動きますが、公式ドキュメントは bundle install の形で書かれています。 ### gemの読み方は何ですか？ 「ジェム」と読みます。Rubyのライブラリを配布するパッケージの形式と、その1つ1つを指す言葉です。配布元の中心はRubyGems.orgです。 ### インストール済みのgemを削除するにはどうすればよいですか？ bundle uninstall は存在しません。Gemfileから外すなら bundle remove gem名、Ruby全体から消すなら gem uninstall gem名 -v 版 を使います。bundle clean はpath未設定だとシステム全体が対象になるので、–force は付けないでください。 ### Bundlerのバージョンを確認・更新するにはどうすればよいですか？ 確認は bundle version、プロジェクトで使う版はGemfile.lock末尾の BUNDLED WITH です。更新は bundle update –bundler=4.0.23 のように版を明示します。版を付けないと、4.0.20以前のBundlerではベータ版がロックされることがあります。 ### Gemfile.lockのBUNDLED WITHとは何ですか？ そのロックファイルを書いたBundlerの版です。実行中のBundlerと違う版が書かれていると、Bundlerはその版に切り替えて動き、未導入なら取得してから再起動します。 ### gem installでバージョンを指定するにはどうすればよいですか？ gem install rake -v 13.3.1 のように -v で版を渡します。-v ‘\~> 13.2.0’ のように範囲も書けます。プロジェクトで使うgemはGemfileに書いて bundle install で入れてください。 ## 関連記事 - [Rubyの最新バージョンは4.0.9｜正規表現の脆弱性修正・3系との違い・サポート期限（2026年11月）](/tech/details/10592/) - [rbenvとは？Rubyバージョン管理の仕組みとRVMとの違い・1.3系の導入手順](/tech/details/7474/) - [Rackとは？Rubyのサーバーとアプリをつなぐ仕様・config.ru・ミドルウェアの書き方【Rack 3.2】](/tech/details/5598/) - [RuboCopとは？読み方・使い方と-a/-Aの違い、.rubocop.yml設定【1.92で実測】](/tech/details/3570/) - [ruby on rails を vscode で開発する環境構築【2026年版】Ruby LSP・デバッグ・Dev Container](/tech/details/2878/) --- 出典: [gemとBundlerの使い方｜bundle install・削除・Bundler自身の更新と4系の変更点【4.0.23対応】]()（株式会社一創）