PHP Xdebug with Vagrant

I’ve been asked a few times about getting Xdebug for PHP working in a Vagrant environment. Most people tend to use Xdebug on localhost and IDEs are often able to configure themselves to work without much hassle in that environment. However, putting PHP in a virtual machine makes the setup a little trickier.

Xdebug works by using a protocol known as DBGP over TCP. What makes it slightly confusing, however, is the protocol flow happens in reverse from how most developers are used working: the server makes connections to your “client” (e.g. your IDE). Your debugger actually listens on a port (9000 by default), and Xdebug connects to that. Understanding that makes the setup make a little more sense.

Vagrant generally uses “Host-Only Networking” with an IP for the virtual machine of “” (see the documentation). In this scenario, your host machine (i.e. where your debugger will be listening on port 9000) is accessible from the VM at That means, we need to tell Xdebug to make it’s connections to on port 9000. This can be handled by the following php configuration:


I handle this configuration with this xdebug.ini.erb template in my chef-repo.

I have found that this works quite well with my Emacs setup using geben, but I’ve not yet tested it with other IDEs.