Installing Xdebug on Mac OS X

Xdebug is an incredibly powerful PHP extension that helps you debug scripts by providing a lot of valuable debugging information. It saves you from having to write your own debugging function for catching errors, at least during the development stage of a web application and certainly provides a lot more information than the standard PHP error messages!

Xdebug also provides the following: –

  • Stack traces and function traces in error messages with:
    • Full parameter display for user defined functions
    • Function name, file name and line indications
  • Support for member functions
  • Memory allocation
  • Protection for infinite recursions
  • Profiling information for PHP scripts
  • Code coverage analysis
  • Capabilities to debug your scripts interactively with a debug client

From the above you can see it’s a very powerful tool that every web developer should have installed on his or her machine and is in-fact included with quite a few commercial IDE programs. Surprisingly, Xdebug is actually open-source, so without further ado… I’ll show you how you can easily install it on your Apple Mac using pre-built binaries


This tutorial assumes you have the following already set up: –

  • Apple Mac OS 10.4
  • Apache (Using Apple’s version that came with OS X)
  • PHP 5 Module (I use PHP 5 from
  • Some PHP files you can test and debug with


Xdebug doesn’t provide any pre-built binaries for Mac OS X, which means we would have to download the source code and compile Xdebug ourselves. Luckily a commercial IDE called Komodo IDE (made by ActiveState who you might remember as the company that makes Perl for Windows), distributes Xdebug with their program and have kindly made their Xdebug binaries available for download. Navigate to the remote debugging page on their website and click on the PHP Remote Debugging option. Make sure you choose Mac OS X / x86 if you have an Intel Mac.
Once downloaded, extract the contents and click on the folder corresponding to your PHP version (I chose 5.2). You should see a single file called This is our PHP extension… drag it into your user folder.

Now we need to copy the extension into our PHP extensions folder. Drop into the Terminal application and if you used the Entropy PHP 5 extension, you’ll find the PHP folder at /usr/local/php5. The extensions folder is in lib/php/extensions.

At the terminal type:

cd /usr/local/php5/lib/php/extensions

List the contents and you should see a folder called no-debug-non-zts-20060613 or similar, change directory into here. We’ll now move the file into this folder and rename it xdebug. Note: You’ll get prompted for your password since we’re editing system files.

cd no-debug-non-zts-20060613
sudo mv ~/ xdebug

Nearly there, we now need to create an .ini file to tell PHP to load in the extension. Change directory to /usr/local/php5/php.d and using vi or your favourite editor create a file called 80-extension-xdebug.ini. Note: You’ll get prompted for your password since we’re editing system files.

cd /usr/local/php5/php.d
sudo vi 80-extension-xdebug.ini

Copy and paste the following into the text file you’ve just created, adjusting the path to where your extensions directory is located.


If you have TextMate, you can add the following line to the config file. This makes clickable error messages that load up the offending PHP file in TextMate and jump to the line containing the error. This is very handy indeed!

xdebug.file_link_format = "txmt://open?url=file://%f&line=%l"

Once your ready to save the config file, close vi by typing ‘:x’ followed by the return key. Restart Apache using your favourite method or simply reboot the whole machine.
Test your new Xdebug configuration by creating a PHP file, which obviously has an error in it such as calling a function that doesn’t exist. Test the PHP file and you should see a lovely coloured error message with a stack trace! You’re all ready to go!


If you’re interested in getting the most out of Xdebug, I recommend checking out some of the documentation on the Xdebug site. Of particular interest is using the profiler and the basics, which are always good to master.