If you find Xdebug useful, please consider supporting the project.

Installation

This section describes on how to install Xdebug.

Installing on Linux & Macs

You can install Xdebug through PECL on Linux & macOS1. You can install Xdebug with PECL with:

pecl install xdebug

When that is done, 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):

zend_extension="/usr/local/php/modules/xdebug.so"

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

Installing on Windows

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.

Installation From Source

Obtain

You can download the source of the latest stable release 2.9.0.

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 3.0.0dev. You can also browse the source at https://github.com/xdebug/xdebug.

Compile

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. You need access to the scripts phpize and php-config. If your system does not have phpize and php-config, you will need to install the PHP development headers.

Debian users can do that with:

apt-get install php-dev

And RedHat and Fedora users with:

yum install php-devel

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, take the following steps:

  1. Unpack the tarball:

    tar -xzf xdebug-2.9.0.tgz

    You should not unpack the tarball inside the PHP source code tree. Xdebug is compiled separately, all by itself, as stated above.

  2. cd xdebug-2.9.0

  3. phpize

    If phpize is not in your path, please make sure that it is by expanding the PATH environment variable. 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

  1. Add the following line to php.ini:

    zend_extension="/wherever/you/put/it/xdebug.so"

    Note: If you want to use Xdebug and OPCache together, you must have the zend_extension line for Xdebug after the line for OPCache. Otherwise, they won't work properly.

  2. Restart your webserver.

  3. Create a PHP page that has 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!

    On the command line, you can also php -m. This lists all loaded modules. Xdebug should appear twice there (once under 'PHP Modules' and once under 'Zend Modules').

With Xdebug loaded, you can now enable individual features, such as Step Debugging, or Profiling PHP Scripts.


1 On macOS, you should have PHP installed with Homebrew.