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のページで版と公開日を確認できます。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系の導入手順で扱っています。

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月）にまとめています。

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にも範囲を書きます。

~> は桁数で意味が変わります。~> 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自身のハッシュも記録する変更が入り、通常の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】で扱っています。

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月】がBundlerに対応しています。

gemの削除：bundle remove・bundle clean・gem uninstall

bundle uninstall を打つと、コマンドが無いと返ります。

$ bundle uninstall rake
Could not find command "uninstall".
Did you mean?  "install"

削除したい対象が場面によって違うためです。次の3つを取り違えると、消したつもりで残るか、他のプロジェクトを壊します。

通常の整理は 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日）で入ったものです。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 が加わりました。乗っ取られたアカウントから悪意のある版が公開されても、日数を空けていれば取り込む前に取り下げられる可能性が高い、という考え方です。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のリファレンスに書かれています。脆弱性の修正版をすぐ入れたい場面とは相反するので、緊急時は --cooldown 0 で外します。依存の脆弱性の検出はOSV-Scannerの使い方｜インストール・コマンド・GitHub Actions設定とTrivyとの違い【v2.7.0】と組み合わせてください。

Bundler 4系で削除・変更された2系のオプション

2系向けの手順書やDockerfileをそのまま使うと、次の書き方で止まります。RubyGems公式ブログの4系移行ガイドに挙がっている変更のうち、踏みやすいものです。

影響が大きいのは --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で実測】を参照してください。

引数なしの 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のリリースノートでは、このほか 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月）
• rbenvとは？Rubyバージョン管理の仕組みとRVMとの違い・1.3系の導入手順
• Rackとは？Rubyのサーバーとアプリをつなぐ仕様・config.ru・ミドルウェアの書き方【Rack 3.2】
• RuboCopとは？読み方・使い方と-a/-Aの違い、.rubocop.yml設定【1.92で実測】
• ruby on rails を vscode で開発する環境構築【2026年版】Ruby LSP・デバッグ・Dev Container