Installation

This section describes on how to install Xdebug.

How you install Xdebug depends on your system. There are the following possibilities:

• Linux with a package manager such as apt, yum, or something else.
• Linux without an Xdebug package with PECL.
• macOSX with homebrew, through PECL.
• Windows, with help from a wizard.
• Unix-like operating systems, from source.

Installing on Linux #

Installing Xdebug with a package manager is often the fastest way. Depending on your distribution, run the following command:

• Alpinelinux:
  sudo apk add php7-pecl-xdebug, or
  sudo apk add php8-pecl-xdebug
• Arch Linux:
  sudo pacman -S xdebug
• CentOS:
  sudo yum install php-xdebug
• CentOS (Remi Repo):
  sudo yum install php74-php-xdebug3, or
  sudo yum install php80-php-xdebug3, or
  sudo yum install php81-php-xdebug3
• Debian (9/stretch, testing/buster/bullseye/sid):
  sudo apt-get install php-xdebug
• Fedora (32):
  sudo yum install php-xdebug
• Fedora (Remi Repo):
  sudo yum install php74-php-xdebug3
• Gentoo:
  emerge dev-php/xdebug
• Manjaro (20.1/Mikah):
  sudo pacman -S xdebug
• RHEL:
  sudo yum install php-xdebug
• RHEL (Remi Repo):
  sudo yum install php74-php-xdebug3
• SUSE (openSUSE, Enterprise):
  sudo zypper in php7-xdebug, or
  sudo zypper in php8-xdebug
• Ubuntu (18.04 LTS/Bionic, 20.04 LTS/Focal):
  sudo apt-get install php-xdebug
• Ubuntu (Ondřej Surý's PPA):
  sudo apt-get install php7.4-xdebug, or
  sudo apt-get install php8.0-xdebug, or
  sudo apt-get install php8.1-xdebug

Xdebug's latest version is 3.4.0.

For packages that have the PHP version in the package name, such as in php81-php-xdebug3, you can substitute the PHP version with the one that matches the PHP version that you are running.

Linux distributions might be providing an old and/or outdated version. If the package manager installs a version that is no longer supported (see Supported Versions), please install Xdebug with PECL, or from source instead.

Installing with PECL #

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

Prerequisites:

• macOS:
  • Xcode's command line tools (run: xcode-select --install).
  • PHP installed through Homebrew.
• Linux:
  • GCC and associated libraries.
  • PHP development headers (see Compile below).

Run:

pecl install xdebug

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 Step Debugging, or Profiling.

If it is there, you can skip to the What's Next? section.

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

Issues on macOS #

On Apple M1 hardware, programs can either be compiled for the native M1/ARM64 architecture, or for the emulated x86_64 architecure. Sometimes there is a mismatch with the default and PECL will fail, or Xdebug won't load with a message such as:

PHP Warning:  Failed loading Zend extension 'xdebug.so' (tried: /opt/homebrew/lib/php/pecl/20190902/xdebug.so (dlopen(/opt/homebrew/lib/php/pecl/20190902/xdebug.so, 9): no suitable image found.  Did find:
        /opt/homebrew/lib/php/pecl/20190902/xdebug.so: mach-o, but wrong architecture
        /opt/homebrew/lib/php/pecl/20190902/xdebug.so: stat() failed with errno=22), /opt/homebrew/lib/php/pecl/20190902/xdebug.so.so (dlopen(/opt/homebrew/lib/php/pecl/20190902/xdebug.so.so, 9): image not found)) in Unknown on line 0

You can verify what your PHP's architecture is with:

file `which php`

If that says arm64e, then you need to run:

arch -arm64 sudo pecl install xdebug

And if it's x86_64, then you need to run:

arch -x86_64 sudo pecl install xdebug

¹ 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 3.4.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.5.0dev. 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. If you downloaded a tarball, unpack it:

   tar -xzf xdebug-3.4.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. Change into the source directory:

   1. tarball: cd xdebug-3.4.0
   2. GIT clone: cd xdebug

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. Find out which PHP ini file to modify.

   Run a script with the following to find all configuration files that PHP has loaded:

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

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

   If there is a file with xdebug in the name, such as /etc/php/7.4/cli/conf.d/99-xdebug.ini, then this is the file to use.

   If that file does not exist, but there are other files in a conf.d or similar directory, you can create a new file there too. Please name it 99-xdebug.ini in that case.

   Otherwise, modify the php.ini file that is displayed through the script, or php --ini command.

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

   If you want to use Xdebug and OPCache together, you must have the zend_extension line for Xdebug below the line for OPCache, or in a file starting with a higher number (ie. 99-xdebug.ini vs 20-opcache.ini), otherwise they won't work properly together.

2. Add the following line to this PHP ini file:

   zend_extension=xdebug

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

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

   If Xdebug does not show up, or you get a warning from PHP that an xdebug.so file or similar was not found, you might need to use the full path instead of just zend_extension=xdebug, such as zend_extension=/usr/lib/php/20190902/xdebug.so.

   On Windows, you should place the php_xdebug.dll in the ext/ directory, which is a child directory in your PHP installation tree.

If you have trouble with this, please refer to the installation wizard to help you guide through this process.

What's Next? #

With Xdebug loaded, you can now enable individual features, such as Step Debugging, or Profiling. Information on what these featers are, how they work, and how to configure them is available on each feature's documentation page:

• Step Debugging — Analyse PHP code while it runs
• Profiling — Check your application for performance issues
• Function Trace — Show every function call, assignment, and return value
• Code Coverage Analysis — Analyse whether your tests cover your whole code base

Related Settings and Functions #

• string xdebug.log =
• integer xdebug.log_level = 7
• string xdebug.mode = develop

• xdebug_info() : mixed

[2693358] Log opened at 2020-09-02 07:19:09.616195
[2693358] [Step Debug] INFO: Connecting to configured address/port: localhost:9003.
[2693358] [Step Debug] ERR: Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port).
[2693358] [Profiler] ERR: File '/foo/cachegrind.out.2693358' could not be opened.
[2693358] [Profiler] WARN: /foo: No such file or directory
[2693358] [Tracing] ERR: File '/foo/trace.1485761369' could not be opened.
[2693358] [Tracing] WARN: /foo: No such file or directory
[2693358] Log closed at 2020-09-02 07:19:09.617510

INFO: Connecting to configured address/port: localhost:9003.
ERR: Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port).

ERR: File '/foo/cachegrind.out.2693358' could not be opened.
WARN: /foo: No such file or directory

ERR: File '/foo/trace.1485761369' could not be opened.
WARN: /foo: No such file or directory

<init
    xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug"
    fileuri="file:///home/httpd/www.xdebug.org/html/router.php"
    language="PHP" xdebug:language_version="7.4.11-dev"
    protocol_version="1.0" appid="2693358" idekey="XDEBUG_ECLIPSE">
        <engine version="3.0.0-dev"><![CDATA[Xdebug]]></engine>
        <author><![CDATA[Derick Rethans]]></author>
        <url><![CDATA[https://xdebug.org]]></url>
        <copyright><![CDATA[Copyright (c) 2002-2020 by Derick Rethans]]></copyright>
</init>

<- feature_set -i 4 -n extended_properties -v 1
-> <response
       xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug"
       command="feature_set" transaction_id="4" feature="extended_properties" success="1">
   </response>

<- step_into -i 9
-> <response
       xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug"
       command="step_into" transaction_id="9"
       status="break" reason="ok">
           <xdebug:message filename="file:///home/httpd/www.xdebug.org/html/router.php" lineno="3">
           </xdebug:message>
   </response>

/tmp/systemd-private-ea3cfa882b4e478993e1994033fc5feb-apache.service-FfWZRg

array(3) {
  [0] =>
  string(5) "debug"
  [1] =>
  string(7) "develop"
  [2] =>
  string(5) "trace"
}

array(1) {
  [0] =>
  string(11) "compression"
}