How to Use Vagrant: The Beginner's Guide (First Vagrantfile, the Box Rule, First VM, and the Provision Lesson)

CodexFuse Team · 2026-10-29T16:04:26.905Z · 9 min read

Learning how to use Vagrant is the fastest way to get a clean, disposable, and reproducible development VM on your laptop. Vagrant is HashiCorp's open-source tool for building and managing virtual machine environments from a single config file: you describe the VM once in a Vagrantfile, then vagrant up spins up the identical machine on any teammate's laptop. If you are weighing VMs against containers first, our Docker beginner guide draws the line between the two.

What is Vagrant and how does it work?

Vagrant is a command-line tool that automates virtual machine creation. It sits on top of a "provider" — usually VirtualBox — downloads a prebuilt VM image called a box, boots it, shares your project folder into it, and gives you one-command SSH access. Delete it with vagrant destroy and it is gone, with nothing left to haunt your laptop.

The core idea is reproducibility. Your dev environment is defined as code, so "it works on my machine" stops being a joke. You get the same OS, the same installed packages, and the same network settings everywhere the Vagrantfile travels.

How do you use Vagrant? (the 7-step beginner arc)

Here is the complete path from zero to a running VM, in order:

1. Install Vagrant and a provider. Download Vagrant 2.4.9 (current stable, released August 21, 2025, per HashiCorp's CHANGELOG) from the official downloads page, plus VirtualBox 7.2, which 2.4.9 officially supports.
2. Create a project folder and run vagrant init. This writes a starter Vagrantfile.
3. Pick your box and edit the Vagrantfile. Set config.vm.box = "ubuntu/jammy64" — a current build, not a dead one like ubuntu/trusty64 (more on the box rule below).
4. Run vagrant up. Vagrant downloads the box on first use, creates the VM, and boots it.
5. Run vagrant ssh. You are inside your new Linux machine.
6. Share your code. Your project folder is automatically mounted at /vagrant inside the guest.
7. Add provisioning. A few lines of shell in the Vagrantfile install your stack automatically, so the next vagrant up builds the full environment, not just the OS.

Step 1: Install Vagrant and choose your provider

Vagrant does not virtualize anything by itself — it orchestrates a provider that does. HashiCorp ships official installers for macOS, Windows, and Linux, plus a Homebrew tap (brew tap hashicorp/tap && brew install hashicorp/tap/hashicorp-vagrant) and an apt repository for Debian/Ubuntu, per the official downloads page.

Your provider options:

For this guide, use VirtualBox. It is free, and Vagrant 2.4.9 added official support for VirtualBox 7.2, so the pair is current.

Step 2: Run vagrant init and meet the Vagrantfile

Make a folder for your project and initialize it:

mkdir my-vm && cd my-vm
vagrant init

This creates a Vagrantfile — and here is the syntax rule every beginner must internalize: the Vagrantfile is Ruby. It looks like config, but it is a real Ruby script, so do |config| ... end blocks, quotes, and commas are Ruby syntax. Edit it like code, not like an INI file.

The starter file is mostly comments. The line that matters is:

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

Step 3: The box rule — always pin a current box

A box is Vagrant's package format: a prebuilt VM image for one provider. The box rule is simple: never bless a dead box. Most beginner guides online pin ubuntu/trusty64, debian/stretch64, or ubuntu/bionic64 — releases whose support ended years ago and whose boxes no longer receive updates.

Before writing this guide I probed the live Vagrant Cloud API (October 29, 2026): ubuntu/jammy64 (Ubuntu 22.04 LTS) is current at version 20241002.0.0 for VirtualBox, and the multi-provider generic/ubuntu2204 is at v4.3.12. There is no ubuntu/noble64 box at all. Pin ubuntu/jammy64 in your Vagrantfile and you start on a supported, patched base.

Also pin the version, not just the name, so a teammate does not silently get a different image:

config.vm.box = "ubuntu/jammy64"
config.vm.box_version = "20241002.0.0"

Step 4: vagrant up — your first VM boots

Run vagrant up in your project folder. On first run Vagrant downloads the box (a few hundred MB), imports it into VirtualBox, boots it, configures SSH, and mounts your project folder at /vagrant inside the guest. Every later vagrant up just boots the existing VM in seconds.

Then step inside:

vagrant ssh

You are now root-adjacent on a fresh Ubuntu 22.04. The default user is vagrant, and SSH works passwordless because Vagrant injects a keypair automatically. If you generate keys manually for servers elsewhere, our SSH key guide covers the how and why.

Step 5: Synced folders — edit on your laptop, run in the VM

By default Vagrant syncs your project folder into the guest at /vagrant. Edit code with your normal editor on the host; run it inside the VM. This is the workflow the tool is built for: host for editing, guest for running.

The first-troubleshooting lesson: synced folders need the provider's guest additions. If shared folders silently fail, it is almost always a VirtualBox Guest Additions version mismatch — install the vagrant-vbguest plugin (vagrant plugin install vagrant-vbguest) and it rebuilds them automatically on boot.

You can also map extra folders explicitly:

config.vm.synced_folder "./app", "/var/www/app"

Step 6: The provision lesson — make every rebuild automatic

A Vagrantfile without provisioning gives you a fresh OS every rebuild — and then you install everything by hand again. Provisioning is the lesson that makes Vagrant worth it: shell commands (or Ansible, Chef, Puppet) in the Vagrantfile that turn the bare box into your full stack automatically.

config.vm.provision "shell", inline: <<-SHELL
  apt-get update
  apt-get install -y nginx python3
  systemctl enable nginx
SHELL

Provisioners run on the first vagrant up. Force a re-run any time with vagrant provision, or vagrant reload --provision to reboot and reprovision in one move. Make provisioning idempotent — safe to run twice — so rebuilds never break.

Step 7: Managing the VM — suspend, halt, destroy

Vagrant's lifecycle commands each do a different thing, and mixing them up is the classic beginner mistake:

Destroying is safe by design — the Vagrantfile is the source of truth, so vagrant destroy && vagrant up rebuilds the identical machine. That disposability is the whole point.

Vagrant vs Docker vs Lima: which one do you actually need?

Beginners confuse these constantly, so here is the decision table:

The rule of thumb: Vagrant = reproducible VMs as code; Docker = reproducible apps as code. Many teams use both — Vagrant for the dev machine shape, Docker inside it for the services.

If you are running these VMs on rented hardware rather than your laptop, start with what VPS hosting is — the same Vagrant workflow works on a VPS, where the machine is always on.

Common first-day problems and fixes

"The box could not be found." You typo'd the box name or the box was removed — vagrant box list shows what is cached locally, and the Vagrant Cloud search page shows what exists.

Shared folders are empty. Guest Additions mismatch (see Step 5) — install vagrant-vbguest and vagrant reload.

vagrant up hangs at SSH. Usually a host-only network conflict or a firewall blocking the private network Vagrant creates — try vagrant up --debug and check the last SSH lines.

The VM eats your disk. Boxes live in ~/.vagrant.d/boxes and grow with every box you try — vagrant box prune and vagrant box remove <name> clean house.

Sources

• HashiCorp — Vagrant CHANGELOG (GitHub, read October 29, 2026): 2.4.9 stable (August 21, 2025) adds VirtualBox 7.2 support; 2.4.10 unreleased nightly.
• HashiCorp — VMware provider docs (read October 29, 2026): Vagrant VMware plugin now open source under the MPL; VMware Fusion/Workstation are paid third-party products installed separately.
• HashiCorp — Vagrant downloads page (read October 29, 2026): Homebrew tap, apt repository, and binary installers.
• Vagrant Cloud API — live probe October 29, 2026: ubuntu/jammy64 current version 20241002.0.0 (VirtualBox); generic/ubuntu2204 v4.3.12 (multi-provider); no ubuntu/noble64 box exists.
• dev.to/trinitezinsou — "Getting Started with Vagrant" (freshest beginner guide found, ~410 days old): VirtualBox-provider arc with box add/list and vagrant validate.
• dev.to/davidmm1707 — "Vagrant Tutorial for Beginners" (~1,023 days old): full command reference (up/halt/suspend/resume/destroy, box management).
• dev.to/sahilghanwatdev — "Getting started with Vagrant: a beginner's Guide" (~1,162 days old): install → init → Vagrantfile → up → ssh arc.
• xmodulo.com — "How to get started with Vagrant on Linux": suspend/halt/destroy semantics and the default /vagrant shared directory.

Frequently asked questions

Is Vagrant still relevant in 2026 with Docker everywhere?

Yes — for a different job. Docker packages apps; Vagrant packages whole machines. When you need a specific OS, kernel behavior, or systemd services that match production servers, a Vagrant VM is still the right tool, and Docker often runs inside it.

Is Vagrant free?

Vagrant itself is free and open source (BSL/MPL lineage under HashiCorp). VirtualBox and Hyper-V cost nothing; VMware's software is paid, though the Vagrant VMware plugin is now open source.

What is the difference between Vagrant and VirtualBox?

VirtualBox is the hypervisor that runs VMs; Vagrant is the automation layer on top. You could click through VirtualBox manually, but Vagrant turns that into one config file and one command — that is the question this guide answers.

How much RAM should I give a Vagrant VM?

Start with 2 GB for a basic Linux dev box; 4 GB if you run Docker or a database inside it. Set it in the Vagrantfile per provider (e.g. vb.memory = "2048" for VirtualBox) and never allocate more than half your host's RAM.

Can I use Vagrant on Apple Silicon Macs?

Yes — Vagrant 2.4.x supports ARM64 hosts. Use VirtualBox 7.2+ or the VMware provider, and pick an arm64 box (e.g. generic/ubuntu2204, which ships arm64 builds); the x86-only ubuntu/jammy64 box will not boot natively on Apple Silicon.