Nexcess Blog Logo
January 29, 2021

Running WordPress Locally with Vagrant and VVV

My next series of posts are going to cover a myriad of ways to run WordPress locally for your development needs. Over the years I’ve used each option at different times depending on the needs for my local development environment.

Today we’re going to look at one of the first tools that I dug into as I learned more about server configuration and working with WordPress Core code, Varying Vagrant Vagrants. That’s a bit of a mouthful, so it’s most often abbreviated to VVV, which is what I’ll use.

What is VVV

VVV was started as an internal project at a WordPress agency called 10up. As it grew in popularity it was moved out of a company-specific project and an official organization was set up to govern the project. Since then a vibrant community of developers has continued to maintain and use VVV in their development environment.

VVV is based on Vagrant, which is open source software used to build virtual machines. You combine it with tools like VirtualBox, Hyper-V, Docker, or other supported platforms to run virtual computers on your machine.

Most people use VirtualBox to interact with Vagrant, and VVV is set up to expect VirtualBox by default.

Installing VVV

Let’s start by getting the default tools set up so that we can install VVV. First, head to the Vagrant downloads page and download the version that is meant for your computer.

On macOS, the download contains a package file that needs to be double-clicked to install. You’ll be asked for your password and then the installation will be complete.

For VirtualBox, head to the download page and download the version that is meant for your computer. For macOS, you’ll be looking at the same basic process. Double-click the package file to run it then enter your password when prompted and let the installer run.

Note: You may need to reboot your machine once you’ve installed VirtualBox to get all the network connections working. If it doesn’t work at first, turn it off and on again before you go further down the path of troubleshooting.

Now we’re ready to install VVV. While there are two methods to install VVV, we’re going to stick with the easy method via git. Check out our Introduction to Git if you’re not familiar with how to use it.

First, create a directory to store all your VVV sites, I usually use ~/Sites. Then we’ll need to use git to clone the VVV repository with the command below.

git clone -b stable git:// ~/Sites/vagrant-nexcess

This creates a copy of the current stable branch of VVV in a folder called vagrant-nexcess in our current directory. Next, you’ll need to change into the vagrant-nexcess directory by using the cd vagrant-excess command. Once inside this directory use vagrant up to start running VVV.

If you’re on Windows, you’ll need to use a command prompt with administrator privileges to get custom hostnames working with VVV.

It may take a while the first time you install this because it has to download a copy of the virtual machine that is defined in the VVV configuration files, but after the first time, that data is cached so future installs will be much faster.

You may get asked to install some other plugins for Vagrant like the vagrant-goodhosts plugin. You want all this stuff so accept the installs when prompted. You may need to run the vagrant up command again after you’ve installed the plugins, and you may need to enter your administrator password to modify the hosts file so you can have custom domains available in VVV.

All computers have a hosts file, which maps hostnames to IP addresses. When you type in this file is part of the system that will translate that URL into the IP address that your computer is looking for. By adding a domain to your hosts file, you can force that domain to go to wherever you want.

Now that VVV is installed you can access the default site at the default URL of http://vvv.test.

Now, let’s go over how to add a custom domain and a clean WordPress install to VVV so you can get started with a new project. To start, open the vagrant-nexcess folder in your code editor. Then you’ll need to open config/config.yml to add our new domain. We’re going to create a new site called nexcess and use nexcess.test as our development domain.

Inside config.yml you can already see some extra sites configured. Let’s look at the first one to understand what’s going on.

 # latest version of WordPress, can be used for client work and testing

  # Check the readme at


    skip_provisioning: false

    description: "A standard WP install, useful for building plugins, testing things, etc"



      - one.wordpress.test



        WP_DEBUG: true

        WP_DEBUG_LOG: true

        WP_DISABLE_FATAL_ERROR_HANDLER: true # To disable in WP 5.2 the FER mode

First, we name the profile wordpress-one and under that, we set our configurations for this site. We can see that we give the site a description, and use the repo parameter to define where we want to clone the site from. Then we set up the host and define some of the constants that will be present in our standard wp-config.php file for debugging. You could even go to one.wordpress.test and see the site that is configured by default.

Modify the code above to match the changes made below. Note, we changed the name of the profile, the description, and host, and we added a plugin we want installed by default, Query Monitor.


    skip_provisioning: false

    description: "A standard WP install, useful for building plugins, testing things, etc"



      # locale: it_IT

      delete_default_plugins: true


        - query-monitor


      - nexcess.test

Once you’ve made the changes above, head over to your terminal and run vagrant up –provision to tell Vagrant to run through its setup scripts again and provision the virtual server with our new settings. Then you can find your new site at nexcess.test.

A word of caution, the configuration file is written in YAML and YAML is sensitive to indentation. You should be using 2 spaces to indent things or it will all go up in flames.🔥

Developer Tools

If you followed our series on Unit Tests then you’ll want to run them with VVV. Because VVV is running a virtual server you’ll need to start by using ssh to connect to this virtual server. You can do this with the vagrant ssh command that is provided as part of your package.

Next, you’ll need to use terminal to get to your web directory, which is found at /srv/www. From here you can move to the directory that has your tests and run them like normal. 

Another thing that I regularly need to do is connect directly to the database of the site I’m working on. If you’re using Sequel Pro, VVV comes bundled with a configuration file you can use to connect automatically. You can find this inside the cloned package at database/sequelpro.spf. Import it into Sequel Pro and you’ll get a connection.

The VVV database documentation also provides several other connection methods to suit your needs.

I also regularly need to check on the emails that are being sent in my WordPress installs. For this VVV provides the MailHog package. MailHog will capture all your emails and provides a nice web UI to view them. You can access Mailhog via the VVV dashboard which is found at vvv.test. You’ll also find access to phpMyAdmin and many other tools on the dashboard, so take note of it.

If you’re looking for a developer-focused environment to do your work, then VVV is a great choice. It installs everything you need without touching any of the internals of your computer. Coming from MAMP, which does touch stuff on your computer, VVV was a breath of fresh air because I knew that if something went drastically wrong, it would be contained in my Vagrant container and not mess with anything else on my machine.

The biggest problem with it is that if something goes wrong, you need to have a good understanding of how server provisioning works to work through and fix problems. The developers are very helpful, but it still takes some understanding to work through problems.

Depending on your projects the tailored to WordPress nature of VVV can also be an issue. If you work with both Laravel and WordPress you may end up fighting with the WordPress specifics. You certainly can run both Laravel and WordPress projects with VVV but you’re a bit more out on your own if you go that route.

If you haven’t tried VVV before, take it for a spin.

Avatar for Curtis McHale
Curtis McHale
Curtis is a husband, father, developer and business coach. He specializes in helping people build a business that lets them spend time with their family instead of working all the time.