Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 36 ยท Getting Started

What Is Vagrant?

Learn what Vagrant is, which problem it solves, how it relates to virtual machines, boxes and providers, and when to choose it over containers.

Every developer has heard "it works on my machine". One laptop has Python 3.9, another has 3.12; one runs Windows, another macOS; the production server runs Ubuntu with a different openssl. Vagrant is a command-line tool that attacks this problem by describing a development machine in a small text file and building it for you, identically, every time.

You write a file called the Vagrantfile, run vagrant up, and a few minutes later you have a real virtual machine running the operating system you asked for, with your project folder mounted inside it and your software installed. Throw it away with vagrant destroy and rebuild it from scratch whenever you like. In this lesson you will learn what Vagrant is made of, what it does and does not do, and when it is the right tool.

The core idea: environment as code

Without Vagrant, a team documents its setup in a wiki page: "install this, then that, then edit these config files". The page goes stale and every person ends up with a slightly different machine. With Vagrant the setup is the file. It lives in the repository next to the code, it is reviewed in pull requests, and a new colleague needs exactly two commands:

CONSOLE
$ git clone https://example.com/team/shop.git
$ cd shop && vagrant up

Vagrant does not create virtual machines itself. It is a manager that talks to other software and gives you one consistent workflow on top of it.

The four building blocks

Vagrantfile Describes the machine
Box A packaged base image
Provider Runs the VM
Provisioner Installs your software

Vagrant glues them together

1 / 2

The vocabulary

  • Vagrantfile: a Ruby file (using a small configuration language) that describes one machine or several. See Vagrantfile basics.
  • Box: a packaged virtual machine image used as the starting point, like a template. Boxes are downloaded once and reused. See Choosing a box.
  • Provider: the software that actually runs the VM: VirtualBox (the default), Hyper-V, VMware, libvirt/KVM, or even Docker.
  • Provisioner: a step that configures the machine after it boots: a shell script, a file copy, Ansible, Puppet, Chef or Docker. See Provisioning.
  • Synced folder: a directory shared between your computer (the host) and the VM (the guest). By default your project folder appears inside the VM as /vagrant.
flowchart LR
    VF["Vagrantfile"] --> V["Vagrant CLI"]
    BOX["Box (base image)"] --> V
    V --> P["Provider (VirtualBox, Hyper-V...)"]
    P --> VM["Running virtual machine"]
    V --> PR["Provisioners"]
    PR --> VM
    HOST["Host project folder"] -. synced folder .-> VM

Vagrant reads the Vagrantfile, fetches a box, asks a provider to start a VM, then runs provisioners inside it.

Vagrant versus containers

Containers (see Docker vs Virtual Machines) share the host kernel and start in a second. A Vagrant machine is a full virtual machine with its own kernel, which is slower and heavier but gives you things containers cannot:

Need Vagrant VM Container
A different kernel or full OS (Windows, BSD, a specific Linux kernel) Yes No, shares host kernel
systemd, services, kernel modules, firewall rules as on a real server Natural Awkward
Starting in under a second No (tens of seconds) Yes
Many instances on a small laptop Limited by RAM Easy

Choose Vagrant when the thing you are developing is a server: an Ansible playbook, a Linux package, a network service that needs a real init system, or a multi-machine lab. Choose containers when you are packaging one application. Many teams use both: Vagrant creates a Linux VM, Docker runs inside it.

Vagrant was created by Mitchell Hashimoto in 2010 and is developed by HashiCorp. Since 2023 it is released under the Business Source License rather than an open-source license; the free CLI is still fine for day-to-day development work. Check the current license text if you plan to embed it in a commercial product.

A first taste of the Vagrantfile

This is a complete, working Vagrantfile (read-only here, because the site cannot run virtual machines):

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"
  config.vm.network "forwarded_port", guest: 80, host: 8080
  config.vm.provision "shell", inline: "apt-get update && apt-get install -y nginx"
end

Three lines of configuration: choose an Ubuntu 24.04 box, make guest port 80 reachable at localhost:8080, install nginx. Because the file is plain Ruby, a Vagrantfile can also use variables, loops and conditions.

The runnable example below is a stand-in that mimics the shape of the DSL so you can see that Vagrant.configure ... do |config| is ordinary Ruby: a block receives a configuration object and sets attributes on it. It is not the real Vagrant.

Ruby A Vagrantfile is just Ruby (stand-in)

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.

Strengths and limits

Vagrant is at its best for local, disposable, repeatable environments. It is not a deployment tool and it is not meant for production. Its limits are practical ones: a VM needs gigabytes of disk and RAM, the first boot downloads a large box, and hardware virtualization must be enabled in your BIOS/UEFI. Apple Silicon Macs need a provider that supports ARM guests; the Troubleshooting chapter of this track covers these cases.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the Vagrantfile describe?

    The Vagrantfile is the environment definition: base box, resources, networking, synced folders and provisioning.
  2. 2. Which component actually runs the virtual machine?

    A provider such as VirtualBox or Hyper-V creates and runs the VM. The box is only the starting image.
  3. 3. When is Vagrant a better fit than a container?

    A Vagrant VM has its own kernel and runs systemd and services like a real server; containers share the host kernel.
  4. 4. Where does your project folder appear inside the guest by default?

    Vagrant syncs the directory holding the Vagrantfile to /vagrant in the guest.

Summary

  • Vagrant builds and manages reproducible virtual machines from a Vagrantfile.
  • The four building blocks are Vagrantfile, box, provider and provisioner.
  • A synced folder shares your project between host and guest (/vagrant by default).
  • Pick Vagrant for server-like, full-OS environments; pick containers for single-app packaging.
  • The environment lives in version control, so every teammate gets the same machine.

Next: Installing Vagrant and VirtualBox