BUNDLE-EXEC(1)

💖 BUNDLE-EXEC — bestie edition 💖

okay so this is the bundle-exec page from the General Commands Manual (section 1, obviously) and it's literally the glow-up your Ruby project needed. buckle up 🎀

---

✨ NAME ✨

bundle-exec — run a command inside the context of your bundle, no cap 💅

---

🌸 SYNOPSIS 🌸

bundle exec [--gemfile=GEMFILE] command

---

🦋 DESCRIPTION 🦋

so what this does is it runs your command, but it makes every single gem listed in the [Gemfile(5)][Gemfile(5)] available to require inside your Ruby programs. it's giving "everyone's invited to the party and they all showed up on time" ✨

basically — say you'd normally just run something like rspec spec/my_spec.rb, but you want the gems from your [Gemfile(5)][Gemfile(5)] that you installed with bundle install(1) (bundle-install.1.html)? then you run:

bundle exec rspec spec/my_spec.rb

and it just works. periodt.

lowkey important: bundle exec does not require that an executable actually be available on your shell's $PATH. it does not care. it will find it. main character energy fr fr 👑

---

💅 OPTIONS 💅

• --gemfile=GEMFILE — use GEMFILE instead of the [Gemfile(5)][Gemfile(5)], because sometimes you're feeling spicy and want a different one 🍓

---

🎀 BUNDLE INSTALL --BINSTUBS 🎀

if you use the --binstubs flag with bundle install(1) (bundle-install.1.html), Bundler will automatically make a directory for you (it defaults to app_root/bin) that contains all the executables available from the gems in your bundle. automatic. iconic. no effort required 💖

so after you've used --binstubs, this:

bin/rspec spec/my_spec.rb

is identical to this:

bundle exec rspec spec/my_spec.rb

same thing, different font 🫶

---

🌈 ENVIRONMENT MODIFICATIONS 🌈

bundle exec makes a whole bunch of changes to your shell environment, and then runs the command you gave it in full. it's a whole makeover montage 💄

• make sure it's still possible to shell out to bundle from inside a command invoked by bundle exec (using $BUNDLE_BIN_PATH)
• put the directory containing executables (like rails, rspec, rackup) for your bundle on $PATH
• make sure that if bundler is invoked in the subshell, it uses the same Gemfile (by setting BUNDLE_GEMFILE)
• add -rbundler/setup to $RUBYOPT, which makes sure that Ruby programs invoked in the subshell can see the gems in the bundle

it also modifies Rubygems, which is a lot of power tbh:

• disallow loading additional gems that aren't in the bundle
• modify the gem method to be a no-op if a gem matching the requirements is in the bundle, and to raise a Gem::LoadError if it's not
• Define Gem.refresh to be a no-op, since the source index is always frozen when using bundler, and to prevent gems from the system leaking into the environment
• Override Gem.bin_path to use the gems in the bundle, making system executables work
• Add all gems in the bundle into Gem.loaded_specs

and finally, bundle exec also implicitly modifies Gemfile.lock if the lockfile and the Gemfile do not match. because Bundler needs the Gemfile to figure out things like a gem's groups, autorequire, and platforms, etc., and that info isn't stored in the lockfile. the Gemfile and lockfile must be synced for bundle exec to succeed, so bundle exec updates the lockfile beforehand. not me doing chores for you before we go out 🙈

---

🧚 Loading 🧚

by default, when bundle exec is pointed at a file with a ruby shebang, Bundler will Kernel.load that file instead of using Kernel.exec. for the vast majority of cases, this is a performance improvement — we love a speed boost ⭐

but in a rare few cases, this could cause some subtle side-effects (like depending on the exact contents of $0 or __FILE__) 😭 and the optimization can be disabled by enabling the disable_exec_load setting. iykyk.

---

🐚 Shelling out 🐚

any Ruby code that opens a subshell (like system, backticks, or %x{}) will automatically use the current Bundler environment. convenient!

if you need to shell out to a Ruby command that is not part of your current bundle, use the with_unbundled_env method with a block. any subshells created inside the block will be given the environment present before Bundler was activated. for example, Homebrew commands run Ruby, but don't work inside a bundle:

Bundler.with_unbundled_env do
  `brew install wget`
end

using with_unbundled_env is also necessary if you're shelling out to a different bundle. any Bundler commands run in a subshell will inherit the current Gemfile, so commands that need to run in the context of a different bundle also need to use with_unbundled_env.

Bundler.with_unbundled_env do
  Dir.chdir "/other/bundler/project" do
    `bundle exec ./script`
  end
end

Bundler also provides convenience helpers that wrap system and exec, and you can use them like this:

Bundler.unbundled_system('brew install wget')
Bundler.unbundled_exec('brew install wget')

go off 🫶

---

💜 RUBYGEMS PLUGINS 💜

at present, the Rubygems plugin system requires all files named rubygems_plugin.rb on the load path of any installed gem whenever any Ruby code requires rubygems.rb. and yes, this includes executables installed into the system, like rails, rackup, and rspec. messy behaviour honestly 💀

since Rubygems plugins can contain arbitrary Ruby code, they commonly end up activating themselves or their dependencies. chaos.

for instance, the gemcutter 0.5 gem depended on json_pure. if you had that version of gemcutter installed (even if you also had a newer version without this problem), Rubygems would activate gemcutter 0.5 and json_pure <latest>.

if your [Gemfile(5)][Gemfile(5)] also contained json_pure (or a gem with a dependency on json_pure), the latest version on your system might conflict with the version in your [Gemfile(5)][Gemfile(5)], or the snapshot version in your Gemfile.lock. 😭

if this happens, bundler will say:

You have already activated json_pure 1.4.6 but your Gemfile
requires json_pure 1.4.3. Consider using bundle exec.

in this situation, you almost certainly want to remove the underlying gem with the problematic gem plugin. in general, the authors of these plugins (in this case, the gemcutter gem) have released newer versions that are more careful in their plugins. good for them, honestly 🌸

you can find a list of all the gems containing gem plugins by running

ruby -e "puts Gem.find_files('rubygems_plugin.rb')"

at the very least, you should remove all but the newest version of each gem plugin, and also remove all gem plugins that you aren't using (gem uninstall gem_name). declutter queen 👑

---

⚠️ real talk: those plugin conflicts and the lockfile-syncing thing are the parts that will actually bite you. read them twice bestie.

---

and that's the whole page!! this came out of the General Commands Manual, and the footer says April 2026 — so yeah, she's fresh, she's current, and she's BUNDLE-EXEC(1). slay 💅✨🎀