Xdebug is the de facto debugging and profiling extension for PHP, giving you step-by-step execution, variable inspection, stack traces, and code coverage reports. Installing it on RHEL 8 requires a few extra steps compared to other distributions because RHEL’s default PHP packages do not include Xdebug in their repos. This tutorial walks through installation from the Remi repository and via PECL, configuring the extension for remote debugging, and integrating it with both VS Code and PhpStorm. You will also learn how to ensure Xdebug is disabled in production.

Prerequisites

  • RHEL 8 server or workstation with root or sudo access
  • PHP 7.4, 8.0, 8.1, or 8.2 already installed
  • EPEL 8 repository enabled (dnf install -y epel-release)
  • The Remi repository configured (recommended) or php-devel and gcc for PECL builds
  • A running Apache or Nginx + PHP-FPM stack for testing

Step 1 — Install Xdebug from the Remi Repository

The Remi repository packages Xdebug for every supported PHP version and is the easiest installation path. Enable the Remi repo and install the package that matches your PHP version.

dnf install -y https://rpms.remirepo.net/enterprise/remi-release-8.rpm
dnf module enable -y php:remi-8.1
dnf install -y php-pecl-xdebug3
php --version
php -m | grep -i xdebug

If you prefer PHP 8.2 or another version, substitute php:remi-8.2 in the module enable command. Skip to Step 3 if Xdebug loaded successfully.

Step 2 — Alternative: Install Xdebug via PECL

If you are not using Remi or need the latest release, build Xdebug from source with PECL. Install the required build tools first.

dnf install -y php-devel php-pear gcc make autoconf
pecl channel-update pecl.php.net
pecl install xdebug
echo "zend_extension=$(php -r 'echo ini_get("extension_dir");')/xdebug.so" 
  > /etc/php.d/15-xdebug.ini
php -m | grep -i xdebug

Step 3 — Configure xdebug.ini

Create or edit the dedicated Xdebug ini file. The settings below configure step-debugging mode with VS Code or PhpStorm listening on port 9003.

cat > /etc/php.d/15-xdebug.ini << 'EOF'
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log=/var/log/xdebug.log
xdebug.idekey=VSCODE
EOF
systemctl restart php-fpm

If you are debugging from a remote workstation, replace 127.0.0.1 with your workstation’s IP address. Set xdebug.idekey=PHPSTORM when using PhpStorm.

Step 4 — Configure VS Code PHP Debug Extension

Install the PHP Debug extension by Xdebug in VS Code, then add a launch configuration to .vscode/launch.json in your project.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html/myapp": "${workspaceFolder}"
      }
    }
  ]
}

Press F5 in VS Code to start listening, then load a page in your browser. VS Code will pause on the first line if breakpoints are set.

Step 5 — Configure PhpStorm

In PhpStorm, go to Settings → PHP → Debug and confirm the Xdebug port is 9003. Then enable the phone icon (Start Listening for PHP Debug Connections) in the toolbar. Add a server under Settings → PHP → Servers with path mappings matching the pathMappings from the VS Code config above. PhpStorm will automatically detect the PHPSTORM IDE key.

Step 6 — Disable Xdebug in Production

Xdebug imposes a measurable performance overhead and must never run in production. The safest approach is to rename the ini file rather than uninstalling the package, making it trivial to re-enable on demand.

mv /etc/php.d/15-xdebug.ini /etc/php.d/15-xdebug.ini.disabled
systemctl restart php-fpm
php -m | grep -i xdebug   # should return nothing

Alternatively, set xdebug.mode=off in the ini file to keep the extension loaded but fully dormant with near-zero overhead.

Conclusion

You have installed Xdebug on RHEL 8 using either the Remi repository or PECL, configured step-debugging with the correct ini directives, and integrated it with VS Code and PhpStorm. The final step showed how to safely disable Xdebug in production so it never affects live performance. With step-debugging in place, you can set breakpoints, inspect variables, and trace execution flow rather than relying on var_dump and log files.

Next steps: How to Harden PHP on RHEL 8, How to Profile PHP Applications with Xdebug on RHEL 8, and How to Set Up PHP-FPM with Nginx on RHEL 8.