XDebug over SSH into Container with VSCode

Written by James McDonald

January 3, 2021

My Layout

I’m connecting from VSCode running on Windows 10 Pro to the Linux host via SSH. The Linux Host has the project files and there is a docker container running on the Linux Host which provides the LAMP stack development environment.

This is how I got XDebug working

VSCode Xdebug Session

|  Windows 10 Pro with VSCode Installed |
   |   Linux Host with project files  |
   |  /home/jm/onedrive/sites/100pbc  |
   |                |                 |
   |    +---------Docker---------+    |
   |    |       |    |
   |    |           |            |    |
   |    |     docker network     |    |
   |    |           |            |    |
   |    |       |    |
   |    |  [ Docker container ]  |    |
   |    |                        |    |
   |    +------------------------+    |

Project files on Linux host: /home/jm/onedrive/sites/100pbc
Path to project files in docker container: /var/www/100pbc

VSCode Extensions

  • VScode instance running on Windows 10 Pro install the PHP Debug extension by Felix Becker ext install php-debug
  • You also need "Visual Studio Code Remote Development Extension Pack" to allow for SSH to remote host


In the docker container compile and install Xdebug 3

Use the install instructions that come in the php-debug extension in VSCode

PHP Debug Xdebug Install Instructions

Add the following to /etc/php/7.4/apache/php.ini and /etc/php/7.4/cli/php.ini in the Docker container. Adding the configuration to both the apache and cli areas allows you to debug your tests from the command line as well as get debbugging information when navigating your site via a browser.

Note: Make sure you restart the container when you make changes.

Set xdebug.client_host to the docker IP address of the Linux host

**Note: ** xdebug.remote_host didn’t seem to work perhaps it is an old version 2 setting. But xdebug.client_host did.

xdebug.mode = debug
xdebug.remote_enable = 1
; xdebug.remote_connect_back = 1
; xdebug.remote_host =
; this 
xdebug.idekey = "VSCODE"
xdebug.client_port = 9000
xdebug.remote_autostart = 1
xdebug.start_with_request = yes

Check your setup by adding a file with phpinfo(); into somewhere accessible to your containers Webserver. You should see XDebug listed

Xdebug phpinfo

Configure launch.json

/home/jm/onedrive/sites/100pbc/.vscode/launch.json on the remote linux host

hostname: is set so the XDebug client in VSCode will listen to the docker IPv4 Address of the Linux host

    // 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": 9000,
            "hostname": "",
            "pathMappings": {
                "/var/www/100pbc/": "${workspaceRoot}/"
           "log": true
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000


  1. very grateful developer

    Your article should have more comments! I couldn’t find anywhere a way to make it work this layout!


Submit a Comment

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

You May Also Like…


This is a graphic I use to figure out which section to add the firewall rules to in the Unifi UDM/USG controller....