Link Search Menu Expand Document

Vagrant-libvirt is a Vagrant plugin that adds a Libvirt provider to Vagrant, allowing Vagrant to control and provision machines via Libvirt toolkit.

Actual version is still a development one. Feedback is welcome and can help a lot :-)


Vagrant-libvirt requires the following:

  • Vagrant
  • Libvirt (and QEMU)
  • GCC and Make (if not using vagrant from your distribution)

Before you start using vagrant-libvirt, please make sure your Libvirt and QEMU installation is working correctly and you are able to create QEMU or KVM type virtual machines with virsh or virt-manager.

See Requirements for guides and details.


  1. Install Vagrant, Libvirt and QEMU for your distribution
    • Ubuntu
    sudo apt-get purge vagrant-libvirt
    sudo apt-mark hold vagrant-libvirt
    sudo apt-get update && \
        sudo apt-get install -y qemu libvirt-daemon-system ebtables libguestfs-tools \
            vagrant ruby-fog-libvirt
    • Fedora
    sudo dnf remove vagrant-libvirt
    sudo sed -i \
        '/^\(exclude=.*\)/ {/vagrant-libvirt/! s//\1 vagrant-libvirt/;:a;n;ba;q}; $aexclude=vagrant-libvirt' \
    vagrant_libvirt_deps=($(sudo dnf repoquery --disableexcludes main --depends vagrant-libvirt 2>/dev/null | cut -d' ' -f1))
    dependencies=$(sudo dnf repoquery --qf "%{name}" ${vagrant_libvirt_deps[@]/#/--whatprovides })
    sudo dnf install --assumeyes @virtualization ${dependencies}
  2. Install the latest release of vagrant-libvirt
    vagrant plugin install vagrant-libvirt

If you encounter any errors during this process, check that you have installed all the prerequisites in Requirements. If you still have issues, see Troubleshooting.

Installation varies based on your operating system or use of upstream vagrant. See our guides for OS-specific instructions.

Initial Project Creation

After installing the plugin (instructions above), the quickest way to get started is to add Libvirt box and specify all the details manually within a config.vm.provider block. So first, add Libvirt box using any name you want. You can find more Libvirt-ready boxes at Vagrant Cloud. For example:

vagrant init fedora/36-cloud-base

Or make a Vagrantfile that looks like the following, filling in your information where necessary. For example:

Vagrant.configure("2") do |config|
  config.vm.define :test_vm do |test_vm| = "fedora/36-cloud-base"

Start VM

In prepared project directory, run following command:

$ vagrant up --provider=libvirt

Vagrant needs to know that we want to use Libvirt and not default VirtualBox. That’s why there is --provider=libvirt option specified. Other way to tell Vagrant to use Libvirt provider is to setup environment variable