Skip to content

How to install Vagrant plugins vagrant-libvirt and vagrant_utm on macos for Apple Silicon

vagrant

Vagrant1 by Hashicorp is a programmatic/IaC wrapper around hypervisors that vagrant calls "providers" and a mechanism to easily manage VM images called "boxes". The default providers included with a vagrant install are Virtualbox, Hyper-V and Docker (Hashicorp also maintains a first party VMware provider but it's a separate installation). Vagrant has a plugin architecture allowing us to install additional providers.

You can install vagrant using Homebrew with brew install vagrant and then list the installed plugins with the command vagrant plugin list.

libvirt

One of the plugin of interest is libvirt2 which is a virtualisation library that normally acts as a user space interface to KVM, but on macOS it is associated with Apple's own Hypervisor.framework3 instead.

Normally installing a plugin in Vagrant is as easy as vagrant plugin install <plugin name>. But for libvirt on macos, extra steps are necessary4.

Just doing the above will get you an error like this:

Failure

Vagrant failed to install the requested plugin because it depends
on development files for a library which is not currently installed
on this system. The following library is required by the 'vagrant-libvirt'
plugin:

  libvirt

If a package manager is used on this system, please install the development
package for the library. The name of the package will be similar to:

  libvirt-dev or libvirt-devel

After the library and development files have been installed, please
run the command again.

Here are the steps to resolve the error:

brew install libvirt
brew services start libvirt
brew install pkgconf iproute2mac
vagrant plugin install vagrant-libvirt

utm

UTM is an hypervisor/emulator for iPad/iPhone5 and macOS6. It's opensource, well integrated in Apple ecosystem and is built on top of QEMU and has an API for programmatic access.

The command to run is vagrant plugin install vagrant_utm. However it seems very finicky about which version of UTM it can work with:

Failure

    The provider 'utm' that was requested to back the machine
'default' is reporting that it isn't usable on this system. The
reason is shown below:

utm_vagrant has detected that you have a version of UTM installed
that is not supported by this version of utm_vagrant. Please install one of
the supported versions listed below to use utm_vagrant plugin:

4.6.5 or earlier

A plugin update may also be available that adds support for the version
you specified. Please check github page of the plugin to download
the latest version.

So I fixed the issue by downloading the exact release number from the UTM project Github release page7, and then tried again the plugin install command.

Final thoughts

Now, running vagrant plugin list should have an output like this:

Success

vagrant-libvirt (0.12.2, global)
vagrant_utm (0.1.3, global)

And here's an example Vagrantfile making use of the utm provider:

Example

Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"
  config.vm.box_version = "202508.03.0"
  config.vm.provider "utm"
end

The vagrant box used here, I found it on Hashicorp's public catalog of vagrant boxes8.

Note

On the box description page at the link above is listed the matrix of architectures and providers that are supported. I was initially only interested in using libvirt which has the benefit of being headless, but the matrix for that box shows that for my architecture (arm64), there is no support for libvirt, hence I looked into installing the utm provider for which an arm64 box is available.

  1. https://developer.hashicorp.com/vagrant ↩

  2. https://libvirt.org ↩

  3. https://developer.apple.com/documentation/hypervisor ↩

  4. https://github.com/vagrant-libvirt/vagrant-libvirt/issues/1205#issuecomment-2560441383 ↩

  5. https://getutm.app ↩

  6. https://mac.getutm.app ↩

  7. https://github.com/utmapp/UTM/releases ↩

  8. https://portal.cloud.hashicorp.com/vagrant/discover/bento/ubuntu-24.04 ↩