Are looking for a well-defined, open-source, virtual environment easily shared amongst team members? If the answer is yes, it may be time to get acquainted with Vagrant.

Vagrant is a tool for configuring and deploying an exact image of a virtual operating system by spinning up boxes of virtual machines. It can share environments together with code, making collaborative and cooperative development possible.

It allows a code fragment from one developer to work on the system of another. Therefore, it is often used in software development to ensure all team members are writing code for the same configuration.

This tutorial will walk you installing, configuring, and managing Vagrant.

tutorial for beginners on using vagrant

Getting Started With Vagant

Note: Different versions of Linux use different package managers. Refer to your operating system pages for specific commands.


1. Before you start, make sure you already have a virtual provider on your system. Providers that work with Vagrant include VirtualBox, VMware, Docker, Hyper-V and custom providers.

2. To find the latest version of Vagrant, use a web browser to navigate to its official webpage:

You will see a list of all the different supported operating systems, with a 32-bit and 64-bit download for each. Download the appropriate file for your operating system, then run the installer.

3. There are two way to check if the installation was successful:

  • You can either use the command:

vagrant -v

It should show the version number running on your computer. The latest version to date is Vagrant 2.2.4.

  • Or you can simply type in the following command in the terminal:


The output will show you a list of frequently used commands if the tool was properly installed.

Do you need to Install Docker CentOS or Ubuntu? Read our guide for each distribution.

Project Setup

Next, you need to create a new local directory file and download Vagrant to start using Vagrant.

1. Start by creating a directory to store your Vagrant file:

sudo mkdir vagrant-test

cd vagrant-test

2. Download the Ubuntu Trusty Tahr distribution from a common library and create a basic Vagrantfile with:

vagrant init ubuntu/trusty64

If you like, you can browse to and download a Vagrantbox of your choosing.

When you run init, Vagrant installs the box to the current directory. The Vagrantfile is placed in the same directory and can be edited or copied.

Vagrant Boxes

The basic unit in a Vagrant setup is called a “box” or a “Vagrantbox.” This is a complete, self-contained image of an operating system environment.

A Vagrant Box is a clone of a base operating system image. Using a clone speeds up the launching and provisioning process.

1. Instead of using the init command above, you can simply download and add a box with the command:

vagrant box add ubuntu/trusty64

This will download the box and store it locally.

2. Next, you need to configure the Vagrantfile for the virtual box it will serve. Open the Vagrantfile with the command:

sudo vi vagrantfile

3. Once the Vagrantfile is open, change the string from “base” to “ubuntu/trusty64”. = "ubuntu/trusty64"


You can add another line above the end command to specify a box version:

config.vm.box_version = “1.0.1”

Or you can specify a URL to link directly to the box:

config.vm.box_url = “”

If you’d like to remove a box, use the following:

vagrant box remove ubuntu/trusty64


Instead of building out a complete operating system image and copying it, Vagrant uses a “Vagrantfile” to specify the configuration of the box.

Note: The download page for each box includes a configuration script that you can copy into your Vagrantfile.


If you spent much time in the guest OS, you may have noticed that it doesn’t come loaded with very many applications.

Fortunately, Vagrant supports automatic provisioning through a file saved in the same directory as the Vagrantfile.

Let’s add a basic resource monitor, nmon, in the guest OS:

sudo vi

In that file, enter the following:

#!/usr/bin/env bash

apt-get update

apt-get install -y nmon

if ! [ -L /var/www ]; then

rm -rf /var/www

ln -fs /vagrant /var/www


Save the file and exit. Next, edit the Vagrantfile and add the provisioning line. It should look as follows:

Vagrant.configure("2") do |config| = "ubuntu/trusty64"

config.vm.provision :shell, path: ""


When Vagrant reads the Vagrantfile, it sees the command to read the file we just created. That bootstrap file will update the package manager, then install the nmon package. If you vagrant up and vagrant ssh, you should now be able to run nmon for a display of the virtual machine’s resources.

Provisioning gives you a powerful tool for preconfiguring your virtual environment. You could also do the same with apache2, and create a web server in your virtual environment.


This tutorial shows you how to use Vagrant with VirtualBox. However, Vagrant can also work with many other backend providers.

vagrant up –provider=vmware_fusion – Launches Vagrant using VMWare.

vagrant up –provider=aws – Launches Vagrant using Amazon Web Services.

Once this command is run the first time, subsequent commands will apply to the same provider.

Launching and Connecting

Vagrant Up

The main command to launch your new virtual environment is:

vagrant up

This will run the software and start a virtual Ubuntu environment quickly. Even though the virtual machine is running, you won’t see anything. Vagrant doesn’t give any kind of user interface.

Vagrant SSH

You can connect to your virtual machine (and verify that it’s running) by using an SSH connection:

vagrant ssh

This will open a secure shell connection to the new virtual machine. Your command prompt will change to vagrant@trusty64 to indicate that you’re logged into the virtual machine.

Once you’re done exploring the virtual machine, you can exit the session with CTRL-D. The virtual machine is still running in the background, but you’ve just closed the SSH connection.

To end the virtual machine, enter:

vagrant destroy

The file you downloaded is still on your system, but anything that was running in the virtual machine is gone.

Synced Folders

Vagrant automatically synchronizes content that’s in your project directory with a special directory in the guest (virtual) system. The project directory is the one you created earlier, /vagrant-test. It’s also the same one that holds the Vagrantfile.

When you log into the virtual machine, by default you’ll start in the /home/vagrant/ directory. A different directory, /vagrant/, holds the same files that are on your host system.

You can use vagrant up and vagrant ssh to launch and log into the virtual machine, then create a test document in the /vagrant directory. Use the exit command to close the SSH session, then use ls to list the contents of your vagrant-test directory. It should display the test file you created.

This is a handy way to manage files in the guest OS without having to use an SSH session.


Vagrant includes options to place your virtual machine on a network. At the end of your Vagrantfile, just before the end command, use the command to specify network settings.

For example: “forwarded_port”, guest: 80, host: 8080

This creates a forwarded port for the guest system. You may also define private networks, public networks, and other more advanced options.

Vagrant Share

Vagrant uses a handy tool that you can use to share your Vagrant environment using a custom URL.

With your Vagrant environment running, use the following command:

vagrant share

The system will create a Vagrant Share session, then generate a URL. This URL can be copied and given to another person. If you’ve got Apache configured in your Vagrant session, anyone who uses this URL can see your Apache configuration page. This URL will change as you modify the contents of your shared folder.

You can close the sharing session with CTRL-C.

For more information, see the Vagrant Sharing documentation.

Clean Up Vagrant

Once you’re done working on your guest system, you have a few options of what to do with it.

vagrant suspend – This saves the state of the machine and stops it. You can resume by running vagrant up again. This is much like putting the machine in sleep mode.

vagrant halt – This gracefully shuts down the virtual machine. Using vagrant up will reboot the same virtual machine, and you can resume where you left off. This is much like shutting down a regular machine.

vagrant destroy – This removes all traces of the virtual machine from your system. Anything you have saved in the virtual machine will be removed. This frees up the system resources used by Vagrant, but when you vagrant up the next time, the machine will have to be re-imported and re-provisioned. This is much like formatting the hard drive on a system, then reloading a fresh image.


By now, you should be familiar with the essential operations for Vagrant. If you followed along with the tutorial, you might even have a virtual OS running right now!