by Angus Mak on January 15, 2014 // Short URL

Debugging Drush commands with Xdebug and PHPStorm

Oftentimes, I run into issues with drush commands that needed more debugging power than dpm() provides. In search for a way to debug PHP scripts from the CLI, or drush commands more specifically, I stumbled upon PHPStorm’s Zero-configuration Debugging which turned out to be perfect for the job.

First, you will need Xdebug installed. has some excellent documentation on installing XDebug. For OSX users, I would recommend using homebrew with the formulae here

In the CLI, we will need to set the XDEBUG_CONFIG variable.

In bash,


Once Xdebug is installed and the XDEBUG_CONFIG variable set up, start a new project in PHPStorm. Click on the Magic Button to "Start Listen PHP Debug Connections"

Start Listen PHP Debug Connections

In the CLI, we can then run any drush command inside the drupal docroot and a breakpoint should trigger on the first line of drush.php.


Set up breakpoints and debug like you normally would. As long as PHPStorm is listening for a connection and the XDEBUG_CONFIG variable is set, any PHP script run on the CLI will trigger the debugger to break on the first line of the script. Once you are done with debugging, click the Magic Button again to "Stop Listen PHP Debug Connections".

Drush commands always trigger a break at the first line, unless drush is included in the project. When that gets a little old, uncheck "Force break at the first line when a script is outside the project" to stop the break at the first line.

Force break at the first line when a script is outside the project

I am in the debugger so much I ended up with the xdebug.idekey set up in my php.ini permanently.


That way the XDEBUG_CONFIG variable is not necessary anymore. In fact, this way any PHP activities including browsing a local site will pass through the debugging as long as PHPStorm is listening for a connection. 

Angus Mak

Senior Developer

Want Angus Mak to speak at your event? Contact us with the details and we’ll be in touch soon.


Add Your Comment

Pedro Perez

not working

Hi, I did all the settings, but debugging is not working. What i did wrong?



Thanks for the info. An

Thanks for the info. An example of the kind of thing that this can sleuth out would be cool too.


Mark Muhleder

In vagrant?

This is great as far as it goes, but what about if you're running your dev site in a vagrant VM? Any clues on how to debug Drush in that case?

I ended up having to install the site I was working on locally, and this worked then, so thanks for the tip anyway.


Iain Potter

@mark you probably need to

@mark you probably need to modify your xdebug config (in an .ini file somewhere, either php.ini or xdebug.ini I'd guess) to point back to your host O/S. The setting you'll need is "xdebug.remote_host". Just set it to the IP of your host O/S, although keep in mind this will need to be the address of the virtualbox adaptor.

Additionally, you can specify a specific phpstorm server by setting the environment variable


Additionally, if your drush command spawns further PHP process, don't forget to increase the "Max simultaneous connections" value (you can see it in Angus' settings screenshot above) otherwise your drush job may appear to hang.


Add Your Comment