Xdebug 3 is the essential debugging extension for PHP. It enables step-by-step debugging, code coverage analysis, and profiling. This guide installs Xdebug 3 for PHP 8.3 on Ubuntu 24.04 LTS and configures it for use with VS Code.

Tested and valid on:

  • Ubuntu 24.04 LTS

Prerequisites

  • Ubuntu 24.04 LTS server or desktop
  • PHP 8.3 installed
  • Composer installed
  • VS Code with PHP Debug extension (optional, for IDE integration)

Step 1 – Install Xdebug 3

Install via the PECL package or the Ondrej PPA:

sudo apt install php8.3-xdebug -y

Step 2 – Verify Xdebug is Loaded

Check that the extension is active:

php8.3 -v

You should see with Xdebug v3.x in the output.

Step 3 – Configure Xdebug for Development

Edit the Xdebug configuration file:

sudo nano /etc/php/8.3/mods-available/xdebug.ini

Add:

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

Step 4 – Restart PHP-FPM

Apply the configuration:

sudo systemctl restart php8.3-fpm

Step 5 – Configure VS Code

Install the PHP Debug extension from the VS Code marketplace, then add a launch configuration to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003
  }]
}

Step 6 – Test the Debugger

Set a breakpoint in VS Code, start listening (F5), then make a request to your PHP app. Execution should pause at the breakpoint.

Step 7 – Enable Profiling (optional)

To profile PHP performance, change the mode:

xdebug.mode=profile
xdebug.output_dir=/tmp/xdebug_profiles

Open the .cachegrind files with tools like KCachegrind or Webgrind.

Conclusion

Xdebug 3 is now configured for PHP 8.3 on Ubuntu 24.04 LTS. Never enable Xdebug in a production environment — it significantly reduces performance. Use it exclusively in development or staging.