In this tutorial we’ll install vagrant-libvirt on a Mac running macOS (tested on High Sierra and Mojave). vagrant-libvirt is a plugin for Vagrant that allows you to interact with libvirt virtualization hosts, local or remote.

Vagrant can be used to build and manage virtual machines and is useful for development. Vagrant runs most platforms, including the MacBook Air and Raspberry Pi. Libvirt is a “toolkit to manage virtualization platforms” and supports a variety of virtualization backends, including, but not limited to, KVM, QEMU, Xen, VMWare, and LXC.

This tutorial assumes you have a working installation of macOS Mojave (preferably) running on a Mac with Vagrant installed (brew cask install vagrant) and that you have a remote Linux machine with libvirt installed.

Install vagrant-libvirt⌗

It should be straightforward, but due to an upstream bug with ruby-libvirt, you’ll have to jump through some hoops to get it to work.

First, install some required packages using brew:

$ brew install libiconv gcc libvirt

Next, we’ll need to make a note of what version of ruby our Vagrant installation is using (in this case, 2.4.6):

$ /opt/vagrant/embedded/bin/ruby --version

Finally, run this command to install vagrant-libvirt, then we’ll walk through what each line does:

$ CONFIGURE_ARGS='with-ldflags=-L/opt/vagrant/embedded/lib with-libvirt-include=/usr/local/include/libvirt with-libvirt-lib=/usr/local/lib' \
GEM_HOME=~/.vagrant.d/gems/2.4.6 \
GEM_PATH=$GEM_HOME:/opt/vagrant/embedded/gems \
PATH=/opt/vagrant/embedded/bin:$PATH \
vagrant plugin install vagrant-libvirt
  1. CONFIGURE_ARGS passes various flags to the configuration stage of the vagrant-libvirt build, telling it to use the libraries installed with Vagrant and to also use the headers and libraries installed with libvirt
  2. GEM_HOME declares ~/.vagrant.d/gems/2.4.6 (note you need to replace the ruby version here with the one you found in the earlier step) as a variable to be included in GEM_PATH
  3. GEM_PATH is a variable determining where to look for ruby gems; we’re adding our variable $GEM_HOME to it
  4. PATH is a variable determining where to look for binaries, and we’re adding our Vagrant supplied binary path (/opt/vagrant/embedded/bin) to it
  5. Installs the vagrant-libvirt plugin using the environment variables described above

Note that these paths may change in future versions of Vagrant or ruby, or changes to the brew packages

That should do it! You can now start a virtual machine on a libvirt host using Vagrant. Here is an example of how to create and run a Fedora 31 VM on a remote libvirt host:

Vagrant.configure("2") do |config|
  config.vm.box = "fedora/31-cloud-base"
  config.vm.provider :libvirt do |libvirt|
    libvirt.host = "libvirt-host.example.com"
    libvirt.connect_via_ssh = true
  end
end

Last Words⌗

These instructions are derived from work done in an issue over at the vagrant-libvirt repository, especially a comment made by ccosby. Thanks for this! It has helped me a lot!

To learn more, check out these books and links on Vagrant, libvirt and vagrant-libvirt:

Audible has Mac, Linux, and DevOps books. If you sign up using this link, you’ll get 30 days for free! 😀

Good luck!

Revision⌗

2023-08-31 Revised language