Vagrant Tutorial: Learn Dev Environments from Scratch (2026)
I used to set up development environments by writing wiki pages with installation steps. A new developer would spend two days configuring their machine. Vagrant solved this by treating development environments as code with a single Vagrantfile.
By the end of this tutorial, you will be able to create and share portable development environments, synchronize code between host and guest, provision software automatically, and debug common Vagrant issues.
Vagrant Basics and Your First Box
Vagrant uses boxes as base images. vagrant init creates a Vagrantfile. vagrant up downloads the box, creates a VM, and starts it. vagrant ssh opens a shell. Shared folders sync your project directory into the VM at /vagrant by default. Provider-specific configuration controls CPU and memory.
vagrant init ubuntu/jammy64
vagrant up
vagrant ssh
vagrant halt
vagrant destroy -fProvisioning: Shell, Ansible, and Puppet
Provisioners run setup scripts after the VM boots. The shell provisioner runs inline commands or script files. The Ansible provisioner runs playbooks with auto-generated inventory. Multiple provisioners run in declared order. The --provision flag forces provisioning on an already-running VM.
config.vm.provision "shell", inline: <<-SHELL
apt-get update
apt-get install -y nginx
SHELL
config.vm.provision "ansible" do |ansible|
ansible.playbook = "playbooks/dev.yml"
endNetworking: Port Forwarding and Private Networks
Port forwarding maps host to guest ports. Private networking assigns a host-only IP. Public networking bridges to the physical network. I use private networking for multi-machine environments. auto_correct resolves port conflicts by incrementing the port number.
config.vm.network "forwarded_port", guest: 80, host: 8080
config.vm.network "private_network", ip: "192.168.33.10"
config.vm.network "public_network", ip: "192.168.1.100"Synced Folders and File Sharing
Synced folders keep code in sync. Default VirtualBox shared folders work everywhere. NFS is faster on Linux/macOS. SMB is faster on Windows. rsync provides one-way sync. Type parameter selects the method. mount_options controls file permissions.
config.vm.synced_folder ".", "/vagrant", type: "nfs"
config.vm.synced_folder "..", "/shared", type: "rsync", rsync__exclude: ["node_modules/"]Multi-Machine Environments
Vagrant supports multiple VMs in a single Vagrantfile. Each VM gets its own box, provisioners, and networking. I set up web, API, and database as separate machines. Primary machine designation lets vagrant ssh default to the web server.
config.vm.define "web", primary: true do |web|
web.vm.box = "ubuntu/jammy64"
web.vm.network "private_network", ip: "192.168.50.10"
endBox Management, Plugins, and Best Practices
Plugins extend Vagrant: vagrant-vbguest installs Guest Additions, vagrant-hostmanager updates /etc/hosts. Best practices include: pin box versions, avoid secrets in Vagrantfile, keep Vagrantfiles in version control, and add .vagrant to .gitignore.
vagrant plugin install vagrant-vbguest vagrant-hostmanager
vagrant box list
vagrant box prune
vagrant package --output myapp.boxFrequently Asked Questions
What is the difference between Vagrant and Docker Compose?
Vagrant manages full VMs with stronger isolation. Docker Compose manages multi-container applications sharing the host kernel. Many teams use both: Vagrant for the VM and Docker inside it for services.
Can Vagrant be used in CI/CD?
Yes, with the Docker provider instead of VirtualBox. The vagrant-libvirt plugin works with KVM-based runners. Cloud provider plugins provision real VMs for CI.
How do I share a Vagrant environment?
Commit the Vagrantfile and provisioning scripts to Git. Team members clone and run vagrant up. For custom boxes, publish to Vagrant Cloud or a private registry.
What is the difference between vagrant halt and vagrant destroy?
halt shutdowns the VM gracefully and preserves disk. destroy removes the VM entirely. Use halt for pauses and destroy to clean up unused environments.
Originally published on Ayodhyyya. Last updated June 1, 2026.