Why do we prepend so many commands with bundle exec? For example:

  • bundle exec rails db:migrate instead of rails db:migrate
  • bundle exec rails test instead of rails test
  • bundle exec rake instead of rake
  • bundle exec rspec spec instead of rspec spec
  • bundle exec rails server instead of rails server
  • bundle exec sidekiq instead of sidekiq
  • bundle exec jekyll serve instead of jekyll serve

Running the command by itself (without the bundle exec) seems to work most of the time so what is difference? Why do we get errors sometimes? Lets dig into why we might need to prepend our commands with bundle exec and what our others options are.

Prerequisite knowledge

What is Bundler

Bundler is a dependency manager tailored for Ruby projects. Its primary role is to ensure the accuracy of gem versions within a given project. Bundler does this by creating a separate environment for each Ruby project on your system so that different projects can require different gem versions wile avoiding conflicts. Bundler allows multiple projects to specify and utilize varying gem versions without encountering conflicts.

The Purpose of bundle exec

The bundle exec command functions by incorporating all the gems specified in the gem version control file within your project folder, known as the Gemfile.lock. These gems are loaded onto the PATH, ensuring they are required before the execution of the subsequent command. Consequently, when you use bundle exec rails test, the command ensures that all the necessary dependencies specified in the project are correctly loaded before proceeding to execute the rails test portion of the command. This mechanism guarantees the proper handling of project-specific dependencies, contributing to the seamless execution of commands within the desired context.

$LOAD_PATH

The LOAD_PATH, also known as $LOAD_PATH, is an array in the Ruby programming language that specifies the directories where Ruby looks for files when requiring or loading them. It helps manage dependencies and ensures that the Ruby interpreter can locate the necessary files and libraries. By manipulating the LOAD_PATH, you can control the order in which directories are searched, which facilitates the organization of project-specific code and external dependencies.

Gemfile.lock

The Gemfile.lock file is used to determine and “lock down” the gem versions that your project is using. It serves as a definitive record, specifying the exact versions of gems employed in your project. When using bundle exec it loads the gems that are specified in your Gemfile.lock taking precedence over any potentially conflicting versions instead of just loading whichever files might be in the global gem repository in your system.

.bundle/config

The .bundle/config file is a configuration file used by Bundler. This file is part of the Bundler configuration and is typically located within your project directory in a subfolder named .bundle.

Here is an example of what the contents of a .bundle/config file might look like:

---
BUNDLE_BIN: "bin"

Common problems

The gems seem to work most of the time

The most frustrating thing about problems caused by not using bundle exec is that they frequently show up for only a small number of developers. If problems show up on some team members computers but not on others then we are getting into harder to debug, time wasting territory.

The source of the problems

When you don’t use bundle exec, Ruby may load a different version than what you have specified in your Gemfile.lock which can lead to conflicts. The gems loaded may not have the methods your code is calling because the loaded code is older or newer than your application code (methods can be added our deprecated). The methods called may also work differently.

The wrong gems might be required

The loaded gems might be different versions than the ones needed. Then you will get this error:

You have already activated i18n 1.8.5, but your Gemfile requires i18n 0.9.5.

Some solutions

Just bundle exec all the time

Prepending Ruby commands with bundle exec will keep a consistent development environment. You will be able to minimize chances of different gem versions causing issues. Ok, you now know why you might do this but we are trying to save time and avoid it so maybe another solution like using an alias is better.

Using an alias

A common solution is to set be as an alias for bundle exec. You can check if you have already set it up (or if you are using be for something else) like this:

$ alias be

If you get nothing back then it is empty and you can use it. Change your .bash_profile file by adding:

# .bash_profile or .zshrc
alias be='bundle exec'

Reload your terminal. Then prepending a command with be should work fine. Example:

$ be rake db:migrate

You can also check the alias by typing:

% alias be
be='bundle exec' # This should be returned

This is a common solution instead of endlessly typing bundle exec.

If changing the .bash_profile didn’t do it then you might be using a different shell. You can find out which like this:

echo $SHELL

Then edit the correct file instead. Here are some common ones.

Bash:
  ~/.bashrc
  ~/.bash_profile

Zsh:
  ~/.zshrc

Fish:
  ~/.config/fish/config.fish

Others:
  Consult the documentation for your specific shell.

Remove all other gems not in use

If you run bundle clean --force then bundler will remove all the gems that are not used in your current gemset which mean no conflicts between gem versions and no need to use bundle exec. Of course if you install other projects again then this will fail. This is not really a recommended option.

Binstubs

Binstubs are executable scripts that are generated by Bundler and contain the paths to the bundled gems for a specific project. By using binstubs, you can avoid the need for bundle exec when running Ruby scripts or commands. Here’s how you can use binstubs:

  1. Generate Binstubs:

Run the following command within your project directory to generate binstubs for the gems specified in your Gemfile:

bundle binstubs --all

This command generates executable scripts for all gems in your Gemfile and places them in the bin/ directory.

  1. Run Commands Using Binstubs:

You can now run commands directly using the binstubs without needing bundle exec. For example:

bin/rails server
  1. Add bin/ to Your PATH:

For convenience, you can add the bin/ directory to your PATH so that you can run binstub commands without specifying the path:

Add the following line to your shell profile file (e.g., ~/.bashrc or ~/.zshrc):

export PATH="./bin:$PATH"

Then, restart your terminal or run source ~/.bashrc (or the appropriate file for your shell) to apply the changes.

  1. Run Commands Without bin/ Prefix:

After adding the bin/ directory to your PATH, you can run commands without the bin/ prefix:

rails server

Note:

Keep in mind that using binstubs effectively creates a project-specific set of executable scripts. This approach can be especially useful in large projects or scenarios where you frequently run commands.

Remember to re-run bundle binstubs –all if your Gemfile changes or if you add/remove gems to ensure that your binstubs are up to date.

Conclusion

I think binstubs is the best way to go. However you might need one of the other solutions if you are working in a group and some sort of compromise solution is the necessary.