Using Vagrant with WordPress

July 16, 2017

Prerequisites for using Vagrant and WordPress

Before beginning, you will need to have the following installed:

Vagrant WordPress configuration

We will be using a tool called WPDistillery. This tooling uses ScotchBox, which is a pre-configured Vagrant box configuration that provides a LAMP stack setup for Vagrant. WPDistillery provides the WordPress application-related provisioning, while ScotchBox provides the LAMP stack infrastructure.

Let’s assume your project root directory is called my-website. We will clone the required files into our project directory:

git clone my-website

This should clone a Vagrantfile and a ./wpdistillery directory into your project root.

We will need to modify the file ./wpdistillery/config.yml. It’s pretty much ready to go but we should change the database information from the default, which can be found in this section:

# scotch box db access
  name: scotchbox
  user: root
  pass: root
  prefix: wp_

Optionally, change the website URL from to something more memorable, e.g., and the database name from scotchbox to something more memorable for your website, e.g. mywebsitesdatabase. One of the benefits of doing this is the flexibility to run more than one WordPress website using ScotchBox on your computer. If all of your WordPress websites use the default database name, they will overwrite each other whenever you run them.

Run it

Once you’ve done this, run the following command:

vagrant up

This should start downloading the required Linux image if it has not already been downloading, and provisioning it with the ScotchBox configuration. Once the ScotchBox provisioning has run, it will start running the WordPress-specific commands that WPDistillery provides.

At this point, if you’ve changed the default database name from scotchbox, this command should show an error saying that the provided database could not be found. This is to be expected. You should then at this point, log into the virtual machine and create this database:

vagrant ssh
create database mywebsitesdatabase;

Once that’s done, you can Ctrl + D out of everything. You should be able to re-run the command and have it complete successfully.

Configure routing

Before loading your WordPress site in the browser, you will need to add the following line to your hosts file, found at /etc/hosts.

Now that you’ve successfully provisioned a virtual machine that runs WordPress, you should be able to access it at the URL or

Start your theme development

Your theme files are located at ./public/wp-content/themes/. You can create a new theme here and get started with developing your WordPress project.