Despite its age and familiarity to most nowadays I couldn’t find a straight forward post on how to install and get started using Vagrant. So here are my notes on doing so in blog post format.
Be aware that this is well-trodden ground and the Vagrant documentation on their website has a similar set of steps and content. The official site, if not this will get you where you need to be when it comes to getting started with Vagrant.
1 – Install VirtualBox
Our provider choice will be VirtualBox. The provider describes the software in charge of creating then managing the virtual machines commissioned by Vagrant. The two major providers are VirtualBox and VMware, VirtualBox is free and open-source, whereas VMware is not.
On Ubuntu, you would add this line to the bottom of your
deb http://download.virtualbox.org/virtualbox/debian xenial contrib
xenial for your own distributions release codename.
You can find this codename if you don’t already know it by running this command; back on the prompt.
For Debian 8 (“Jessie”) and Ubuntu 16.04 (“Xenial”) or later distributions. Download and add the repositories PGP key.
Update the apt-get package database and install the
VirtualBox is now installed and ready to use.
2 – Install Vagrant
Find the correct binary for your version of Linux, then download it with the URL and Wget.
wget command and correct URL for downloading the latest version of Vagrant on Debian (at the time of writing this) – yours may differ.
To then install the binary as a package on the system, use:
You can remove the Vagrant
.deb build file from your user’s home directory now, after it’s been installed.
3 – Download and Use a Vagrant Box
Make a temporary test directory, and change into it, before continuing.
To test the install, you can download and run a basic Vagrant box as a VM by running the next set of commands.
So we’re clear, here’s a good definition of a what a Vagrant “box” actually is:
“A package containing a representation of a virtual machine running a specific operating system. To be more simple, it is a base image of any Operating System or Kernel. It may be for a specific Provider.”
The box is the image, and from this image, a virtual machine (VM) is created on the localhost.
The basic Vagrant configuration for this VM will be based in one file, the
This file is placed in the
~/vagrant-test directory via:
There are a wide variety of different box types (various OS images) listed on Hashi corp’s Atlas index.
After issuing the next command Vagrant will start to download the box and attempt to create and run a VM through VirtualBox.
Here’s an example of what the progress output looks like for this:
You can get an error message here relating to CPU architecture if you use a box that isn’t intended for your host’s operating system.
For example, the first image here requires a 64-bit host operating system, and then the second is for a 32-bit version. The “host” here refers to the machine you installed Vagrant on.
In my example, we used the first box, a 64-bit system.
Also if you are running Vagrant itself in a virtual machine (using a hypervisor). Then you’ll need to ensure your hypervisor has “VT-x/AMD-V enabled”.
To enable this you’ll have to do something along the lines of:
- Power off the host virtual machine.
- Edit the individual virtual machine’s settings.
- Go to the CPU/processors section.
- Enable “VT-x/AMD-V” / “Virtualise Intel VR-x/EPT and AMD-V/RVI”
- Then power on the virtual machine again.
vagrant upin your Vagrant testing directory.
Here is what the setting looks like when using VMware Workstation as your hypervisor.
4 – Connect to a Running VM
Once a box is installed and configured to run in a VM (like in step 2), you connect to the VM through an SSH tunnel created by Vagrant.
To connect to the new running VM with Vagrant use:
The prompt now shows you are connected to your new VM!
exit or use
CTRL + D to leave the VM’s command line and return to your host.
5 – Vagrant Sub-commands
These are the commands you’ll find yourself using when working with Vagrant. They use subsets of subcommands – which may seem confusing at first glance. The first is
box and has several susbets. Not all, however, have them.
List all the boxes you currently have installed on the host.
Remove an already existing box from Vagrant.
Check updates for all box images on your system.
Many of these commands can have the box named appended to them. In order to single them out.
The Vagrant documentation sums this command up pretty well:
“This command stops the running machine Vagrant is managing and destroys all resources that were created during the machine creation process. After running this command, your computer should be left at a clean state, as if you never created the guest machine in the first place.”
Use it to destroy your created virtual machines e.g.
This command shuts down the running virtual machine Vagrant is currently managing; you can add a machine name/ID to target specific VM’s
This is the same as a
vagrant halt but restarts the VM after halting – like with
This allows you to list all the Vagrant guest ports that are mapped to the host ports.
Useful for displaying the output of the Vagrant host side SSH configuration file.
6 – Miscellaneous
Should there ever be any SSH connection issues to a VM. The connection log can be seen by appending
--debug to the command.
--debugflag can be added onto most Vagrant commands to see the internal operations being carried out.
Checking the status of the current Vagrant virtual machine is possible by entering:
A global version also exists.
--prune flag updates the cache for this – thereby removing any old, dead entries from the output.
Looking back to the
Vagrantfile configuration. We can see that there are different options on offer to configure the resultant VM(s).
One to highlight is the VM name that is assigned to both the provider (VirtualBox) and the internal Vagrant machine “name”.
This is the code to explicitly define it in both instances if you ever want to:
Line 3 determines the
"name" listed when issuing:
Whilst line 5/6 ensures VirtualBox names and displays the VM properly in its GUI.
7 – Autocompletion
A nice addition to Vagrant is shell auto-completion (Bash shell) for when typing in the above commands. An up to date (at the time of writing this) repo which provides this is located here:
This is a fork of Kura’s old repo; thanks go to him for maintaining this up until now. Here’s the provided “easiest” method of downloading this functionality to your Linux/Unix host system.
wget the script file in the above repo.
Add the newly-downloaded file to the system Bash completion directory – whilst modifying the file’s permissions.
Now either close and re-open your terminal, or
source in the new
/etc/bash_completion.d/vagrant bash-completion file. To get the new auto-completion working.
Learn more from this infographic: