Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 36 ยท Getting Started

Installing Vagrant and VirtualBox

Install Vagrant and a provider on Windows, macOS and Linux: system requirements, virtualization settings, version checks and fixing the most common setup errors.

Before you can run your first machine you need two things on your computer: Vagrant itself and a provider, the program that really runs virtual machines. The classic pair is Vagrant plus VirtualBox, because VirtualBox is free, runs on all major systems, and is Vagrant's default provider. This lesson walks through the installation on each operating system, shows how to check that everything works, and lists the setup problems people hit most often.

What you need first

  • A 64-bit computer with hardware virtualization turned on. It is called Intel VT-x or AMD-V (sometimes "SVM Mode") in the BIOS/UEFI. Most laptops ship with it enabled, but some have it off.
  • Enough resources. A small Linux VM is happy with 1 to 2 GB of RAM and a few GB of disk, but plan for 8 GB of total RAM on the host if you run anything else.
  • A terminal. PowerShell or Windows Terminal on Windows, Terminal on macOS, any shell on Linux.
  • An Internet connection for the first vagrant up, which downloads a box of several hundred megabytes.

Only one hypervisor can own the virtualization hardware at a time on some systems. On Windows, Hyper-V, WSL 2, Docker Desktop and "Virtual Machine Platform" all use it. VirtualBox can coexist with them on modern versions but runs slower, and old setups may fail with "VT-x is not available". If you hit that, either use Hyper-V as the provider or turn the Windows feature off.

Install on Windows

The simplest route is a package manager. In an elevated PowerShell:

CONSOLE
> winget install Oracle.VirtualBox
> winget install Hashicorp.Vagrant

Chocolatey users can run choco install virtualbox vagrant. You can also download both installers from their official download pages and click through them. A reboot is required after installing Vagrant so that the new PATH entry is picked up; after that open a new terminal.

If you prefer Hyper-V, enable it first (Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All) and then use vagrant up --provider=hyperv from an administrator terminal. The provider lesson shows the settings.

Install on macOS

With Homebrew:

CONSOLE
$ brew install --cask virtualbox
$ brew install --cask vagrant

On Intel Macs VirtualBox works as usual; macOS asks you to allow the Oracle kernel extension in System Settings, Privacy and Security, and you may need to restart. On Apple Silicon (M-series) Macs, VirtualBox only runs ARM guests and many x86 boxes will not boot. Use ARM64 boxes, or a provider such as VMware Fusion or Parallels with the matching Vagrant plugin.

Install on Linux

Debian and Ubuntu users can add HashiCorp's package repository and then install:

CONSOLE
$ sudo apt update && sudo apt install -y virtualbox
$ wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
$ echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
$ sudo apt update && sudo apt install -y vagrant

Fedora and RHEL families use a dnf repository in the same way. Distribution repositories often carry an older Vagrant, so the vendor repository is preferred. On Linux many people use libvirt/KVM instead of VirtualBox; that needs the vagrant-libvirt plugin and is covered in the Providers chapter.

Check the installation

Two version commands prove that the tools are found. The output below is an example; your version numbers will be newer or older.

CONSOLE
$ vagrant --version
Vagrant 2.4.9

$ VBoxManage --version
7.1.12r169651

If the shell answers command not found, the install directory is not on your PATH. Open a fresh terminal, or on Windows sign out and back in. Vagrant checks compatibility between itself and VirtualBox; a message such as "Vagrant has detected that you have a version of VirtualBox that is not supported" means you should install a Vagrant release that lists your VirtualBox version.

flowchart TD
    A["Install a provider (VirtualBox)"] --> B["Install Vagrant"]
    B --> C["Open a NEW terminal"]
    C --> D{"vagrant --version works?"}
    D -- no --> E["Fix PATH, reboot"]
    D -- yes --> F{"VT-x / AMD-V enabled?"}
    F -- no --> G["Enable in BIOS/UEFI"]
    F -- yes --> H["Ready for vagrant up"]

A quick decision path for a clean installation.

Where Vagrant keeps its files

Vagrant stores global data in a hidden folder, ~/.vagrant.d (or %USERPROFILE%\.vagrant.d on Windows). Downloaded boxes live in ~/.vagrant.d/boxes, plugins in ~/.vagrant.d/gems. You can move it by setting the VAGRANT_HOME environment variable, which is handy when your system drive is small. Per-project state, such as the machine ID, lives in a .vagrant folder next to the Vagrantfile; add it to .gitignore.

The runnable stand-in below checks the kind of thing Vagrant itself does at startup: it compares version strings. Ruby's Gem::Version is what Vagrant uses internally for required_version checks, and you will use it in the team workflows chapter to pin a Vagrant version.

Ruby Comparing version requirements (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.

Common installation problems

  • "VT-x is disabled in the BIOS": enable virtualization in firmware settings.
  • "The provider 'virtualbox' could not be found": VirtualBox is not installed or not on PATH; VBoxManage must run in your terminal.
  • Kernel driver errors on Linux: install your kernel headers, then run sudo /sbin/vboxconfig. Secure Boot may block unsigned modules.
  • Host-only network errors: newer VirtualBox restricts host-only ranges; the file /etc/vbox/networks.conf lists the allowed ones. The private network lesson explains this.
  • Slow or hanging boot on Windows: Hyper-V is fighting VirtualBox for virtualization. Pick one.

Keep a note of what you installed. When a teammate says "works for me", the two versions (Vagrant and provider) are the first things to compare.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a provider in Vagrant?

    Providers create and run the VM. Boxes come from a box catalog, scripts are provisioners.
  2. 2. Which command verifies that Vagrant is installed?

    vagrant --version prints the installed version. If the shell cannot find it, the PATH is not set up.
  3. 3. Where does Vagrant store downloaded boxes by default?

    Boxes are global and shared across projects, stored under ~/.vagrant.d/boxes unless VAGRANT_HOME is changed.
  4. 4. Why might an x86 box fail to boot with VirtualBox on an Apple Silicon Mac?

    An ARM host cannot run x86 guests at hardware speed; use ARM64 boxes or another provider.

Summary

  • Install a provider (VirtualBox is the default) and Vagrant, then open a new terminal.
  • Hardware virtualization must be enabled, and other hypervisors can conflict on Windows.
  • vagrant --version and VBoxManage --version confirm a working setup.
  • Global files live in ~/.vagrant.d; per-project state in .vagrant, which belongs in .gitignore.
  • Apple Silicon needs ARM boxes or a different provider.

Next: Your First Vagrant Machine