Debugging Vagrant with pry-byebug

What to do when running Vagrant with --debug flag is not enough? As Vagrant is nothing else than a Ruby program, you can use famous pry gem together with pry-byebug to debug it. The only thing you need to do to use pry from the Vagrant code base is to make sure it’s installed and available in the Vagrant environment.

Since Vagrant uses Bundler and locks it’s dependencies, you need to first edit its Gemfile, and add all the gems you need. On Fedora, that would be at /usr/share/vagrant/vagrant.gemspec:

$ cat /usr/share/vagrant/vagrant.gemspec
s.add_dependency 'pry'
s.add_dependency 'pry-byebug'

In upstream Vagrant package, look in /opt/vagrant.

Great, now Vagrant can use these gems in its environment, but they are not available. Let’s install them.

We need to install those in the directory that is on the Vagrant’s GEM_PATH:

$ sudo gem install pry pry-byebug --install-dir /usr/share/gems

In Fedora packages, Vagrant can use system gems (but installs plugins to user’s directory as upstream package) so we can install it there. If you are using package from HashiCorp, install them into /opt/vagrant/gems or again in the user directory (~/.vagrant.d/gems).

Once done we can use Pry as we know it and start debugging from any Vagrant source file by inserting:

require 'pry'; binding.pry

Hope that helps!


I wrote a complete guide on web application deployment. Ruby with Puma, Python with Gunicorn, NGINX, PostgreSQL, Redis, networking, processes, systemd, backups, and all your usual suspects.

More →