--- name: "bundle-exec" section: "1" platform: "linux" package: "ruby-bundler" version: "4.0.3-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "macos"] url: "https://new.carta.tech/bundle-exec" --- # bundle-exec(1) Execute a command in the context of the bundle ## NAME **bundle-exec** - Execute a command in the context of the bundle ## SYNOPSIS **bundle exec** \[--gemfile=GEMFILE\] *command* ## DESCRIPTION This command executes the command, making all gems specified in the \[**Gemfile(5)**\]\[Gemfile(5)\] available to **require** in Ruby programs. Essentially, if you would normally have run something like **rspec spec/my\_spec.rb**, and you want to use the gems specified in the \[**Gemfile(5)**\]\[Gemfile(5)\] and installed via bundle [install(1)](/install/1.md) *bundle-install.1.html*, you should run **bundle exec rspec spec/my\_spec.rb**. Note that **bundle exec** does not require that an executable is available on your shell's **$PATH**. ## OPTIONS - **--gemfile=GEMFILE** Use the specified gemfile instead of \[**Gemfile(5)**\]\[Gemfile(5)\]. ## BUNDLE INSTALL --BINSTUBS If you use the **--binstubs** flag in bundle [install(1)](/install/1.md) *bundle-install.1.html*, Bundler will automatically create a directory (which defaults to **app\_root/bin**) containing all of the executables available from gems in the bundle. After using **--binstubs**, **bin/rspec spec/my\_spec.rb** is identical to **bundle exec rspec spec/my\_spec.rb**. ## ENVIRONMENT MODIFICATIONS **bundle exec** makes a number of changes to the shell environment, then executes the command you specify in full. - • make sure that 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: - • disallow loading additional gems not 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 - Finally, **bundle exec** also implicitly modifies **Gemfile.lock** if the lockfile and the Gemfile do not match. Bundler needs the Gemfile to determine things such as a gem's groups, **autorequire**, and platforms, etc., and that information isn't stored in the lockfile. The Gemfile and lockfile must be synced in order to **bundle exec** successfully, so **bundle exec** updates the lockfile beforehand. ### Loading By default, when attempting to **bundle exec** to 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. In a rare few cases, this could cause some subtle side-effects (such as dependence on the exact contents of **$0** or **\_\_FILE\_\_**) and the optimization can be disabled by enabling the **disable\_exec\_load** setting. ### Shelling out Any Ruby code that opens a subshell (like **system**, backticks, or **%x{}**) will automatically use the current Bundler environment. 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 are 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 provides convenience helpers that wrap **system** and **exec**, and they can be used like this: - ``` Bundler.unbundled_system('brew install wget') Bundler.unbundled_exec('brew install wget') ``` - ## RUBYGEMS PLUGINS At present, the Rubygems plugin system requires all files named **rubygems\_plugin.rb** on the load path of *any* installed gem when any Ruby code requires **rubygems.rb**. This includes executables installed into the system, like **rails**, **rackup**, and **rspec**. Since Rubygems plugins can contain arbitrary Ruby code, they commonly end up activating themselves or their dependencies. 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 \**. If your 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), 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. 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**).