Install the PHP Xdebug extension

The Xdebug extension provides debugging and profiling capabilities for PHP scripts.

The Xdebug extension supports PHP 5.6 through PHP 8.4. The Xdebug extension is not yet supported in PHP 8.5. See the Xdebug supported versions chart and the list of Xdebug releases for the specific extension versions that are supported for each PHP version.

Install the Xdebug extension

Installing the extension involves the following steps:

1. Install build dependencies (packages that are required to build the extension).
2. Build the extension’s library file.
3. Enable the extension in the PHP configuration.

Note

You must be logged into your server as root to install PHP extensions.

Install build dependencies

Set environment variables for the package manager.

export DEBIAN_FRONTEND=noninteractive

Install a compiler and other packages that are required for building PHP extensions.

sudo apt-get -y install gcc g++ make autoconf libc-dev pkg-config

Build the extension

The PECL install command compiles the extension’s .so library file.

php8.4

yes '' | sudo pecl8.4-sp install xdebug-3.4.2

php8.3

yes '' | sudo pecl8.3-sp install xdebug-3.4.2

php8.2

yes '' | sudo pecl8.2-sp install xdebug-3.4.2

php8.1

yes '' | sudo pecl8.1-sp install xdebug-3.4.2

php8.0

yes '' | sudo pecl8.0-sp install xdebug-3.4.2

php7.4

yes '' | sudo pecl7.4-sp install xdebug-3.1.5

php7.3

yes '' | sudo pecl7.3-sp install xdebug-3.1.5

php7.2

yes '' | sudo pecl7.2-sp install xdebug-3.1.5

php7.1

yes '' | sudo pecl7.1-sp install xdebug-2.9.8

php7.0

yes '' | sudo pecl7.0-sp install xdebug-2.7.2

php5.6

yes '' | sudo pecl5.6-sp install xdebug-2.5.5

Enable the extension

Configure PHP to load the extension.

php8.4

sudo bash -c "echo zend_extension=xdebug.so > /etc/php8.4-sp/conf.d/xdebug.ini"

php8.3

sudo bash -c "echo zend_extension=xdebug.so > /etc/php8.3-sp/conf.d/xdebug.ini"

php8.2

sudo bash -c "echo zend_extension=xdebug.so > /etc/php8.2-sp/conf.d/xdebug.ini"

php8.1

sudo bash -c "echo zend_extension=xdebug.so > /etc/php8.1-sp/conf.d/xdebug.ini"

php8.0

sudo bash -c "echo zend_extension=xdebug.so > /etc/php8.0-sp/conf.d/xdebug.ini"

php7.4

sudo bash -c "echo zend_extension=xdebug.so > /etc/php7.4-sp/conf.d/xdebug.ini"

php7.3

sudo bash -c "echo zend_extension=xdebug.so > /etc/php7.3-sp/conf.d/xdebug.ini"

php7.2

sudo bash -c "echo zend_extension=xdebug.so > /etc/php7.2-sp/conf.d/xdebug.ini"

php7.1

sudo bash -c "echo zend_extension=xdebug.so > /etc/php7.1-sp/conf.d/xdebug.ini"

php7.0

sudo bash -c "echo zend_extension=xdebug.so > /etc/php7.0-sp/conf.d/xdebug.ini"

php5.6

sudo bash -c "echo zend_extension=xdebug.so > /etc/php5.6-sp/conf.d/xdebug.ini"

Restart PHP-FPM.

php8.4

sudo service php8.4-fpm-sp restart

php8.3

sudo service php8.3-fpm-sp restart

php8.2

sudo service php8.2-fpm-sp restart

php8.1

sudo service php8.1-fpm-sp restart

php8.0

sudo service php8.0-fpm-sp restart

php7.4

sudo service php7.4-fpm-sp restart

php7.3

sudo service php7.3-fpm-sp restart

php7.2

sudo service php7.2-fpm-sp restart

php7.1

sudo service php7.1-fpm-sp restart

php7.0

sudo service php7.0-fpm-sp restart

php5.6

sudo service php5.6-fpm-sp restart

Verify the extension is enabled in PHP.

php8.4

php8.4-sp -i | grep xdebug

php8.3

php8.3-sp -i | grep xdebug

php8.2

php8.2-sp -i | grep xdebug

php8.1

php8.1-sp -i | grep xdebug

php8.0

php8.0-sp -i | grep xdebug

php7.4

php7.4-sp -i | grep xdebug

php7.3

php7.3-sp -i | grep xdebug

php7.2

php7.2-sp -i | grep xdebug

php7.1

php7.1-sp -i | grep xdebug

php7.0

php7.0-sp -i | grep xdebug

php5.6

php5.6-sp -i | grep xdebug

If the extension is enabled, you will see output like the following.

/etc/phpX.Y-sp/conf.d/xdebug.ini,
xdebug
Support Xdebug on Patreon, GitHub, or as a business: https://xdebug.org/support
             Enabled Features (through 'xdebug.mode' setting)
'xdebug://gateway' pseudo-host support => yes
'xdebug://nameserver' pseudo-host support => yes
xdebug.auto_trace => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)
xdebug.cli_color => 0 => 0
xdebug.client_discovery_header => HTTP_X_FORWARDED_FOR,REMOTE_ADDR => HTTP_X_FORWARDED_FOR,REMOTE_ADDR
xdebug.client_host => localhost => localhost
xdebug.client_port => 9003 => 9003
xdebug.cloud_id => no value => no value
...

Uninstall the Xdebug extension

Uninstalling the extension involves the following steps:

1. Disable the extension in the PHP configuration.
2. Remove the extension’s library file.

Disable the extension

Remove the extension’s configuration from PHP.

php8.4

sudo rm /etc/php8.4-sp/conf.d/xdebug.ini

php8.3

sudo rm /etc/php8.3-sp/conf.d/xdebug.ini

php8.2

sudo rm /etc/php8.2-sp/conf.d/xdebug.ini

php8.1

sudo rm /etc/php8.1-sp/conf.d/xdebug.ini

php8.0

sudo rm /etc/php8.0-sp/conf.d/xdebug.ini

php7.4

sudo rm /etc/php7.4-sp/conf.d/xdebug.ini

php7.3

sudo rm /etc/php7.3-sp/conf.d/xdebug.ini

php7.2

sudo rm /etc/php7.2-sp/conf.d/xdebug.ini

php7.1

sudo rm /etc/php7.1-sp/conf.d/xdebug.ini

php7.0

sudo rm /etc/php7.0-sp/conf.d/xdebug.ini

php5.6

sudo rm /etc/php5.6-sp/conf.d/xdebug.ini

Restart PHP-FPM.

php8.4

sudo service php8.4-fpm-sp restart

php8.3

sudo service php8.3-fpm-sp restart

php8.2

sudo service php8.2-fpm-sp restart

php8.1

sudo service php8.1-fpm-sp restart

php8.0

sudo service php8.0-fpm-sp restart

php7.4

sudo service php7.4-fpm-sp restart

php7.3

sudo service php7.3-fpm-sp restart

php7.2

sudo service php7.2-fpm-sp restart

php7.1

sudo service php7.1-fpm-sp restart

php7.0

sudo service php7.0-fpm-sp restart

php5.6

sudo service php5.6-fpm-sp restart

Remove the extension

The PECL uninstall command removes the extension’s .so library file.

php8.4

sudo pecl8.4-sp uninstall xdebug

php8.3

sudo pecl8.3-sp uninstall xdebug

php8.2

sudo pecl8.2-sp uninstall xdebug

php8.1

sudo pecl8.1-sp uninstall xdebug

php8.0

sudo pecl8.0-sp uninstall xdebug

php7.4

sudo pecl7.4-sp uninstall xdebug

php7.3

sudo pecl7.3-sp uninstall xdebug

php7.2

sudo pecl7.2-sp uninstall xdebug

php7.1

sudo pecl7.1-sp uninstall xdebug

php7.0

sudo pecl7.0-sp uninstall xdebug

php5.6

sudo pecl5.6-sp uninstall xdebug