From ArchWiki

Vagrant is a tool for managing and configuring virtualised development environments.

Vagrant has a concept of 'providers', which map to the virtualisation engine and its API. The most popular and well-supported provider is Virtualbox; plugins exist for libvirt, lxc, vmware and more.

Vagrant uses a mostly declarative Vagrantfile to define virtualised machines. A single Vagrantfile can define multiple machines.


Install the vagrant package.


Vagrant is configured with environment variables. See the full list of options in the official documentation.

For example, to change the location where vagrant stores it's "potentially large" files, set VAGRANT_HOME to a suitable directory. (The default is ~/.vagrant.d).


Vagrant has a middleware architecture providing support for powerful plugins.

Plugins can be installed with Vagrant's built-in plugin manager. You can specify multiple plugins to install:

$ vagrant plugin install vagrant-vbguest vagrant-share


Note: The libvirt plugin is not compatible with the ruby gems as currently shipped with the vagrant package in the Arch repos (which are up-to-date). This might cause an error such as Vagrant failed to properly resolve required dependencies.

An alternative in order to use this plugin without such issues, is to use the container image via either Podman or Docker, as shown in the official documentation [1].

This plugin adds a libvirt provider to Vagrant. libvirt and related packages (e.g. QEMU) must be installed and configured before using the provider.

To install the plugin, make sure base-devel is installed and libvirtd.service has been started. Then run

$ vagrant plugin install vagrant-libvirt

Once the plugin is installed, the libvirt provider will be available:

$ vagrant up --provider=libvirt

If you have issues with dependency mismatch, the following environment variable can be set to ignore gem versions.


If you have issues building ruby-libvirt, try the following (replace lib with lib64 as needed):

$ CONFIGURE_ARGS='with-ldflags=-L/opt/vagrant/embedded/lib with-libvirt-include=/usr/include/libvirt with-libvirt-lib=/usr/lib' \
   GEM_HOME=~/.vagrant.d/gems \
   GEM_PATH=$GEM_HOME:/opt/vagrant/embedded/gems \
   PATH=/opt/vagrant/embedded/bin:$PATH \
       vagrant plugin install vagrant-libvirt

See [2] for more troubleshooting.


First install lxc from the official repositories, then:

$ vagrant plugin install vagrant-lxc

Next, configure lxc as directed in the official repository. The plugin can now be used with a Vagrantfile like so:

This article or section needs expansion.

Reason: This uses some arbitrary image. Link to a transparent repository or instructions how to build a custom image should be added. (Discuss in Talk:Vagrant)

Vagrant.configure("2") do |config|

    config.vm.define "main" do |config| = ''

        config.vm.provider :lxc do |lxc|
            lxc.customize 'cgroup.memory.limit_in_bytes', '512M'

        config.vm.provision :shell do |shell|
            shell.path = ''

The file should be a shell script beside the Vagrantfile. Do whatever setup is appropriate; for example, to remove puppet, which is packaged in the above box:

rm /etc/apt/sources.list.d/puppetlabs.list
apt-get purge -y puppet facter hiera puppet-common puppetlabs-release ruby-rgen


Provisioners allow you to automatically install software, alter and automate configurations as part of the vagrant up process. The most common provisioner is puppet.

Base Boxes for Vagrant

Here is a list of places to get all sorts of vagrant base boxes for different purposes: development, testing, or even production.

  • Vagrant Cloud is HashiCorp's official site for Vagrant boxes. You can browse user-submitted boxes or upload your own. A single Vagrant Cloud box can support multiple providers with versioning.
  • Bento is a project that encapsulates Packer templates for building Vagrant base boxes. A subset of templates are built and published to the bento org on Vagrant Cloud.
  • Vagrant Ubuntu Cloud Images—It has been there since Jan, 2013. For some reason Canonical has NOT officially promoted it yet, may be still in beta. Remember these are vanilla images, NOT very useful without Chef or Puppet.


No ping between host and vagrant box (host-only networking)

Sometimes there are troubles with host-only networking not functioning. Host have no ip on vboxnet interface, host cannot ping vagrant boxes and cannot be pinged from them. This is solved by installing good old net-tools as mentioned in this thread by kevin1024

Virtual machine is not network accessible from the Arch host OS

As of version 1.8.4, Vagrant appears to use the deprecated route command to configure routing to the virtual network interface which bridges to the virtual machine(s). If route is not installed, you will not be able to access the virtual machine from the host OS due to the lack of suitable route. The solution, as mentioned above, is to install the net-tools package, which includes the route command.

'vagrant up' hangs on NFS mounting (Mounting NFS shared folders...)

Installing nfs-utils package may solve this problem.

Make sure the connection is not blocked by iptables or nftables. If you are using libvirt along with firewalld, enable nfs (nfs3), rpc-bind and mountd for the libvirt zone.

Mounting NFS shared folders: mount.nfs: requested NFS version or transport protocol is not supported

Install the nfs-utils package. Enable (v3 and) UDP support by editing /etc/nfs.conf and uncommenting the following lines:


Restart nfs-server.service to apply the changes immediately.

Error starting network 'default': internal error: Failed to initialize a valid firewall backend

Most likely the firewall dependencies were not installed. Install the iptables-nft and dnsmasq packages and restart the libvirtd.service unit.

Unable to ssh to vagrant guest

Check that virtualization is enabled in your BIOS. Because vagrant reports that the vm guest is booted, you would think that all was well with virtualization, but some vagrant boxes (e.g. tantegerda1/archlinux) allow you to get all the way to the ssh stage before the lack of cpu virtualization capabilities bites you.

Could not get preferred machine for domain

Error while creating domain: Error saving the server: Call to virDomainDefineXML failed: could not get preferred machine for domain

Check that virtualization is enabled in your BIOS.

See also