This section describes on how to install Xdebug.

Precompiled Windows Modules

There are a few precompiled modules for Windows, they are all for the non-debug version of PHP. You can get those at the download page. Follow these instructions to get Xdebug installed.

PECL Installation

As of Xdebug 0.9.0 you can install Xdebug through PEAR/PECL. This only works with with PEAR version 0.9.1-dev or higher and some UNIX.

Installing with PEAR/PECL is as easy as:

# pecl install xdebug

but you still need to add the correct line to your php.ini: (don't forget to change the path and filename to the correct one — but make sure you use the full path)


Note: You should ignore any prompts to add "extension=xdebug.so" to php.ini — this will cause problems.

Installation on Mac OS X via Homebrew

PHP and Xdebug are available from the unofficial Mac OS X package manager Homebrew. If you use PHP installed via Homebrew (see this installation guide for details on how to do that) Xdebug can be installed via brew install:

# brew install <php-version>-xdebug


# brew install php56-xdebug

You can also use brew search to locate the specific package you need:

# brew search xdebug

The Xdebug extension will be enabled per default after the installation, additional configuration of the extension should be done by adding a custom ini-file to /usr/local/etc/php/<php-version>/conf.d/ . See the Caveats output at the end of the installation for more details.

Installation From Source

You can download the source of the latest stable release 2.2.5. Alternatively you can obtain Xdebug from GIT:

git clone git://github.com/xdebug/xdebug.git

This will checkout the latest development version which is currently 2.2.5. You can also browse the source at https://github.com/derickr/xdebug.


There is a wizard available that provides you with the correct file to download, and which paths to use.

You compile Xdebug separately from the rest of PHP. Note, however, that you need access to the scripts 'phpize' and 'php-config'. If your system does not have 'phpize' and 'php-config', you will need to compile and install PHP from a source tarball first, as these script are by-products of the PHP compilation and installation processes. (Debian users can install the required tools with apt-get install php5-dev). It is important that the source version matches the installed version as there are slight, but important, differences between PHP versions. Once you have access to 'phpize' and 'php-config', do the following:

  1. Unpack the tarball: tar -xzf xdebug-2.2.5.tgz. Note that you do not need to unpack the tarball inside the PHP source code tree. Xdebug is compiled separately, all by itself, as stated above.
  2. cd xdebug-2.2.5
  3. Run phpize: phpize (or /path/to/phpize if phpize is not in your path). Make sure you use the phpize that belongs to the PHP version that you want to use Xdebug with. See this FAQ entry if you're having some issues with finding which phpize to use.
  4. ./configure --enable-xdebug
  5. make
  6. make install

Configure PHP to Use Xdebug

  1. add the following line to php.ini: zend_extension="/wherever/you/put/it/xdebug.so". For PHP versions earlier than 5.3 and threaded usage of PHP (Apache 2 worker MPM or the ISAPI module), add: zend_extension_ts="/wherever/you/put/it/xdebug.so" instead. Note: In case you compiled PHP yourself and used --enable-debug you would have to use zend_extension_debug=. Note: If you want to use Xdebug and OPCache together, you must load Xdebug after OPCache. Otherwise, they won't work properly. From PHP 5.3 onwards, you always need to use the zend_extension PHP.ini setting name, and not zend_extension_ts, nor zend_extension_debug. However, your compile options (ZTS/normal build; debug/non-debug) still need to match with what PHP is using.
  2. Restart your webserver.
  3. Write a PHP page that calls 'phpinfo()' Load it in a browser and look for the info on the Xdebug module. If you see it next to the Zend logo, you have been successful! You can also use 'php -m' if you have a command line version of PHP, it lists all loaded modules. Xdebug should appear twice there (once under 'PHP Modules' and once under 'Zend Modules').


Xdebug does not work together with the Zend Optimizer or any other extension that deals with PHP's internals (DBG, APD, ioncube etc). This is due to compatibility problems with those modules.

Debugclient Installation

Unpack the Xdebug source tarball and issue the following commands:

$ cd debugclient
$ ./configure --with-libedit
$ make
# make install

This will install the debugclient binary in /usr/local/bin unless you don't have libedit installed on your system. You can either install it, or leave out the '--with-libedit' option to configure. Debian 'unstable' users can install the library with apt-get install libedit-dev libedit2.

If the configure script can not find libedit and you are sure you have (and it's headers) installed correctly and you get link errors like the following in your configure.log:

/usr/lib64/libedit.so: undefined reference to `tgetnum'
/usr/lib64/libedit.so: undefined reference to `tgoto'
/usr/lib64/libedit.so: undefined reference to `tgetflag'
/usr/lib64/libedit.so: undefined reference to `tputs'
/usr/lib64/libedit.so: undefined reference to `tgetent'
/usr/lib64/libedit.so: undefined reference to `tgetstr'
collect2: ld returned 1 exit status

you need to change your configure command to:

$ LDFLAGS=-lncurses ./configure --with-libedit

This site and all of its contents are Copyright © 2002-2017 by Derick Rethans.
All rights reserved.