Unable to get PHPStorm to connect to xdebug running in WSL 2

I am having trouble getting PHPStorm 2020.2 to work with xdebug with the following setup:
WSL2 running Ubuntu 20, with php and php-xdebug installed. Whenever I run my tests with debugging enabled it says "Connection was not established.".

This is what the xdebug log shows:

    [5877] Log opened at 2020-08-14 17:20:45
    [5877] I: Connecting to configured address/port:
    [5877] E: Time-out connecting to client (Waited: 200 ms). :-(
    [5877] Log closed at 2020-08-14 17:20:46

This is for CLI only, I'm not trying to connect via php-fpm (so no apache, nginx, ...).

So far I have tried:

  • Changing the port to something other than 9000 (portscans also reveal that none of them are in use).
  • Adding a firewall rule to allow incoming requests as described in https://github.com/microsoft/WSL/issues/4585#issuecomment-610061194 (as well as restarting a couple times after adding the rule)

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

  • Adding options like `xdebug.remote_enable=1` to the config, but this is being done by PHPStorm anyways when it runs the remote php instance (`remote_connect_back` also did not do the trick):

    [wsl://UBUNTU2004]:php -dxdebug.remote_enable=1 -dxdebug.remote_mode=req -dxdebug.remote_port=9006 -dxdebug.remote_host= /home/spaceemotion/code/xxxxxx/backend/vendor/phpunit/phpunit/phpunit [rest ommitted]

Any help would be much appreciated!


I know that it may sound like overkill but have you tried to completely disable Windows Firewall on _all_ profiles just to totally isolate any possible firewall intervention?


I asked  the same question on stack overflow and was able to fix it via the firewall settings (https://stackoverflow.com/a/63420260/1397894):

  • In Windows Control Panel > Windows Firewall > Allow a program or feature through Windows Firewall you can see a list of software that is allowed to communicate through private and public networks.

For some weird reason though I had quite a few phpstorm entries there, each one probably an older Jetbrains Toolbox installation (I guess they don't get cleaned up properly?). I fear I will have to do this every time there's a new PhpStorm coming out :/


Thanks for sharing the link to the SO question, Windows firewall could be tricky sometimes.

As for the different PhpStorm entries, this is a somewhat normal scenario as each version has a different installation path.


I had a similar issue, but for me the solution was very different, but maybe this will help someone searching for a solution like me (for hours).
My problem was that absolutely nothing was happening after I configured xdebug. It ownly showed up in phpinfo, but not even logs were generated. For my solution, also Docker Desktop plays a role:

  • I Have xdebug 3.x installed
  • I also have Docker Desktop for Windows running
  • Inside Docker for Desktop, I enabled "WSL2 Integration" for the WSL2 distribution my web server runs in.
  • The magic config line for Xdebug for me was:
    Because the docker integration will leave this host entry in the WSL2 which also works without docker even running there!
  • Boom, it worked. All other attempts failed, like copying the IP over and pasting it into the ini file and restarting the server.

I know this was a completely different setup, but if anyone else is as desperate as I was, this may hopefully help :-) 



Thanks for sharing what worked Nina

Does the debugging work even when the internet is turned off? And also how does it work when VPN is turned on?


Hi Nikhil,

sad thing is, this was just a one-trick-pony and...

... and after it didn't work a second time, it now works again, but the funny thing is that I had to set BOTH remote_host and client_host to host.docker.internal and BOTH remote_port and client_port to 9000 to get it working!
That's somewhat confusing, because I always thought those had to be different.



...but the funny thing is that I had to set BOTH remote_host and client_host to host.docker.internal and BOTH remote_port and client_port to 9000 to get it working!
That's somewhat confusing, because I always thought those had to be different.

But they ARE the same thing.

remote_xxx is used by Xdebug v2 while Xdebug v3 uses client_xxx param name. BTW: v2-only param does nothing in v3.

Xdebug: Upgrading from Xdebug 2 to 3


Ah good to know! That's often also my problem: instead of actually reading more into the documentation, I just want to "get it running, NOW" and go through all the stackoverflow articles where you often find "mixed" configurations. From people who also are in my situation and just want to get it running ASAP. Also looking at the XDEBUG info in phpinfo, there was "_client" with port 9003 and "_remote" with port 9000 and if you don't really get deep into the topic, you might think something like (and yes, I admit this, fully ashamed) "one is for the one side, one is for the other side" or "one is if the debugging IDE is on the same machine, the other one is if the IDE is on an external (remote) machine". So you find all kinds of explanations why there should be two configurations for an IP and a port.

...finally many thanks for pointing this out! :-) 


Had came across the deprecation of the property earlier. The names are certainly confusing Nina. Thanks for the sharing the link here Andriy Bazanov

Had been using the settings as discussed here in this thread. However, when VPN is turned on, or, internet is disconnected the debugging no longer works. Hopefully using xdebug.client_host=host.docker.internal supports debugging in all the above scenarios.


Despite the popularity and wide adoption of WSL2, strangely, haven't come across a detailed article by @Jetbrains on how to set up debugging using WSL2.

Did any of you come across an article by PHPStorm that details the process of setting up debugging with WSL2? 


Guys Im having the same problem. I am very new to phpstorm and I am battling how to setup xdebug.

I have spent whole day - more than 12 hours trying to figure out what is what.

  • I have set my WSL to use static IP
  • I have enabled WSL distro integration in docker desktop
  • I have set `remote_host`
  • I have also set `remote_autostart` and `remote_connect_back`
  • Xdebug module is loaded that i checked
  • I also enabled logging
  • I also installed the Chrome extension
  • I checked phpstorm listening on port 9000 ok

This is my `xdebug.ini`:


It should run on port 9000.
I can ping the WSL machine from within the container:

sh-5.0# ping -c 3
PING ( 56(84) bytes of data.
64 bytes from icmp_seq=1 ttl=36 time=6.41 ms
64 bytes from icmp_seq=2 ttl=36 time=3.64 ms
64 bytes from icmp_seq=3 ttl=36 time=3.48 ms

But if I try to do the same from WSL machine to the docker container it does not work. I have also tried to turn off the firewall completely.

Docker container was instantiated using docker compose file:

version: "3"
    image: image.registry.sk/wy/uhs:int-php56
    container_name: wgtld.local
    hostname: wgtld.local
    restart: "no"
      WEB_UID: ${WEB_UID}
      - ${NETWORK_NAME}
      - ${PROJECT_PATH}:/var/www/html
      - ./nginx.conf:/etc/nginx/sites-enabled/default:ro
      - ./supervisord.conf:/etc/supervisor/supervisord.conf:ro
      - ./xdebug.ini:/etc/php/5.6/mods-available/xdebug.ini
      # - ./pool-www.conf:/etc/php/5.6/fpm/pool.d/www.conf:ro
      - traefik.enable=true
      - traefik.http.routers.wgtld.rule=Host(`wgtld.local`)
      - traefik.docker.network=${NETWORK_NAME}
      - traefik.http.services.wgtld-service.loadbalancer.server.port=80
    privileged: true
      - "8080:80"
      test: ["NONE"]
    external: true

I think the issue is mainly that i do not understand well:

  • If the project im working on (its working directory is on wsl) and phpstorm wants to connect to establish the xdebug session does it use WSL ip or host machine IP?
  • I was trying to use

Im not sure If I used the correct configuration choice?

Guys any ideas / tips / tricks would be more than welcome!
Thank you!


Andrej Rehak, given that you specify xdebug.remote_host, you don't need xdebug.remote_connect_back to be enabled.
In general, the configuration looks correct, so it makes sense to check what you have in xdebug.log after you initiate a debugging session.

I can ping the WSL machine from within the container

Why are you pinging the WSL machine, though? A better test would be pinging host.docker.internal, although it won't necessarily tell you the entire truth.
A perfectly valid test would be checking the 9000 port availability on host.docker.internal from the container while enabling/disabling Listening for PHP Debug connections in PhpStorm.


Please sign in to leave a comment.