Installation

This section describes on how to install Xdebug.

Installing with PECL

You can install Xdebug through PECL on Linux & macOS with Homebrew. Run:

pecl install xdebug

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

In some cases pecl will change the php.ini file to add a configuration line to load Xdebug. You can check whether it did by running php -v. If Xdebug shows up with a version number, than you're all set and you can configure Xdebug's other functions, such as , or Profiling.

If pecl did not add the right line, skip to the Configure PHP section.

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

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.8.

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.0beta1. This development branch might not always work as expected, and may have bugs.

You can also browse the source on GitHub 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.8.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.8

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

   To find out which php.ini file to modify, run a script with the following:

   <?php
   var_dump(php_ini_loaded_file(), php_ini_scanned_files());
   

   Alternatively, you can run php --ini on the command line.

   Note: There could be more than one php.ini file. In many set-ups there is a different one for the command line (often cli/php.ini) and the web server (often fpm/php.ini).

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

2. Restart your webserver, or PHP-FPM, depending on what you are using.

3. Verify that Xdebug is now loaded.

   Create a PHP page that calls xdebug_info(). If you request the page through the browser, it should show you an overview of Xdebug's settings and log messages.

   On the command line, you can also run php -v. Xdebug and its version number should be present as in:

   PHP 7.4.10 (cli) (built: Aug 18 2020 09:37:14) ( NTS DEBUG )
   Copyright (c) The PHP Group
   Zend Engine v3.4.0, Copyright (c) Zend Technologies
     with Zend OPcache v7.4.10-dev, Copyright (c), by Zend Technologies
     with Xdebug v3.0.0-dev, Copyright (c) 2002-2020, by Derick Rethans
   

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