When doing development of WordPress like plugin, theme, or even the core development, it is usually a pain to set up the local development environment.

The setup of local WordPress development environment usually includes two parts:

  1. Set up the development stack locally as well as the WordPress instance.
  2. Sync WordPress DB — normally it is required for better testing environment.

Usually, we are using MAMP or XAMPP to help set up the PHP development environment including PHP (with multiple versions), MySQL, Perl, as well as some other services (like DNS, FTP, etc.). And for a long period of time, these tools do help a lot to simplify this process.

With Vagrant, we could make this process even simpler. And beyond that, Vagrant can also help us easily set up the WordPress instance, even including getting the plugins and themes ready.


Vagrant is an open source tool that helps “create and configure lightweight, reproducible, and portable development environments”. Instead of setting up the environment directly on your dev machine, Vagrant builds separate “Virtual Machine” as a “container” to host all the development stack. By doing this, you can very easily create multiple different environments on one single dev machine as well as mange them (editing, destroying, etc.).

Check Vagrant official website for more explanation.

Vagrant uses a plain-text based “configuration file” (usually no more than 4KB) – “Vagrantfile” to help configure the virtual machine you create. The configuration includes the basic specs (like memory, CPU, server IP, hostname), sync folder, and some customized operations (like installing software package).

So we can just configure the “Vagrantfile” to help set up the development stack as well as install the WordPress.

Set Up Vagrant

Using Vagrant needs support of “VirtualBox“. So you need to install them both.

Once done, you can also add several Vagrnt plugins to help you run Vagrant better. Use vagrant plugin install {plugin-name} to install the plugins.

  • vagrant-hostsupdater – help manage the “hosts” file (/etc/hosts) when using local domain.
    • If you are working on Windows, then you have to add it manually.
  • vagrant-triggers – it allows for various scripts to fire when issuing commands such as vagrant halt and vagrant destroy.

If you are using the IDE “PhpStorm” / “WebStorm” (from JetBrain), you can also manage Vagrant (including plugins and boxes) directly with the GUI it provides.

Vagrant with Other Virtual Machine Providers

By default, Vagrant works with VirtualBox, which is a universal virtual machine provider working on every platforms (Windows, Linux and OS X). However, its performance is way far slower than any other enterprise-level providers like VMWare Workstation, VMware Fusion, Parallels Desktop, etc.

If you are working specially on certain platform and having those enterprise-level providers installed, you can switch to those prvoiders by using the corresponding plugins:

Vagrant Boxes

Vrgrant uses the term “Box” to represent a virtual machine it works on. This Vagrant Box can be either a fresh linux image (like a Ubuntu image) or any customized Linux image with some software pre-installed (like VCCW – a pre-prepared WordPress development image).

Vagrant uses the command vagrant box add ADDRESS to add a box into your Vagrant environment. The ADDRESS can be:

  • A unique shorthand name (like “ubuntu/trusty64”). You find the entire list from the public catalog.
  • File path or HTTP URL to a box in the catalog.
  • URL directly a box file.

Check the online documentation for more details.


For writing the Vagrantfile you can refer to the example file that Vagrant provides (by run vagrant init to initialize a new project).

Or you can use this tool (provided by PUPHPET) to help construct the Vagrantfile.

Build Local Development Environment

In this post, we will use Varying Vagrant Vagrants to help build the Vagrant configurations for WordPress development. When using “vvv“, here are two tools that can help save a lot of time.

  • VVV Site Wizard – it automates the creation of new sites as well as the teardown of old ones.
    • You can also choose Variable VVV, a more active maintained tool forked from “VVV Site Wizard”.
  • WordPress Theme Review VVV – it is a quick Vagrant setup that adds all the necessary tools for reviewing themes.

Besides “vvv”, there are also some other tools that can help you build the WordPress development environment, such as VCCW (vagrant-chef-centos-wordpress), Primary Vagrant, VagrantPress, etc.

For more details of these other tools, you can check on this post.

OK, let’s start.

Set up VVV

Setting up VVV is easy.

  1. Make sure you have installed the VM providers (VirtualBoz by default).
  2. Install Vagrant.
  3. (optional) install the vagrant plugins – “vagrant-hostsupdater”, “vagrant-triggers”.
  4. Clone or extract the Varying Vagrant Vagrants project into a local directory.
    • git clone git://github.com/Varying-Vagrant-Vagrants/VVV.git vagrant-local
  5. In the terminal (command prompt), run vagrant up under the directory “vagrant-local”.
    • Since it is on the first run, it takes a while to download the required files to finish the provision. Please Be patient.
    • You may also need to enter your “password” to get the permisison to modify the “hosts” file on your machine.
  6. Once it done, you should be able to use the following links to visit the WordPress instances in the browser.
    • http://local.wordpress.dev/ for WordPress stable
    • http://local.wordpress-trunk.dev/ for WordPress trunk
    • http://src.wordpress-develop.dev/ for trunk WordPress development files
    • http://build.wordpress-develop.dev/ for the version of those development files built with Grunt
    • http://vvv.dev/ for a default dashboard containing several useful tools
  7. The username and password for Vagrant SSH is vagrant and vagrant.

You can check the online documentation for more tutorials, like add new domains, Auto site setup, etc.

If you are looking for a better dashboard, check VVV Dashboard

VVV Stack

In the VM, all the usernames and passwords for WordPress admin are admin and password. And all the usernames and passwords for WordPress DB are wp and wp.

The username and password for mySQL root is root and root.

The following table shows the info for all WordPress instances:

WordPress Stablevagrant-local/www/wordpress-default/srv/www/wordpress-defaulthttp://local.wordpress.devwordpress_default
WordPress Trunkvagrant-local/www/wordpress-trunk/srv/www/wordpress-trunkhttp://local.wordpress-trunk.devwordpress_trunk
WordPress Developvagrant-local/www/wordpress-develop/srv/www/wordpress-develophttp://src.wordpress-develop.dev, http://build.wordpress-develop.devwordpress_develop, wordpress_unit_tests

Here is a list of tools installed in VM:

Use CLI – VVV Site Wizard / Variable VVV

VVV Site Wizard / Variable VVV are CLIs that help automate seting up new WordPress sites as well as manage the existing WordPress instances.

For example, assume we need to create a new site with the following settings:

  • name: mysite
  • domain: mysite.dev
  • a multisite with subdomains
  • WP_Debug turned on

So the command should be:

vv create --domain mysite.dev --name mysite --multisite subdomains --debug
## A "short" version
vv create -d mysite.dev -n mysite -m subdomains -x

Besides using CLI arguments to specify the settings, Variable VVV also support Blueprints. The Blueprints file is a json file (named vv-blueprints.json) which can contain as many different sites as you’d like. Each of the sites can have different plugins, themes, mu-plugins, options, or other constants.

To set up the Blueprints file, run vv --blueprint-init and it will create the vv-blueprints.json file in your VVV directory.

Here is the example format of the json file:

  "sample": {
    "themes": [
        "location": "automattic/_s",
        "activate": true
    "mu_plugins": [
        "location": "https://github.com/WebDevStudios/WDS-Required-Plugins.git"
    "plugins": [
        "location": "https://github.com/clef/wordpress/archive/master.zip",
        "version": null,
        "force": false,
        "activate": true,
        "activate_network": false
        "location": "cmb2",
        "version": "2.0.5",
        "force": false,
        "activate": true,
        "activate_network": false
    "options": [
    "demo_content": [
    "defines": [

And “sample” is the name of the site and you can add more blocks like this in the file.

You can check the Github repos for more info about how to use it.

Set up WordPress Theme Review VVV

If you are more offten doing theme development, you should definitely add this extention as well.

Set up WordPress Theme Review VVV is easy.

  1. Clone this repo (https://github.com/aubreypwd/wordpress-themereview-vvv.git) to the www folder under your VVV local folder.
  2. Run fo the provision of Vagrant in VVV.
    • If Vagrant is running, run vagrant halt to shut it down and then vagrant up --provision.
    • You may also need to enter your “password” to get the permisison to modify the “hosts” file on your machine.
  3. Once it done, visit the new theme review development site by the URL http://themereview.wordpress.dev/.
    • The username and password for WordPress admin is still admin and password.
    • It also creates the DB wordpress_themereview in the local MySQL, with the username and password wp and wp.

When setting up WordPress Theme Review VVV, it also install and activate the Developer and Theme-Check plugins. So you will need to configure them once log into the WordPress admin. It also imports the Theme Unit Test data.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>