Tutorial: Vagrant Drupal 8 Development

Drupal 8

In this tutorial, you'll learn how to set up a local Drupal 8 development environment using the Vagrant Drupal Development (VDD) contributed module, Chef, Vagrant, and VirtualBox.

Warning - To use VDD with Drupal 8 you need to use the 8.x-1.x-dev version until a new release is created (after September 10, 2015).

Vagrant Drupal Development (VDD) is a ready-to-use development environment contained in a virtual machine. Why use it? It provides a standard hosting setup for developing with Drupal. This can get you up and running quickly, without knowing anything about server administration.

The VDD module uses Chef, a configuration management tool that helps automate your infrastructure, and Virtualbox server virtualization software. VDD uses Ubuntu 12.04 LTS Precise Pangolin, a Linux distribution, as a base. LTS is an acronym for Long Term Support. Version 12.04 was released in 2012 and has maintenance support until 2017. There is an issue open for upgrading to Ubuntu 14.04 LTS, although 2017 is a ways off.

One of the best things about the VDD module is that it shares a directory on your local machine with the virtual machine (VM) you use to run Drupal. This allows you to use all of your local development tools, while keeping all the server configuration in the VM!

Getting started

We're going to set up a Drupal 8 environment. Vagrant Drupal Development requires Virtualbox and Vagrant, if you don't have these installed, follow the steps below.

Installing Virtualbox:

Navigate to https://www.virtualbox.org/wiki/Downloads and grab a copy of the installer for your OS/Platform, and install it!

Installing Vagrant:

Make sure you followed the step above and installed Virtualbox. Otherwise, you won't be able to install Vagrant. Navigate to http://www.vagrantup.com/downloads.html and, again, grab a copy of the installer for your OS/Platform, and install it!

If you previously had Virtualbox installed, make sure to back up your current VMs before proceeding with this tutorial.

Clone the VDD repo in to your home directory (~/):

git clone --branch 8.x-1.x http://git.drupal.org/project/vdd.git
cd vdd

Drupal 8 now requires PHP 5.5.9, and as such, the base VDD module will require applying a patch to get Drupal 8 running.

VDD automatically creates drush aliases for each site in the config.json file at


By default, it defines a Drupal 7 and Drupal 8 alias. You can also set the username, email, and password for your Drupal install:

"vdd": {
  "sites": {
    "drupal8": {
      "account_name": "root",
      "account_pass": "root",
      "account_mail": "[email protected]",
      "site_name": "Drupal 8",
      "site_mail": "[email protected]",
      "vhost": {
        "document_root": "drupal8",
        "url": "drupal8.dev",
        "alias": ["www.drupal8.dev"]
    "drupal7": {
      "account_name": "root",
      "account_pass": "root",
      "account_mail": "[email protected]",
      "site_name": "Drupal 7",
      "site_mail": "[email protected]",
      "vhost": {
        "document_root": "drupal7",
        "url": "drupal7.dev",
        "alias": ["www.drupal7.dev"]

We can now start provisioning our VM. Once you type the following, go and grab a snack. It takes some time!

vagrant up

Once this is complete, you'll see the following in the terminal:

==> default: =============================================================
==> default: Install finished! Visit in your browser.
==> default: =============================================================

Visiting presents you with further instructions. I'll quickly add the bare-bones here so we can move along. But I urge you to visit this link and read more, particularly if you're interested in a Drupal 6 or 7 development environment.

We are going to add a custom entry to our hosts files, which controls your local system's DNS.

In Linux, edit the following file as an administrator in your text editor of choice:


In OS X, edit the following file as an administrator in your text editor of choice:


In Windows, edit the following file as an administrator in your text editor of choice:


I'm only going to add an entry for Drupal 8 here, as the VDD summary page noted above ( describes the entries you may wish to add for other Drupal versions. drupal8.dev www.drupal8.dev

Now we want to grab the latest Drupal 8, either using git, or drush. Make sure to use the directory name Drupal 8 to save us from editing apache config:

cd ~/vdd/data/drupal8
git clone --branch 8.0.x http://git.drupal.org/project/drupal.git .

By default, VDD performance can be slow, depending on your system, as it uses shared folders to share a directory on your host system with your virtual machine.

To speed this up, if you're running OS X or Linux, you can use: NFS

If your host system is Debian or Ubuntu (OS X users can skip this step):

apt-get install nfs-kernel-server

Now edit the "synced_folders" section of your config.json file, setting the "type" property from "default" to "nfs":

"synced_folders": [
      "host_path": "data/",
      "guest_path": "/var/www",
      "type": "nfs"

Windows users can use SMB:

"synced_folders": [
      "host_path": "data/",
      "guest_path": "/var/www",
      "type": "smb"

Now issue the following command to reload your VM configuration, from the VDD root directory on your host system:

vagrant reload

To install Drupal 8 on your new virtual machine :

vagrant ssh

The drush command 'si' installs your new Drupal site using the credentials specified in the config.json, based on the alias you pass. Since we're installing Drupal 8:

cd ~/sites/drupal8
drush @drupal8 si standard -y

You should now be able to navigate to drupal8.dev or www.drupal8.dev in your web browser, and log in with the credentials you specified in your config.json file.

You can start working on Drupal 8 core, on your local system, at the following location:


Why not start with Writing a Hello World Module?

If you would like to use mysql from the command line, you'll want to first ssh to your VM. From the VDD root directory on your host system:

vagrant ssh
cd ~/sites/drupal8

Then for mysql directly (you'll be prompted to type in the password: "root"):

mysql -u root -p drupal8

Or using drush sql-cli:

drush sql-cli

Happy coding everyone!


Just a heads up, but I had to update xdebug.max_nesting_level in vdd_xdebug.ini to avoid an exception when running drush.

The max_nesting_level issue is already in the d.o issue queue and it's marked RTBC. Hopefully in the next release of VDD 8.x we should see it!

Xdebug settings xdebug.max_nesting_level is set to 200.
Set xdebug.max_nesting_level=256 in your PHP configuration as some pages in your Drupal site will not work when this setting is too low.

I am getting this error when installing drupal 8. How do i solve this?

Hi Bishisht,

You will need to edit your php.ini, and set the "xdebug.max_nesting_level=256"

If you're not sure which php.ini on your system to edit, you can create a PHP Info page to find out!

Create "infotest.php" with the following contents: <?php phpinfo();?>

Visit http://yoursite.com/infotest.php

Look for the 'Configuration File (php.ini) Path' directive, which will tell you which php.ini you'll need to edit.

Make sure you delete the "testinfo.php" you create when you're done!

You can skip the hosts file setup if you use the vagrant-hostmanager plugin:

$ vagrant plugin install vagrant-hostmanager

Then, in your Vagrantfile, in the "# Create a private network..." section after "config.vm.network 'private network', ip: '192.168.xxx.xxx'" section, add something like (making sure to wrap in "if Vagrant.has_plugin?" like below to avoid errors when you take it to a new machine without vagrant-hostmanager installed):

if Vagrant.has_plugin?("vagrant-hostmanager")
config.hostmanager.enabled = true
config.hostmanager.manage_host = true
config.vm.hostname = 'local'
config.hostmanager.aliases = %w(euphoriemassage.com)

On vagrant up, you will be prompted for admin rights (root PW, Windows UAC prompt, etc.) to modify the hosts file. On vagrant halt or vagrant destroy, you will be prompted for admin rights again to remove the entries.

Hi - just did a vagrant install on ios yosemite 10.10.3 for drupal 8. I'm getting message: Your PHP installation is too old. Drupal requires at least PHP 5.5.9. See the system requirements page for more information
I'm helping with D8 panels sprint.

Hi toby53!

There is an open issue with a patch, that will upgrade the vdd setup to use Ubuntu 14.04, PHP 5.5.9 and a host of other changes.

You can check it out here: https://www.drupal.org/node/2327263

You will need to install the Chef Development Kit.

You then need to apply the following patch: https://www.drupal.org/files/issues/2327263-34.patch

If you need some assistance in applying a patch, check out the following video: https://drupalize.me/videos/applying-patch-module

Finally, run: vagrant up --provision

After vagrant setup,
I can enter ssh ok but now I'm trying to run drupal 8 and I'm getting the following messages:
on http://www.drupal8.dev/drupal/core/install.php
Your PHP installation is too old. Drupal requires at least PHP 5.5.9. See the system requirements page for more information.

Thanks for this, Will. Any plans on making a tutorial about configuring drush aliases with VMs?

I am trying to use this vagrant VM on Max OS 10.13 new machine and I am encountering this error:
during the vagrant up....

default: ERROR: Error installing chef:
default: ERROR: Failed to build gem native extension.
default: /usr/bin/ruby2.2 -r ./siteconf20171231-9919-1h90xgz.rb extconf.rb
default: creating Makefile
default: make "DESTDIR=" clean
default: make "DESTDIR="
default: compiling generator.c
default: In file included from generator.c:1:0:
default: ../fbuffer/fbuffer.h: In function ‘fbuffer_to_s’:
default: ../fbuffer/fbuffer.h:175:47: error: macro "rb_str_new" requires 2 arguments, but only 1 given
default: VALUE result = rb_str_new(FBUFFER_PAIR(fb));
default: ^
default: ../fbuffer/fbuffer.h:175:20: warning: initialization makes integer from pointer without a cast [enabled by default]
default: VALUE result = rb_str_new(FBUFFER_PAIR(fb));
default: ^
default: make: *** [generator.o] Error 1
default: make failed, exit code 2
default: Gem files will remain installed in /var/lib/gems/2.2.0/gems/json-1.8.1 for inspection.
default: Results logged to /var/lib/gems/2.2.0/extensions/x86_64-linux/2.2.0/json-1.8.1/gem_make.out
default: installed ruby and chef

Howdy Aaron,

It looks like you're missing some of the development dependencies that chef (and ruby) use to build executable files.

Have you installed Xcode and Xcode tools on your machine?

Add new comment

Filtered HTML

  • Web page addresses and email addresses turn into links automatically.
  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <code class> <ul type> <ol start type> <li> <dl> <dt> <dd><h3 id> <p>
  • Lines and paragraphs break automatically.

About us

Drupalize.Me is the best resource for learning Drupal online. We have an extensive library covering multiple versions of Drupal and we are the most accurate and up-to-date Drupal resource. Learn more