Command Palette

Search for a command to run...

GitHubGitHub

Vagrant Installation Guide

Install Vagrant 2.4.9, add boxes, manage VirtualBox, VMware, Hyper-V and libvirt providers, share folders and provision machines with Ansible or shell scripts.

Vagrant builds and manages reproducible development environments. One Vagrantfile describes the machine, and Vagrant takes care of creating, provisioning, connecting to and tearing it down.

System Requirements

  • A 64-bit operating system with hardware virtualization enabled (Intel VT-x or AMD-V)
  • 4 GB RAM or more, 2 GB of it available for the guest
  • One of the supported providers:
ProviderNotes
VirtualBoxFree, works everywhere, slower than KVM
libvirt / KVMThe fastest option on Linux
VMware Workstation / FusionGood performance, needs a licence for some features
Hyper-VThe built-in option on Windows
Docker / PodmanContainer-based, no virtual machine

Installation Instructions

Ubuntu / Debian (apt)

# Add the HashiCorp signing key
wget -O - https://apt.releases.hashicorp.com/gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
 
# Add the repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/hashicorp.list
 
# Install Vagrant
sudo apt update
sudo apt install -y vagrant
 
# Install a provider (VirtualBox is the easiest starting point)
sudo apt install -y virtualbox
 
vagrant --version

Verifying the Installation

# Version
vagrant --version
 
# List the providers Vagrant can use
vagrant provider --list

Your First Vagrantfile

# -*- mode: ruby -*-
# vi: set ft=ruby :
 
Vagrant.configure("2") do |config|
  # The box the machine is created from
  config.vm.box = "bento/ubuntu-24.04"
 
  # Provider specific settings
  config.vm.provider "virtualbox" do |vb|
    vb.memory = 4096
    vb.cpus = 2
  end
 
  # A private network so the host can reach the guest
  config.vm.network "forwarded_port", guest: 80, host: 8080
  config.vm.network "private_network", ip: "192.168.56.10"
 
  # Synchronise the project folder into the guest
  config.vm.synced_folder ".", "/vagrant", type: "virtualbox"
 
  # Provision with a shell script
  config.vm.provision "shell", inline: <<-SHELL
    sudo apt-get update
    sudo apt-get install -y nginx
  SHELL
end
# Add the box (downloads it once)
vagrant box add bento/ubuntu-24.04
 
# Validate the configuration
vagrant validate
 
# Create and start the machine
vagrant up
 
# SSH into it
vagrant ssh
 
# Stop it (keeps the disk)
vagrant halt
 
# Destroy it (removes everything)
vagrant destroy -f

Boxes

A box is a pre-built base image. The catalogue lives on Vagrant Cloud.

# Search for a box
vagrant search ubuntu
 
# Add a specific version
vagrant box add bento/ubuntu-24.04 --box-version 20241002
 
# List the boxes you have
vagrant box list
 
# Update a box
vagrant box update

Common Commands

# Global status
vagrant status
 
# SSH details for the connection
vagrant ssh-config
 
# Port forwarding
vagrant port --guest 80
 
# Run a command inside the machine
vagrant ssh -c "systemctl status nginx"
 
# Copy a file in or out
vagrant ssh -c "cat /var/log/syslog"
vagrant copy ./file.txt /tmp/file.txt
 
# Suspend and resume
vagrant suspend
vagrant resume

Provisioning with Ansible

Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"
 
  # Point Vagrant at your Ansible playbooks
  config.vm.provision "ansible" do |ansible|
    ansible.playbook = "playbooks/site.yml"
    ansible.compatibility_mode = "2.0"
    ansible.extra_vars = { vagrant: true }
  end
end
# Re-provision an existing machine
vagrant provision --provision-with ansible

Multi-Machine Environments

Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"
 
  config.vm.define "web" do |web|
    web.vm.hostname = "web"
    web.vm.network "private_network", ip: "192.168.56.10"
  end
 
  config.vm.define "db" do |db|
    db.vm.hostname = "db"
    db.vm.network "private_network", ip: "192.168.56.11"
  end
end
# Bring up everything
vagrant up
 
# Bring up one machine
vagrant up web
 
# Run a command on a specific machine
vagrant ssh db

Choosing a Provider

# List the installed providers
vagrant provider --list
 
# Use a specific provider
vagrant up --provider=libvirt

On Linux, libvirt/KVM is dramatically faster than VirtualBox. On Windows, use Hyper-V. On macOS, VMware Fusion or UTM are the fastest options.

Troubleshooting

Best Practices

  1. Commit the Vagrantfile — it is the definition of the environment.
  2. Pin the box version so every machine starts from the same image.
  3. Provision with code, not with manual steps inside the guest.
  4. Use vagrant destroy -f instead of rm -rf .vagrant — it cleans up properly.
  5. Never commit a .vagrant directory or a *.box file to Git.
  6. Use vagrant box prune regularly to reclaim disk space.
  7. Prefer libvirt/KVM on Linux and Hyper-V on Windows for performance.
  8. Set the memory and CPU count explicitly so the environment is predictable.

Next Steps

Hashicorp Consul

Install Consul 2.0, run a client-server cluster with ACLs and TLS, register services with health checks, and set up service discovery and the service mesh.

Hashicorp Packer

Install Packer 1.16, write HCL2 templates, build machine images for AWS, Azure, GCP and QEMU, and produce signed provenance attestations for your supply chain.