Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Providers and Plugins

Vagrant Providers Overview

Understand what a Vagrant provider is, how the box and provider must match, how to choose one, and how to write one Vagrantfile that works with several providers.

Vagrant does not run virtual machines itself. It is an orchestrator: it reads your Vagrantfile and asks another program to do the real work. That program is called a provider. VirtualBox is the default, but Vagrant supports several others, and choosing the right one affects speed, features and which boxes you can use.

What a provider does

When you run vagrant up, Vagrant resolves three things: the box (the base image), the provider (the software that runs it) and your configuration. The provider creates the machine, starts it, configures the network adapters and shared folders, and later stops or deletes it.

One Vagrantfile, many engines

Vagrantfile Describes the machine
Vagrant Orchestrates the steps
Provider Runs the machine

Vagrant talks to the provider through plugins.

1 / 3

Providers are matched to boxes

A box is built for one or more providers, and its metadata says which. A VirtualBox box contains a .vmdk-style disk and VirtualBox settings; a libvirt box holds a qcow2 disk. You cannot start a VirtualBox box with libvirt.

TEXT
$ vagrant box list
ubuntu/jammy64    (virtualbox, 20240101.0.0)
generic/ubuntu2204 (libvirt, 4.3.12)
generic/ubuntu2204 (virtualbox, 4.3.12)
generic/ubuntu2204 (hyperv, 4.3.12)

The listing shows the provider in parentheses, and the same name can be stored once per provider. Boxes that publish several providers, such as the generic/* family, are the easiest choice for cross-platform teams.

Choosing a provider

Provider Host OS Cost Strengths Watch out for
VirtualBox Windows, macOS, Linux Free Default, most boxes, easy networking Slower disk; conflicts with other hypervisors
VMware (Fusion, Workstation) Windows, macOS, Linux Paid plugin and license Fast graphics and disk Licensing, plugin cost
Hyper-V Windows Pro/Enterprise Included Built in, works with WSL 2 Network and shared-folder limits
libvirt (KVM) Linux Free Near-native speed Needs a plugin and system setup
Docker Linux, macOS, Windows Free Starts in seconds A container, not a full VM
Parallels macOS (Apple silicon) Paid Native on Apple silicon License and plugin

On Apple silicon Macs, VirtualBox only runs ARM guests and is limited, so use Parallels, VMware Fusion or Docker, and pick boxes built for arm64.

Selecting a provider

Order of precedence, strongest first:

  1. The --provider flag: vagrant up --provider=libvirt
  2. The VAGRANT_DEFAULT_PROVIDER environment variable
  3. The first usable provider Vagrant detects, with VirtualBox preferred when installed
TEXT
$ VAGRANT_DEFAULT_PROVIDER=hyperv vagrant up
$ vagrant up --provider=virtualbox

A machine remembers its provider in .vagrant/machines/<name>/<provider>/. Switching later means destroying the machine first, because the same name cannot be backed by two engines at once without confusion.

One Vagrantfile, several providers

Provider-specific settings live in config.vm.provider blocks. Vagrant runs only the block for the active provider and ignores the rest, so one file can serve a mixed team.

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "generic/ubuntu2204"
  config.vm.hostname = "app"

  config.vm.provider "virtualbox" do |vb|
    vb.memory = 2048
    vb.cpus = 2
  end

  config.vm.provider "libvirt" do |lv|
    lv.memory = 2048
    lv.cpus = 2
  end

  config.vm.provider "hyperv" do |hv|
    hv.memory = 2048
    hv.cpus = 2
  end
end

The setting names differ a little between providers (vb.memory versus lv.memory), which is why each has its own block. Settings outside any block, such as config.vm.hostname, are universal.

A stand-in: resolving the active provider

This Ruby program imitates how a Vagrantfile picks settings per provider and shows the precedence rules above. It is a model, not Vagrant.

Ruby Provider selection model

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Only the active provider's block runs. That is why you can safely keep every provider's tuning in one file.

Installing and checking providers

TEXT
$ vagrant plugin install vagrant-libvirt     # KVM/libvirt
$ vagrant plugin install vagrant-vmware-desktop
$ vagrant box add generic/ubuntu2204 --provider=libvirt
$ vagrant up --provider=libvirt

VirtualBox and Hyper-V are bundled, the others come as plugins. See Vagrant plugins for how to manage them.

Common mistakes

  • Running two hypervisors at once. VirtualBox and Hyper-V (or WSL 2 with certain settings) can conflict on Windows. Pick one for a session.
  • Expecting a box to work everywhere. Check the provider next to the box name in vagrant box list.
  • Switching providers without destroying. The old machine's metadata gets in the way.
  • Using a provider-specific option outside its block. vb.memory only exists inside the VirtualBox block.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a Vagrant provider?

    Vagrant orchestrates; the provider creates and runs the machine.
  2. 2. Which has the highest precedence when choosing a provider?

    The command-line flag overrides the environment variable, which overrides auto-detection.
  3. 3. What happens to config.vm.provider blocks for providers that are not active?

    Only the block that matches the active provider is applied, so one Vagrantfile can serve several providers.
  4. 4. Why can you not start a VirtualBox-only box with libvirt?

    A box is built for specific providers; its disk image format and metadata must match.

Summary

  • A provider runs the machine; Vagrant only coordinates it.
  • Boxes are provider-specific; check the provider in vagrant box list.
  • Choose by host OS and needs: VirtualBox for general use, Hyper-V on Windows, libvirt on Linux, Docker for speed.
  • Use config.vm.provider blocks to keep several providers' settings in one Vagrantfile.

Next: Tuning the VirtualBox provider