An Introduction to Vagrant

Avatar of Jason Witt
Jason Witt on (Updated on )

The following post is by Jason Witt, a regular around here on topics like WordPress development. This time Jason introduces us to a development prerequisite: the development environment itself. There are lots of ways to level up behind off-the-shelf app solutions, including scripting your own setups.

One question I hear again and again from new and experienced developers alike is “What local development setup do you use?” As a WordPress developer that needs, at a minimum, Apache, MySQL, and PHP, I would answer “You should give MAMP/XAMPP/WAMP a try, it’s easy to use and works great”. I still think that, but the more I learn and develop my skills as a developer, I no longer think MAMP/XAMPP/WAMP can support my needs.

I think most of us have uttered these words at least once: “Well, it works on my local server”. What can you do? When the live server isn’t the same as your local server, it’s not as though you can predict an issue on the live server. Vagrant can help solve that problem.

vagrant logo

Let me introduce you to Vagrant, a tool that allows you to easily set up a virtual server environment on your local machine. In their own words:

Vagrant provides easy to configure, reproducible, and portable work environments built on top of industry-standard technology and controlled by a single consistent work flow to help maximize the productivity and flexibility of you and your team.

With Vagrant, you can set up your local machine with the exact same environment as your live server. From the OS, to the web server, to the database. Now you can build your web app or website with the utmost confidence that it will run just as well on the live server as it does on your local server.


There are a few things you need to have before you can start working with a Vagrant box.

First, you need a virtual machine installed on your computer for Vagrant to run the virtual boxes. The two most popular virtual machines are VMware Workstation and VirtualBox. VMware is a commercial product and VirtualBox is a free, open-source product.

Next, you need git installed if you want to clone Vagrant Box repos from GitHub or Bitbucket. You can find many Vagrant boxes distributed on GitHub and Bitbucket, and having git to clone the repos is an easy way to get the Vagrant Boxes. I won’t go into installing git in this article, but you can learn how install git here. You can also find a bunch of great git related articles right here on CSS-Tricks.

You also need to have SSH installed to be able to SSH into your virtual box. If you’re running OSX or Linux, you probably already have OpenSSH installed. If you’re on Windows, you can follow the tutorial here to get SSH installed on your PC.

Finally, you need a command line tool. Yes, I know the command line can be scary, but trust me; you only need the most basic of command line skills to use Vagrant. If you’re on Windows, you can use the Command Prompt. On OSX you can use Terminal.

Installing Vagrant

All right, it’s time to get into the meat and bones. Head over to the Vagrant website to download and install the latest version of Vagrant for your operating system.

After you install Vagrant, you can check to make sure it was installed correctly by typing the following command:

vagrant -v

If Vagrant was properly installed, you should see something like this:

Vagrant 1.7.2

Now that you have Vagrant installed, let’s find and set up a Vagrant Box. There are three popular ways to download a Vagrant Box. Downloading a box directly, cloning a box from GitHub or Bitbucket, and adding a box from the Vagrant Cloud.

Getting the Boxes

For the purpose of this tutorial I’m going to use a pre-built Vagrant Box called Scotch Box. Scotch Box is a basic LAMP stack, that, once installed, will give you everything you need to start developing with those dependencies.

Scotch Box is set up for use on the VirtualBox virtual machine. If you’re running VMware, you can find a Vagrant Box to download at There are also a ton of other great boxes for VirtualBox there, too.

If you want to download Scotch Box, head over to the GitHub repo at, and download the repo. Once it’s downloaded, navigate to the directory where you want to install your Vagrant Box. Create a directory where you want the box located, then extract the contents of the zip file into that folder.

Cloning the repo just as easy. Navigate to the parent directory where you’re going to install the box using your CLI. Then, use this command to create the Vagrant Box directory and clone the box:

git clone my-project

Make sure you change my-project to what you want to name your Vagrant Box’s directory.

The last way to get a Vagrant Box is to grab it from the Vagrant Cloud. In my opinion this is the easiest way to set up a Vagrant virtual machine.

First, add the box. You do this by using the add box command, followed by the box’s name. The box’s name is usually formatted like: something/anotherthing. The name for Scotch Box is scotch/box. To add Scotch Box, use the following command:

vagrant box add scotch/box

This command downloads the Vagrant Box, making it available to use with Vagrant.

After the box is downloaded, create the directory you want the box to be located in and navigate into that directory in your CLI. Once there, initiate the box and add the Vagrant file to the directory with this command:

 vagrant init scotch/box

Starting Up Vagrant

At this point, you have the Vagrant files downloaded and in the correct directory. We want to install all components available in the box, so navigate to your newly created Vagrant Box directory and start Vagrant for the first time with the command vagrant up.

vagrant up

Now wait….

The first time you run a Vagrant Box, it needs to download and install the OS, the server, and all the additional components. The amount of time for this varies depending on the Vagrant Box you choose and your connection speed. Scotch Box is pretty lightweight and takes me about 10 minutes. I’ve also used a Vagrant Box called Varying Vagrant Vagrants, which is an excellent box for WordPress development, but it’s pretty big. It takes me the better part of 20-30 minutes on the initial vagrant up.

Using Vagrant

Now that you have the Scotch Box Vagrant Box installed and running, what can you do with it? Well, you can do anything you can do on any other LAMP stack server. Scotch Box has a pre-configured web server that uses the IP address, so if you point you browser to that address you’ll see this:

scotch box default screen

Everything being rendered by the web server can be found in the “public” directory. This is going to work just like any other web server you’ve ever used. In addition to the Apache web server, Scotch Box also installed these components that are ready to be used:

  • Vim
  • MySQL
  • PHP 5.5
  • Ruby
  • Git
  • Screen
  • Composer
  • Laravel Installer
  • cURL
  • GD and Imagick
  • Mcrypt
  • Memcache and Memcached
  • NPM
  • Grunt
  • Bower
  • Yeoman
  • Gulp

If you want to use a virtual domain instead of the IP address, you can edit your hosts file and add this line:

Vagrant Commands

Vagrant lets you control your server from the command line. You can find a full list of commands here, but let’s get you started with the basic commands.


All Vagrant commands begin with vagrant. If you run the vagrant command by itself, it will list all available commands you can use.

vagrant up

The vagrant up command is used for starting your virtual box. After you run this command your virtual box will be running and ready to use.

vagrant ssh

The vagrant ssh command allows you to SSH into your virtual box and gives you access to a shell. This is helpful for accessing MySQL and performing commands such as mysqldump to backup your databases.

vagrant suspend

To pause your machine you can use vagrant suspend. This is useful if you want to stop your machine without having to completely shut it down.

vagrant halt

To shut down your machine you use vagrant halt. This shuts it down and retains the machine’s current state.

vagrant destroy

To turn off your machine and completely start over fresh, use the command vagrant destroy. After a vagrant destroy command you’ll have to go through the initial vagrant up again.


The world of web development is far more vast today than it was even 5 years ago. Having the ability to develop on a local server that mirrors your live server gives you a more stable development environment and the confidence to push your projects live without the worry of it breaking immediately. Tools such as Vagrant are the future of web development, and by using these tools you’ll grow as a web developer and help mature the landscape of the Internet.