Skip to content

Instantly share code, notes, and snippets.

@antfroger
Last active July 4, 2025 16:09
Show Gist options
  • Select an option

  • Save antfroger/1f2b24fdba0f215a41c8a94e8aa062f7 to your computer and use it in GitHub Desktop.

Select an option

Save antfroger/1f2b24fdba0f215a41c8a94e8aa062f7 to your computer and use it in GitHub Desktop.
Using xdebug with Windows 10, WSL2, Docker and VS Code

Configuring xdebug to work with Windows 10, WSL2, Docker and VS Code

  1. Install and configure xdebug in Docker
RUN ...
COPY ...
  1. Setup VS Code PHP Debug is the extension to debug PHP in VS Code .vscode/lauch.json ...

  2. Debugging in Chrome Install Xdebug helper to debug in Chrome

  3. Configure Windows Defender Firewall

New-NetFirewallRule -DisplayName "WSL" -Direction Inbound  -InterfaceAlias "vEthernet (WSL)"  -Action Allow

More about this issue here

More ... https://xdebug.org/docs/step_debug

# .vscode/lauch.json
# one configuration file per project
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"port": 5902,
"pathMappings": {
"/var/www/my-app": "${workspaceFolder}"
},
"hostname": "localhost"
},
]
}
zend_extension=/path/to/xdebug.so
xdebug.mode=debug,develop
#xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=5902
@apmyp1990
Copy link

Hi,
thanks for the guide!
I am running Win11 and it should be the same, but its not working for me. I ran the powershell command, and I added a rule for ESET Internet Security, but it still wont hit the breakpoint.

Any suggestions?

Thanks in advance

@tadeobarranco
Copy link

Hi,

I just followed your guide but even though I am not able to check anything because every time I refresh the page it only refreshes without showing me any data.

Is there a way I can talk to you and get your services for support?

@r0bchain
Copy link

r0bchain commented May 16, 2022

I've followed all the steps as well, but it is not working for me. The xdebug logs looks good, but not errors, nor warnings at all.

[18] Log opened at 2022-05-16 05:49:07.140566
[18] [Step Debug] INFO: Connecting to configured address/port: host.docker.internal:5902.
[18] [Step Debug] INFO: Connected to debugging client: host.docker.internal:5902 (through xdebug.client_host/xdebug.client_port). :-)
[18] [Step Debug] -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" fileuri="file:///var/www/html/webroot/info.php" language="PHP" xdebug:language_version="7.4.19" protocol_version="1.0" appid="18"><engine version="3.1.4"><![CDATA[Xdebug]]></engine><author><![CDATA[Derick Rethans]]></author><url><![CDATA[https://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2022 by Derick Rethans]]></copyright></init>

[18] [Step Debug] <- feature_set -i 1 -n resolved_breakpoints -v 1
[18] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="1" feature="resolved_breakpoints" success="1"></response>

[18] [Step Debug] <- feature_set -i 2 -n notify_ok -v 1
[18] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="2" feature="notify_ok" success="1"></response>

[18] [Step Debug] <- feature_set -i 3 -n extended_properties -v 1
[18] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="3" feature="extended_properties" success="1"></response>

@StefanRickli
Copy link

For future reference... I thought the hostname line wasn't needed. This caused my php debugger's autoconfig to listen on :::5902 (i.e. IPv6) and thus wouldn't accept a connection from the docker IPv4 network.

@StefanRickli
Copy link

StefanRickli commented Jul 20, 2023

I've followed all the steps as well, but it is not working for me. The xdebug logs looks good, but not errors, nor warnings at all.

[18] Log opened at 2022-05-16 05:49:07.140566
[18] [Step Debug] INFO: Connecting to configured address/port: host.docker.internal:5902.
[18] [Step Debug] INFO: Connected to debugging client: host.docker.internal:5902 (through xdebug.client_host/xdebug.client_port). :-)
[18] [Step Debug] -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" fileuri="file:///var/www/html/webroot/info.php" language="PHP" xdebug:language_version="7.4.19" protocol_version="1.0" appid="18"><engine version="3.1.4"><![CDATA[Xdebug]]></engine><author><![CDATA[Derick Rethans]]></author><url><![CDATA[https://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2022 by Derick Rethans]]></copyright></init>

[18] [Step Debug] <- feature_set -i 1 -n resolved_breakpoints -v 1
[18] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="1" feature="resolved_breakpoints" success="1"></response>

[18] [Step Debug] <- feature_set -i 2 -n notify_ok -v 1
[18] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="2" feature="notify_ok" success="1"></response>

[18] [Step Debug] <- feature_set -i 3 -n extended_properties -v 1
[18] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="3" feature="extended_properties" success="1"></response>

Increase the Xdebug loglevel to 10 (xdebug.log_level = 10). Then you see how it compares the file paths. Maybe your path mapping is misconfigured.

@androsland
Copy link

androsland commented Sep 12, 2024

I'll leave this here for anyone that uses docker-compose.yml and can't get this to work.

So, for me, the Configure Windows Defender Firewall step wasn't necessary.

I only needed to add host.docker.internal:host-gateway as an extra_hosts to my service (docker-compose.yml) like this:

services:
  wordpress:
    build:
      context: .
      dockerfile: Dockerfile-wordpress # this is the filename of your Dockerfile
    extra_hosts:
      - "host.docker.internal:host-gateway"

and everything worked!
I found this here: https://blog.bitexpert.de/blog/win10_wsl2_docker_xdebug

Note: In my Dockerfile, I installed xdebug like this:

RUN pecl install xdebug \
    && docker-php-ext-enable xdebug

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment