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.
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 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,
$ /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
CONFIGURE_ARGSpasses various flags to the configuration stage of the
vagrant-libvirtbuild, telling it to use the libraries installed with
Vagrantand to also use the headers and libraries installed with
~/.vagrant.d/gems/2.4.6(note you need to replace the
rubyversion here with the one you found in the earlier step) as a variable to be included in
GEM_PATHis a variable determining where to look for
rubygems; we’re adding our variable
PATHis a variable determining where to look for binaries, and we’re adding our
Vagrantsupplied binary path (
/opt/vagrant/embedded/bin) to it
- Installs the
vagrant-libvirtplugin using the environment variables described above
Note that these paths may change in future versions of
ruby, or changes to the
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
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
To learn more, check out these books and links on Vagrant,
- Vagrant documentation
- Vagrant: Up and Running: Create and Manage Virtualized Development Environments
- Hands-On DevOps with Vagrant: Implement End-to-End DevOps and Infrastructure Management using Vagrant
- Virtualization Essentials
2023-08-31 Revised language