Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 36 ยท Providers and Plugins

Tuning the VirtualBox Provider

Configure the Vagrant VirtualBox provider: memory, CPUs, names, GUI mode, linked clones, customize commands, extra disks and sensible defaults for your hardware.

VirtualBox is the provider most people start with. Its defaults are conservative, so almost every serious Vagrantfile adjusts a few things: how much memory the guest gets, how many CPU cores, whether a window opens, and how disks are created. This lesson covers the settings that matter and the escape hatch for everything else.

The provider block

All VirtualBox options live inside config.vm.provider "virtualbox". The block receives a provider object, conventionally named vb.

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"

  config.vm.provider "virtualbox" do |vb|
    vb.name   = "myapp-dev"      # name shown in the VirtualBox manager
    vb.memory = 2048             # megabytes
    vb.cpus   = 2
    vb.gui    = false            # true opens the VM console window
  end
end
  • vb.name makes the machine easy to find in the VirtualBox manager. Without it, VirtualBox generates a name from the folder plus a timestamp.
  • vb.memory is the guest RAM in megabytes. Leave your host enough: on a 16 GB laptop, a total of 8 GB across all guests is a comfortable limit.
  • vb.cpus is the number of virtual cores. More is not always faster; give each guest the number it will actually use, and never more than your host's physical cores.
  • vb.gui opens the VirtualBox console window. Use it to watch the boot screen when something hangs before SSH works.

Linked clones: faster and smaller

By default, vagrant up copies the whole box disk for each machine. A linked clone instead stores only the differences from a shared base image, so creation takes seconds and uses far less disk.

Ruby
config.vm.provider "virtualbox" do |vb|
  vb.linked_clone = true
end

Linked clones are ideal for clusters made of identical machines. The trade-off: the base image is shared, so removing the box (vagrant box remove) while clones exist causes trouble, and a clone cannot be moved to another computer as easily as a full copy.

Resources that adapt to the host

A hard-coded vb.memory = 4096 fails on a smaller laptop. You can read the host's resources in Ruby and scale. This version uses the standard etc library for the core count and an environment variable for the override.

Ruby
require "etc"

cpus   = [Etc.nprocessors / 2, 1].max        # half the host cores, at least 1
memory = (ENV["VM_MEMORY"] || 2048).to_i

Vagrant.configure("2") do |config|
  config.vm.provider "virtualbox" do |vb|
    vb.cpus   = cpus
    vb.memory = memory
  end
end

Run with VM_MEMORY=4096 vagrant up when you need more.

The customize escape hatch

Vagrant exposes the common options directly. For anything else, vb.customize passes arguments to the VBoxManage command-line tool. The first element is the command; :id stands for the machine's identifier.

Ruby
config.vm.provider "virtualbox" do |vb|
  vb.customize ["modifyvm", :id, "--ioapic", "on"]
  vb.customize ["modifyvm", :id, "--natdnshostresolver1", "on"]
  vb.customize ["modifyvm", :id, "--audio", "none"]
  vb.customize ["modifyvm", :id, "--graphicscontroller", "vmsvga"]
end

Useful examples:

Option Purpose
--ioapic on Required to use more than one CPU
--natdnshostresolver1 on Let the guest use the host's DNS, which helps behind VPNs
--nictype1 virtio Faster network adapter for supported guests
--cpuexecutioncap 50 Limit the guest to half a core's worth of CPU time
--audio none Avoid audio-device warnings on some hosts

Settings like modifyvm can only be changed while the machine is powered off; Vagrant applies them during boot, which is why they live in the Vagrantfile and not in a shell command after up.

Adding a second disk

The createhd and storageattach commands add a disk. You must create the file once and attach it every time.

Ruby
config.vm.provider "virtualbox" do |vb|
  disk = File.join(__dir__, ".vagrant", "data-disk.vdi")

  unless File.exist?(disk)
    vb.customize ["createhd", "--filename", disk, "--size", 10 * 1024]
  end

  vb.customize ["storageattach", :id,
                "--storagectl", "SCSI",
                "--port", 2,
                "--device", 0,
                "--type", "hdd",
                "--medium", disk]
end

The controller name (SCSI, SATA Controller) depends on the box. Look it up with VBoxManage showvminfo <name> once. Newer Vagrant versions also offer config.vm.disk :disk, size: "10GB", name: "data" which is simpler for supported providers; prefer it when your Vagrant version allows.

Inspecting what VirtualBox sees

When you tune settings, confirm they applied:

TEXT
$ VBoxManage list vms
"myapp-dev" {6f1c2a8e-...}

$ VBoxManage showvminfo myapp-dev --machinereadable | grep -E '^(memory|cpus)='
memory=2048
cpus=2

Use vagrant reload to re-read the Vagrantfile and restart the machine with new settings; changes to the provider block are not applied to a running machine.

A stand-in: turning settings into VBoxManage commands

A vb.customize list is just data that Vagrant turns into command lines. This Ruby program shows that translation, which is a good way to understand what actually happens. It prints the commands instead of running them, so nothing here touches VirtualBox.

Ruby Preview the VBoxManage calls

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.

Two things to notice: :id is replaced by the machine's identifier, and the first-class settings (memory, cpus) become a single modifyvm call. Your own customize lines run after them.

Common mistakes

  • Over-allocating memory. Starting three 4 GB guests on a 8 GB laptop makes everything swap and crawl.
  • Setting cpus above 1 without ioapic. Old boxes may need --ioapic on; most current boxes already set it.
  • Typing customize options that do not exist in your VirtualBox version. Check VBoxManage modifyvm help for your release.
  • Editing the VM in the VirtualBox GUI instead of the Vagrantfile. Those changes are lost the next time you destroy and recreate the machine, and teammates never see them.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does vb.customize ["modifyvm", :id, "--ioapic", "on"] do?

    customize forwards its arguments to VBoxManage; :id is replaced by the machine's identifier.
  2. 2. What is the main benefit of linked clones?

    Linked clones store only differences from the base disk.
  3. 3. You edit vb.memory in the Vagrantfile while the VM is running. What applies the change?

    Reload restarts the machine and re-reads the Vagrantfile, applying the new provider settings.
  4. 4. Why is it better to change VM settings in the Vagrantfile than in the VirtualBox GUI?

    The Vagrantfile is the reproducible source of truth; manual edits are not.

Summary

  • Use config.vm.provider "virtualbox" for name, memory, CPUs and GUI mode.
  • Linked clones create clusters fast and cheaply.
  • Scale resources to the host with plain Ruby, and expose overrides through environment variables.
  • vb.customize reaches any VBoxManage option; apply changes with vagrant reload.

Next: Hyper-V, libvirt and VMware