VSCode – XDebug 3 – MacOS – Docker Desktop

Written by James McDonald

May 11, 2021

My setup

  • MacOS Big Sur version 11.2.3 (20D91)
  • VSCode version: 1.56.0 with felixfbecker.php-debug (v1.15.1) extension installed
  • Docker Desktop 3.3.1 (63152)
  • Docker container running Ubuntu 20.04 Apache, PHP 7.4.3 and Xdebug v3.0.4

Because I was running php-fpm on my Macbook I got an EADDRINUSE error when trying to use port 9000 so I changed it to 9001

Checking what is using your TCP port/s on MacOS

# lsof -P | grep <yourport>
# e.g.
lsof -P | grep 9000

VSCode Configuration for XDebug

Install the felixfbecker.php-debug extension

Contents of .vscode/launch.json

Regarding path mappings the left hand value “/var/www/html” is the path to your PHP code inside the docker container. The ${workspaceRoot} value resolves to the path to your code on your MacBook

    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9001,
            "pathMappings": {
                "/var/www/html/": "${workspaceRoot}/"
           "log": false

Inside the container

Install XDebug 3.x

Instructions on compiling and installing XDebug are available in the felixfbecker.php-debug vscode extension

Add XDebug configuration to container

Enable xdebug in the Apache and CLI PHP environments (you want enable CLI xdebug if you are debugging using phpunit or the running PHP scripts from the command line)

Contents of /etc/php/7.4/cli/conf.d/20-xdebug.ini and /etc/php/7.4/apache2/conf.d/20-xdebug.ini

zend_extension = /usr/lib/php/20190902/xdebug.so

Contents of /etc/php/7.4/apache2/conf.d/25-xdebug.ini and /etc/php/7.4/cli/conf.d/25-xdebug.ini

Critical thing is xdebug.remote_connect_back = 0 as the docker container can call out to the host but the host can’t talk back to the container

xdebug.mode = debug
xdebug.remote_enable = 1
xdebug.remote_connect_back = 0
xdebug.idekey = "VSCODE"
xdebug.client_port = 9001
xdebug.remote_autostart = 1
xdebug.start_with_request = yes

Once you have xdebug installed and the config installed. Restart the container

docker restart <container>


Submit a Comment

Your email address will not be published. Required fields are marked *

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

The reCAPTCHA verification period has expired. Please reload the page.

You May Also Like…