gemとBundlerの使い方｜Bundler 4系で変わったコマンドとGemfileの書き方

手元の記事どおりに bundle install --path vendor/bundle と打ってエラーで止まる。これは2025年12月3日にリリースされたBundler 4.0.0で、2系の時代に定番だったオプションがまとめて削除されたためです。この記事では、gemとBundlerの役割分担から、Gemfileの書き方、bundle install と bundle exec の使い方までを、実際のコマンド出力とあわせて整理します。4系で動かなくなった書き方とその代替も一覧にしました。掲載しているコマンドの出力は、Ruby 4.0.6・RubyGems 4.0.16・Bundler 4.0.16（macOS / x86_64-darwin23）で実行して採取したものです。

まとめ：gemとBundlerの要点

• gemはライブラリ本体の単位、Bundlerはプロジェクト単位で必要なgemの組み合わせを決めて固定する道具です。
• Gemfileが「欲しいものの条件」、Gemfile.lockが「実際に確定した版」で、チームで共有するのは両方です。
• Bundler 4系は2025年12月3日公開。--path などの記憶されるフラグが全廃され、設定は bundle config set に一本化されました。
• bundle uninstall というコマンドは存在しません。用途に応じて bundle remove、bundle clean、gem uninstall を使い分けます。
• Bundler 4系はRuby 3.2以上が必要です。動作環境が古い場合は先にRuby側を上げる判断になります。

以下、各コマンドが何を書き換えるのかを、出力を見ながら順に確認していきます。

gemとBundlerの役割分担とコマンド名の違い

gemが担う範囲｜ライブラリ本体とRubyGemsの配布基盤

gemはRubyのライブラリを配布・インストールするためのパッケージ形式であり、その単位そのものを指す言葉でもあります。配布先の中心がRubyGems.orgで、gem install を実行するとここから取得してRuby処理系に登録されます。付属コマンドの gem は、この「システム全体のgem棚」を操作する道具だと考えると整理しやすくなるはずです。実際のgemの例としては、Excel操作のRubyXLリファレンス｜主要メソッドとセル・シート操作の使い方【最新3.4系対応】や、HTTPクライアントのFaradayの使い方とタイムアウト設定｜Ruby HTTPクライアントの基本が挙げられます。

$ gem install rake -v 13.2.1
Successfully installed rake-13.2.1
1 gem installed

この方法で入れたgemはRuby全体から見える一方、どのプロジェクトがどの版を必要としているかという情報は残りません。そこを引き受けるのがBundlerです。

Bundlerが担う範囲｜依存解決とバージョン固定

Bundlerとは、Gemfileに書かれた条件から依存関係を解決し、確定した版の組み合わせをGemfile.lockに書き出すツールです。gemだけを使っていると、あるプロジェクトのために入れた新しい版が別のプロジェクトを壊しますが、Bundlerはこれをプロジェクト単位で切り分けます。Bundler自身もgemとして配布されており、RubyGemsと同じバージョン番号で並行してリリースされています。2026年8月時点の最新は4.0.18（2026年8月5日公開）です。

bundleとbundlerの使い分け｜gem名とコマンド名の違い

検索でよく出てくる疑問ですが、両者は同じものを指しています。gemとしての名前が「bundler」、実行するコマンド名が bundle です。bundler という名前でも実行はできますが、公式ドキュメントおよびヘルプの表記は bundle install の形に統一されています。判断に迷う場面はほぼなく、コマンドラインでは bundle と覚えておけば足ります。

Bundlerの導入確認とバージョン特定

導入済みBundlerの版と実体パスの確認

Bundlerは現行のRubyに標準添付されているため、多くの環境では改めてインストールする必要がありません。まず入っているかを確認します。

$ bundle version
4.0.16 (2026-08-10 commit fc18079dba)

$ which bundle
/usr/local/opt/ruby/bin/bundle

$ gem --version
4.0.16

bundle version はコミットハッシュまで表示するため、bundle -v より障害報告に向いています。ここで1つ注意点があります。括弧内の日付はビルド日ではなくコマンドを実行した日です。Bundlerの build_metadata.rb は @built_at が nil のとき現在時刻へフォールバックする実装のため、同じ4.0.16でも実行日によって表示が変わります。上の 2026-08-10 は実行日であり、4.0.16の実際の公開日は2026年7月10日です。版を突き合わせるときはこの日付を根拠にしないでください。

複数のRubyが混在していると、which bundle の結果が意図しない配下を指します。バージョン管理ツールを使った切り分けはrbenvとは何か？RVMとの違いや特徴を徹底解説する基本ガイドで扱っています。インストール済みgemの版を並べて確認したい場合は、gem list にgem名を渡してください。

$ gem list rake
rake (13.4.2, 13.3.1)

このように同じgemの複数版が同居している状態が、次章以降で bundle exec が必要になる理由そのものです。

Ruby 3.2未満で4系が入らない場合の判断

Bundler 4系はRuby 3.2.0以上を必須としています。古いRubyのまま gem install bundler を実行すると、条件を満たす最後の版が入るだけで4系にはなりません。ここでBundlerだけを無理に上げようとするのは避けてください。Ruby 3.1系は既にサポートが終了しており、Bundlerの版ずれではなくRuby本体の更新が本来の課題だからです。現行の安定版は2026年7月14日公開のRuby 4.0.6で、4系の動向はRuby 4.0.1がリリースされました – 新機能満載のRuby 4系に初の安定版パッチが登場しましたにまとめています。

Gemfileの作成とgem行の書き方

bundle initで作る初期Gemfile

プロジェクトのルートで bundle init を実行すると、雛形が生成されます。

$ bundle init
Writing new Gemfile to /private/tmp/myapp/Gemfile

$ cat Gemfile
# frozen_string_literal: true

source "https://rubygems.org"

# gem "rails"

1行目の frozen_string_literal は雛形に含まれるRuby向けのマジックコメントで、Bundlerの設定ではありません。実際に編集するのは source 行と、その下に追記する gem 行です。

バージョン指定演算子の使い分け

gem行の第2引数で許容する版の範囲を決めます。指定を省略すると「解決できる最新版」が選ばれるため、本番運用するプロジェクトでは何らかの範囲を書きます。

迷ったときは ~> を桁数2つ（~> 13.0）で書いておきます。この場合は13.9.9のようなマイナー更新まで許容されるため、新機能の追加を含む版も対象です。修正版だけに絞りたいなら桁数3つ（~> 13.4.2）にしてください。13.5.0以上は対象外になります。

複数sourceの記述｜4系で必須になったブロック形式

社内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をそこから取るのかをブロックで明示する必要があります。

source "https://rubygems.org"

source "https://gems.example.com" do
  gem "internal-tool"
end

gem "rake", "~> 13.0"

この変更は利便性ではなく安全性が目的です。取得元が曖昧だと、社内gemと同名のgemを公開リポジトリに置かれたときに意図しない方を取り込む余地が生まれます。社内向けのsourceを使っているなら、ブロック形式への書き換えは後回しにせず先に済ませてください。

bundle installの実行とGemfile.lockの読み方

install出力に出る依存件数の読み方

bundle install はGemfileの条件を解決し、未取得のgemをインストールしたうえでGemfile.lockを書き出します。以下はGemfileに gem "rake", "13.3.1" と書いた状態での実行結果です。

$ bundle install
Fetching gem metadata from https://rubygems.org/.
Resolving dependencies...
Fetching rake 13.3.1
Installing rake 13.3.1
Bundle complete! 1 Gemfile dependency, 1 gem now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.

「1 Gemfile dependency」がGemfileに自分で書いた数、「1 gem now installed」が依存を含めて実際に入った数です。前者より後者が大きいときは、書いていないgemが依存として引き込まれています。

CHECKSUMS行の役割｜4系の既定変更

生成されたGemfile.lockには、2系までは既定で出力されなかったCHECKSUMSセクションが含まれます。

GEM
  remote: https://rubygems.org/
  specs:
    rake (13.3.1)

PLATFORMS
  ruby
  x86_64-darwin-23

DEPENDENCIES
  rake (= 13.3.1)

CHECKSUMS
  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c

BUNDLED WITH
  4.0.16

4系で lockfile_checksums の既定値が有効に変わったため、確定した版のハッシュ値が記録されるようになりました。同じGemfile.lockから復元した環境で中身が差し替わっていないことを検証できます。Gemfile.lockは生成物だからと .gitignore に入れる運用を見かけますが、アプリケーション開発では誤りです。この検証情報ごと共有されなくなり、環境差の原因が追えなくなります。

導入状態の確認とCI向けfrozen設定

インストール済みかどうかだけを知りたい場面では bundle check が使えます。ネットワーク接続を伴わないため、CIの前段チェックに向いています。

$ bundle check
The Gemfile's dependencies are satisfied

$ bundle list --format=json
{"gems":[{"name":"rake","version":"13.3.1","git_version":null}]}

bundle list --format=json は4.0.0で追加された出力形式で、依存一覧をそのままスクリプトに渡せます。CIではあわせて bundle config set frozen true を設定してください。Gemfile.lockと矛盾する変更があったときにビルドを失敗させられます。

bundle execによる実行gemの固定

bundle exec は、コマンドをGemfile.lockで確定した版の環境で実行します。効果がはっきり現れるのは、システムに複数の版が入っているときです。前章の gem list rake が rake (13.4.2, 13.3.1) を返した状態、つまり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

同じコマンド名でも、呼び出される実体が違います。前者はシステムに入っている最新版、後者はプロジェクトが固定した版です。この差が、手元では通るのに本番やCIで落ちる不具合の典型的な原因になります。Rakeタスクやテスト実行など、プロジェクトの依存に関わるコマンドは bundle exec を付ける前提で運用してください。毎回付けるのが面倒であれば bundle binstubs --all で専用の実行ファイルを生成する方法もあります。

gemの追加・更新・削除に対応するコマンド

bundle addでのGemfile追記

Gemfileを直接編集して bundle install を打つ手順でも構いませんが、bundle add なら追記とインストールをまとめて実行できます。

$ bundle add rack
Fetching gem metadata from https://rubygems.org/..
Resolving dependencies...
Fetching gem metadata from https://rubygems.org/..
Fetching rack 3.2.6
Installing rack 3.2.6

$ grep rack Gemfile
gem "rack", "~> 3.2"

追記される版指定は、取得した版に基づいた ~> 形式です。範囲を変えたい場合はこの行を後から書き換えます。

bundle updateの更新範囲の絞り込み

引数なしの bundle update はGemfileの条件が許す限りすべてのgemを更新するため、意図しない依存まで動きます。更新対象を絞る書き方を使い分けてください。

• bundle update rake：指定したgemとその依存だけを更新
• bundle update --conservative rake：指定gemのみを更新し、依存の版は据え置き
• bundle outdated：更新せずに、新しい版が出ているgemだけを一覧表示

差分を小さく保ちたい運用では、bundle outdated で対象を把握してから個別に更新する順序が扱いやすくなります。

bundle uninstallが存在しない理由と削除手順の使い分け

削除しようとして bundle uninstall を打つと、コマンド自体が見つからないと返ってきます。

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

Bundlerにこのコマンドが無いのは、削除したい対象が場面によって違うためです。次の3つを取り違えると、消したつもりで残る、あるいは他プロジェクトを壊すことになります。

通常の依存整理は bundle remove だけで完結します。危険なのは残る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がシステムから一括で消えます。--dry-run で対象を確認すると、Bundler本体を含む無関係なgemまで並ぶはずです。プロジェクト配下に path を設定していない環境で bundle clean --force を実行するのは避けてください。gem uninstall も同じくRuby全体に効くため、版を -v で明示せずに実行すると、他のプロジェクトが依存している版まで消える可能性があります。

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

2系向けに書かれた手順書やDockerfileをそのまま持ち込むと、この章の内容で止まります。Bundler 4.0.0のリリースノートに挙がっている破壊的変更のうち、実務で踏みやすいものを整理します。

影響が最も大きいのは --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

2系では一度渡したフラグがプロジェクトに記憶され、次回以降は省略しても効き続ける仕組みでした。この暗黙の状態が、手元とCIで挙動が食い違う原因になっていたため、4系では記憶されるフラグが全廃されています。設定は bundle config set で .bundle/config に明示的に書き込む形に一本化されました。

$ bundle config set path 'vendor/bundle'
$ cat .bundle/config
---
BUNDLE_PATH: "vendor/bundle"

なお bundle を引数なしで実行する挙動も移行期にあります。4.0.16の時点では警告を出したうえで bundle install が動きますが、将来的にはヘルプ表示に変わることが予告されています。CIやスクリプトでは省略せず bundle install と明示的に書いてください。挙動を今の時点で確定させたい場合は bundle config set default_cli_command install --global を設定します。

よくある質問

BundleとBundlerの違いは何ですか？

指しているものは同じです。gemとして配布されている名前が「bundler」で、インストール後に実行するコマンド名が bundle です。bundler install と打っても動作しますが、公式ドキュメントやコマンドのヘルプ表示は bundle install の形で統一されているため、こちらに合わせておくと情報を探しやすくなります。Gemfileに書く名前も、CIの設定に書くコマンドも、この対応関係を押さえていれば迷いません。

Rubyのgemとは何ですか？

Rubyのライブラリを配布・インストールするためのパッケージ形式であり、そのパッケージ単位そのものを指す呼び方でもあります。配布基盤がRubyGems.orgで、gem install を実行するとここから取得してRubyに登録されます。Excel操作のRubyXLやHTTPクライアントのFaradayのように、機能ごとに独立したgemが公開されており、必要なものを組み合わせてアプリケーションを構築する形です。gem自体が別のgemに依存することも多く、その依存関係を解決する役割をBundlerが担います。

Gemfileとは何ですか？

プロジェクトで使うgemとその版の条件を記述する設定ファイルで、ルートディレクトリに置きます。bundle init で雛形を生成し、source 行と gem 行を書き足していってください。ここに書くのはあくまで「条件」であり、実際に確定した版はGemfile.lockに記録されます。Gemfileが要求、Gemfile.lockが結果という関係です。両方をバージョン管理に含めて共有することで、他の開発者やCIでも同じ組み合わせを再現できます。

bundle installとgem installはどう使い分けますか？

プロジェクトで使うgemは bundle install、Bundlerに管理させない道具は gem install です。gem install はRuby全体の領域に直接インストールするため、複数プロジェクトを扱っていると版がぶつかります。一方 bundle install はGemfileの条件から依存を解決し、確定した版をGemfile.lockに記録するので、同じ組み合わせを他の環境でも再現できます。アプリケーション開発では原則として bundle install を使い、gem install は環境構築時などに限定してください。

インストール済みのgemを削除するにはどうすればよいですか？

bundle uninstall というコマンドは存在しないため、目的に応じて使い分けます。Gemfileから依存を外すだけなら bundle remove GEM名、未使用gemの実体を消すなら bundle clean、Ruby全体からgemを消すなら gem uninstall GEM名 です。gem uninstall は影響範囲がシステム全体に及ぶため、-v 13.3.1 のように版を明示してください。bundle clean の対象範囲は bundle config set path の設定有無で変わり、未設定の既定構成ではシステム全体が対象になります。この状態で --force を付けるのは危険です。まず --dry-run で対象を確認してください。

Bundlerのバージョンを確認・固定するにはどうすればよいですか？

確認は bundle version で、コミットハッシュを含む詳細が表示されます。プロジェクトで使う版はGemfile.lock末尾のBUNDLED WITH行に記録されており、同じ環境を再現する側のBundlerがこの版に合わせて動きます。特定の版を強制したい場合は環境変数 BUNDLER_VERSION を指定しますが、指定した版が実際にインストールされていないと警告なく既定の版で動くため、gem install bundler -v 版番号 で導入済みかを先に確認してください。なお2026年8月時点の最新は4.0.18で、4系の利用にはRuby 3.2.0以上が必要です。Rubyが古い環境ではBundlerだけを上げても4系にはならないため、先にRuby本体の更新を検討してください。

関連記事

• Ruby 4.0.1がリリースされました – 新機能満載のRuby 4系に初の安定版パッチが登場しました
• rbenvとは何か？RVMとの違いや特徴を徹底解説する基本ガイド
• Faradayの使い方とタイムアウト設定｜Ruby HTTPクライアントの基本
• RubyXLリファレンス｜主要メソッドとセル・シート操作の使い方【最新3.4系対応】
• Rollupとは｜JavaScriptバンドラーのnpm導入から使い方・Webpack/Viteとの違いまで