Contact Us

Setting up Xdebug on Mac OS X (or Win32 / Linux)

Posted on 21/9/07 by Felix Geisendörfer

If you want to take your debugging to the next level by getting a nice stack / function trace on errors that occur, then you should check out Xdebug by Derick Rethans (who I had the pleasure to meet at php|works). I've only been touching the surface of this powerful extensions so far, but its already been a pleasure to work with and I'll try to write more about it in future. Maybe I can even integrate it into the CakePHP test suite for code coverage analysis at some point.

Anyway, one of the biggest obstacles when getting started with Xdebug was that I had a hard time finding good instructions on how to set it up on Mac OS X (I finally got rid of windows, yeah !). The only good resource I found was stored in Googles cache (wasn't live anymore) and had instructions on how to manually build xdebug from source. However, I didn't have a lot of time back then and compiling would have involved setting up all kinds of additional tools. This was the point when I vaguely remembered that the Komodo IDE was using xdebug. So I did some more research and sure enough, the good folks over at ActivateState actually provide their Xdebug binaries as stand-alone downloads for all major platforms.

On my macbook I'm using MAMP, but the basic concept of setting this up should be cross plattform:

  1. Download the latest Xdebug binaries for your OS from:
  2. Copy the / xdebug.dll for your PHP version to your extensions directory (for MAMP this was: /Applications/MAMP/bin/php5/lib/php/extensions/no-debug-non-zts-20050922/, in Windows its probably C:\php\modules\xdebug.dll)
  3. Find your php.ini file (for my MAMP install this was in /Applications/MAMP/conf/php5/php.ini, under Windows it should be C:\Windows\php.ini)
  4. Add the following lines to your php.ini configuration (MAMP):

or for Windows:


To test if things worked or not run a phpinfo() script and see if xdebug shows up in your list of extensions (you'll probably have to restart Apache first). Once that is accomplished you can start to indulge yourself in discovering all the various configuration options and functions there are.

One of my favorite settings allows to make all file paths that show up in error messages turn into links that will open my text editor for the given file at the right line. For Textmate this is simply a matter of adding this line to your php.ini:

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

Check the manual of your editor of choice to see what "protocol" it is using for accomplishing the same thing. Also make sure to check out if your editor happens to have built-in Remote Debugging support for Xdebug. A list of those editors can be found in the Xdebug documention (Textmate is not in there yet : /).

Alright, I hope some of you find this useful. If you run Windows or Linux there are also more detailed instructions on the Xdebug website itself, I just found the lack of OS X info out there worth making this little blog post. Kudos go out to Derick for writing this awesome extension and ActiveState for providing Mac OS X (and other plattform) binaries for all kinds of PHP versions.

-- Felix Geisendörfer aka the_undefined


You can skip to the end and add a comment.

Yevgeny said on Sep 21, 2007:

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

For widows system there is two way for using textmate style links.
First - use E-texteditor that very young. I dislike it even most of bundles implemented but functionality is very very young.

The second is my solution. I create universal wrapper that process such links and start extarnal application (editor). In mmy case i use notepad++ that also use xdebug for debuging php code.

Also in future i plan to integrate textmate bundles and scripts in it.

Tarique Sani said on Sep 21, 2007:

For Linux users - has a nice lightweight client for Xdebug which is also available as a plugin for Kate (this is not mentioned on the Xdebug site)

Xdebug also runs happily with XAMPP - if you figure out where to put the compiled .so file ;)

Felix Geisendörfer said on Sep 21, 2007:

Tarique: Thanks for that info.

@Everybody: There also is an article describing on how to install Xdebug on Linux w/ XAMPP on the SaniSoft blog:

Yevgeny said on Sep 21, 2007:

The link to my wrapper is
Also i integrate this solution with cakephp (Footnotes article on bakery)

Soon I create extended article (where will possible to open files from cake stack trace) said on Sep 21, 2007:

Felix Geisendorfer's Blog: Setting up Xdebug on Mac OS X (or Win32 / Linux)...


Timo Derstappen said on Sep 21, 2007:

Together with xdebug phpcoverage detects your test coverage while running your testsuite. This is really helpful to find important parts in your application which are still untested:

[...] Felix Geisendorfer shows, in a new blog post today, how to setup XDebug (the popular debugging extension for PHP) on a Mac OSx (or Win32/Linux) system. One of the biggest obstacles when getting started with Xdebug was that I had a hard time finding good instructions on how to set it up on Mac OS X (I finally got rid of windows, yeah !). The only good resource I found was stored in Googles cache (wasn’t live anymore) and had instructions on how to manually build xdebug from source. [...]

Simon said on Sep 21, 2007:

I just installed it through pecl and added the zend_extension line to php.ini

Works prefectly.

JNunez  said on Sep 24, 2007:

For those with fresh installs of MAMP make sure that you add the xdebug directives to the bottom of the php.ini file (after the ZendExtension manager). Also switch to php 4 and turn off APC in the MAMP control panel.

tyler  said on Sep 24, 2007:

Awesome! Thank you!

Remco  said on Sep 27, 2007:

Thanks for sharing this, Felix! Works perfectly :)

jeremy said on Nov 03, 2007:

It installed no problem through macports in OS X 10.5 for me. Thank you for the pointer!

Tesh  said on Nov 19, 2007:

Thanks for sharing this!

Matt said on Dec 17, 2007:

Just got xdebug 2.1dev running today with leopard. The file_link_format is proving to be very useful when developing locally. Thanks.

Joe  said on Jan 13, 2008:

These instructions worked *nearly* perfectly for me. One little hitch (on my 2.4 Ghz Intel Core Duo iMac) is that I had to disable the "Zend Optimizer".

SCUM  said on Jan 30, 2008:

On Leopard, both the pecl install and the Komodo download worked... but they needed to be referenced in php.ini with this line:


The "zend-extension=" line would not load the extension for me.

Antonio said on Feb 28, 2008:

You wrote:
>On of my favorite settings allows to make all file paths ...

Should be:

>One of my favorite settings allows to make all file paths ...

Felix Geisendörfer said on Mar 01, 2008:

Thx Antonio - fixed.

xentek said on Mar 21, 2008:

@scum - that's because it's zend_extension not zend-extension.

For everyone else: This one of the best XDEBUG tutorials I've seen yet:

It will totally get you started on how to properly configure its options, and what to do with its output.

Happy bug hunting!


Olivier  said on Mar 30, 2008:

I ran into some problems when I added the line in my php.ini. For some reason the Zend optimizer had a conflict with xdebug. The php_error.log showed the following error:

[30-Mar-2008 17:17:32] PHP Fatal error: [Zend Optimizer] Zend Optimizer 3.2.2 is incompatible with Xdebug 2.1.0-dev in Unknown on line 0

Apache wouldn't start anymore!

I solved by turning off the Zend Optimizer in





Cheers, Olivier

Dano!  said on May 05, 2008:

Be careful of getting the latest The version I found was v2.1.0-dev, which has some problems with the most recent version of Eclipse and PDT. Tripped me up for quite some time.

From the Eclipse newsgroup:

A change has been made in the xdebug 2.0.3 which appears to causes a problem for PDT using xdebug. So at this time it is not recommended to upgrade to 2.0.3 and to continue using xdebug 2.0.2 with PDT 1.0.2 and the PDT 1.1 Nightly/Integration builds.


The only way I found to get the old version is to download the source from and compile it. If you don't have the Xcode tools, they are not hard to install: insert Disc 2 from the install CDs, open the "Xcode Tools", double click on the XcodeTools.mpkg, and go outside for a bit and enjoy the weather. When you come back, greb the 2.0.2 version of xdebug, unpack it, go to that directory in a terminal, and follow the directions in the README.

Kent said on May 11, 2008:

After compiling xdebug and failing to get the server to start back up, this was nice to find.

Tim Fletcher said on May 12, 2008:


Yes, the install docs on the xdebug site state:

Xdebug does not work together with the Zend Optimizer or any other Zend extension (DBG, APD etc). This is due to compatibility problems with those modules. We will be working on figuring out what the problems are, and of course try to fix those.

I only had to comment out this line


to get it all working.

Great tutorial! Thanks!

scum  said on May 14, 2008:

On Mac OS X (Leopard) on Intel Core 2 Cuo processors, the pre-built binaries do not seem to work. Instead, grab the xdebug binaries at and in the downloaded directory run:



MACOSX_DEPLOYMENT_TARGET=10.5 CFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 -g -Os -pipe -no-cpp-precomp" CCFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 -g -Os -pipe" CXXFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 -g -Os -pipe" LDFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 -bind_at_load" ./configure --enable-xdebug

This will create the module you want in the `modules` directory. Copy these into your php extensions directory (probably /usr/lib/php/extensions/no-debug-non-zts-20060613).


to your php.ini

Restart apache. And you should be good to go.

Felix Geisendörfer said on May 14, 2008:

scum: I run the same setup as you (unless you really mean cuo processors, not duo ^^) and the binaries from komodo work for me.

Stuart  said on Jun 16, 2008:

For what it's worth... I could not get the komodo binary to work for me and I am on the same setup as Felix (same Macbook, MAMP, etc.).

In my apache error logs I could see that the extension failed to load but no clues as to why. I finally compiled everything myself from the binaries on the xdebug site (using version 2.0.2, not the latest also using my own install of phpize... not MAMP's. It is a very fast configure and make so don't worry), copied that over into the extensions dir and Felix's direction then worked fine.

Felix Geisendörfer said on Jun 16, 2008:

Stuart: Tried disabling zend optimizer?

lightspeed  said on Jun 19, 2008:

This was great, thanks. I've got everything going...sorta.

I have two issues: a.) the debugger will not stop at a checkpoint on my *second* page. Checkpoints on the first page are fine. b.) the implicit_flush doesn't seem to work. On or off, I only see my page after the php page completes. I'm running:

Leopard 10.5.3 on 2.4GHz Intel Core 2 Duo.
MAMP 1.7.1, Zend Engine v2.2.0, Xdebug v2.1.0-dev.

Recommendations where to start digging into this?

lightspeed  said on Jun 20, 2008:

compiled xdebug 2.0.2 as instructed above. both issues resolved. :-)

Luke Barton  said on Jun 26, 2008:

To all with issues enabling the extension with MAMP PRO, it seems to ignore the ini @ '/Applications/MAMP/conf/php5/php.ini' completely.

On server start-up it actually overwrites '/Library/Application Support/living-e/MAMP PRO/conf/php.ini' (which is the config loaded by php, see phpinfo();) with the one stored inside the .app contents.

So you need to edit you need to edit '/Applications/MAMP PRO x.x.x/MAMP'

Hope this helps some people.

Ira Rainey  said on Jul 07, 2008:

Luke: Top job on picking that up. I've been banging my head against the wall trying to get this up and running on MAMP Pro. All sorted now though - and using the Komodo binaries. Cheers.

Leopard 10.5.4 on 2GHz Intel Core 2 Duo.
MAMP Pro 1.7.1, Xdebug v2.1.0-dev.

Stuart  said on Jul 08, 2008:

Felix: Yes, I had done that. I'm as certain as I can be that I tried everything (but you know that feeling of "I'm certain I haven't missed anything and it STILL isn't working" and then you find you have indeed missed something). Compiling things myself ended up working for me so for others who are comfortable with terminal and configure, make, make install may just want to go that route.

Joel  said on Jul 10, 2008:

@Luke: I just spent the better part of an hour trying to figure out why MAMP Pro 1.7.1 refused to load the php.ini configuration files. In the end, I simply used the MAMP Pro menu to get File->Edit Template->php5 php.ini and include the directives there. Thanks for pointing out where this template file actually resides.

Pete  said on Aug 21, 2008:

Leopard: 10.5.4
2.4GHZ Intel Core 2 Duo

Still can't get this to work :( Nothing with xdebug appears in my file. I've downloaded the 4.4 version of Mac OS X / x86 off the website listed above, extracted it and used the from the 5.2 folder, the 5.1 folder and the 5.0 folder. None of them allow my mamp to start.

Any suggestions on what I am doing wrong?

Pete  said on Aug 21, 2008:

Fixed: downloaded the Komodo IDE and took the from there, worked.

Thanks for the post (Also ;zend_extension=/Applications/MAMP/bin/php5/zend/lib/ )

Vineet said on Aug 24, 2008:

Your article saved me a lot of time.
It is difficult to get information on php and OSX.

Thanks a lot!

kai  said on Nov 03, 2008:

Thanks Felix! Worked great for me.

dan said on Nov 12, 2008:

Saved me a lot of time too. Thank you for sharing this!

Matt said on Dec 06, 2008:

The Apache that comes with Max OS 10.5 is compiled as 64-bit application, and I think Xdebug is 32-bit. These commands will restart Apache in 32-bit mode, and it now shows up in phpinfo() for me:

sudo apachectl stop
sudo arch -i386 /usr/sbin/httpd

farhaan  said on Dec 06, 2008:

Do you have to have apple developer tools to compile xdebug on a mac. I dont have the developer tools and when i phpize it throws an error

Cannot find config.m4.
Make sure that you run '/usr/bin/phpize' in the top level source directory of the module

ben said on Dec 29, 2008:

I've got xdebug installed fine (showing up in phpinfo()) but I'm trying to get it to work with PHPUnit's code coverage functionality. It keeps telling me "XDebug is not loaded". I've got phpunit working fine with MAMP. Anyone have any ideas?

Nicola Ferruzzi said on Jan 03, 2009:

To get it working using Leopard 10.5.6 with the system php and apache, just download the source of xdebug then follow Scum instructions:


MACOSX_DEPLOYMENT_TARGET=10.5 CFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 -g -Os -pipe -no-cpp-precomp" CCFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 -g -Os -pipe" CXXFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 -g -Os -pipe" LDFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 -bind_at_load" ./configure --enable-xdebug


sudo cp modules/ /usr/lib/php/extensions/no-debug-non-zts-20060613

edit your php.ini and add

zend_extension = "/usr/lib/php/extensions/no-debug-non-zts-20060613/"
xdebug.remote_enable = 1

(you might add all other options listed in the thread)

restart the "Web Sharing" service

php -m

you should see at the bottom

[Zend Modules]

!! :-)

hereNT said on Jan 05, 2009:

I was having a lot of trouble getting this to actually load on my mac with the proper (x86) versions of the debugger from Komodo. I had this same problem trying to compile under XAMPP for linux.

The problem is that MAMP and XAMPP both run as 32 bit. The file for x86 is 64bit, so it can't be loaded.

To get it working on the mac with the Komodo file, I downloaded the PPC version instead and it came up fine.

For the *nix box, I ended up just installing Apache, PHP, etc from source or yum as 64bit. I needed a couple of other extensions besides debug that were giving me the same problem where the extension that I'd compile from the source would be 64 and wouldn't run under the 32bit XAMPP.

Hopefully that helps someone else that's trying to figure out why this isn't working for them :)

hereNT said on Jan 05, 2009:

Nevermind, seems like this mac actually is running a PPC processor, for some reason I thought it was intel. Silly macs.

nasigoreng  said on Apr 18, 2009:

hi guys... i have followed this instruction but i still couldnt get it to work. On php error log i got this error message

PHP Warning: PHP Startup: Unable to load dynamic library '/Applications/MAMP/bin/php5/lib/php/extensions/no-debug-non-zts-20050922//Applications/MAMP/bin/php5/lib/php/extensions/no-debug-non-zts-20050922/

any idea?

nasigoreng  said on Apr 18, 2009:

oops i didn't copy the whole thing

PHP Warning: PHP Startup: Unable to load dynamic library '/Applications/MAMP/bin/php5/lib/php/extensions/no-debug-non-zts-20050922//Applications/MAMP/bin/php5/lib/php/extensions/no-debug-non-zts-20050922/' - (null) in Unknown on line 0

julien said on May 14, 2009:

Thanks for this tutorial and thanks Olivier for your comment, that helped me out!

jalama said on May 15, 2009:

If anyone needs it this is the settings for the php.ini with XAMPP

;xdebug code






arthur said on Jun 11, 2009:

If you want to get KCachegrind working on OSX along side of xdebug, you may find this post helpful get the environment up and running:

Werner Glinka said on Jul 16, 2009:

Great post - it certainly has a long halflive! I researched this several month ago. At that time I used MAMP Pro and run into many problems which let me to set up my Mac dev environs with Entropy PHP, mySQL, Eclipse and XDebug. If anybody is interested in that info you can read about it here:

Ryan Blunden  said on Aug 09, 2009:

If anyone is using Macports and having a hard time of it, try using zend_extension_debug=/path/to/ instead of the standard zend_extension

It took me 3 hours to figure this out and I only came across this tip thanks to a brilliant page at

Matt Young  said on Aug 29, 2009:

I finally got xdebug working on MAMP.

1. Must disable Zend Optimizer. I enable startup error log and see the message indicating Xdebuger is not compitable with it.

2. Must use version 5.2. I initially try 5.3 and it just silently fail!

3. I'm not sure but I think the extension manager must be enabled also.

Blaise Freeman said on Sep 16, 2009:

Some more tips:

4. In MAMP, you have to edit the template for the php.ini file, not the php.ini in the folder structure.

5. You don't need to use Komodo to use their binary in case you were wondering.

This post is too old. We do not allow comments here anymore in order to fight spam. If you have real feedback or questions for the post, please contact us.