From the Terminal

Installing XDebug on anything for VSCode in 5 minutes (XDebug 3.x)

This guide is for XDebug 3.x only.

For XDebug 2.x clear here.


I see a lot of over complicated guides on XDebug so I'll simplify things real quick for everyone.

Visual Studio Code has debugging support out of the box. Click on the Debug icon in the left bar (OS X: ⇧⌘D, Windows / Linux: CTRL+SHIFT+D) then click on the cog icon which should open your launch.json file or create one if none exists.

You must have the PHP XDebug extension installed of course.

Now add this to your launch.json file you have open:

            "type": "php",
            "request": "launch",
            "name": "Listen For XDebug",
            "port": 9003,
            "pathMappings": {
                "/var/www/": "${workspaceRoot}"
            "xdebugSettings": {
                "max_children": 256,
                "max_data": -1,
                "max_depth": 5
            "ignore": [

Make sure you change /var/www/ to where your code is on your local server.

Set this in your php.ini

xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.idekey = VSCODE
xdebug.client_port = 9003
xdebug.client_host = ""
xdebug.discover_client_host  = 1
xdebug.cli_color = 1

You might need to do it twice. Once for CLI and once for PHP-FPM!


Typical locations for your php.ini file:

  • Linux: /etc/php/{$version}/php.ini
  • macOS (Homebrew): /usr/local/etc/php/{$version}/php.ini

Don't forget to restart php-fpm!

Now start the debugger by hitting the green play button.