Xdebug 3 + Lando + PhpStorm Setup Guide

Setting up Xdebug with Lando has gotten simpler over the years, but there are still a few gotchas — especially on Windows with WSL2. Here’s a quick, up-to-date setup guide for Xdebug 3 with Lando and PhpStorm.

Enable Xdebug in Lando

Lando has built-in Xdebug support. Add xdebug: true to your .lando.yml service config:

name: my-project
recipe: wordpress
config:
  webroot: web
  xdebug: true
  conf:
    php: config/php.ini

Configure Xdebug 3

Create a custom config/php.ini with the Xdebug 3 directives. The old remote_enable and remote_host settings from Xdebug 2 no longer work.

[xdebug]
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003
xdebug.idekey = PHPSTORM
xdebug.log = /tmp/xdebug.log

Key changes from Xdebug 2 to 3:

xdebug.remote_enable = 1 → xdebug.mode = debug
xdebug.remote_host → xdebug.client_host
xdebug.remote_port = 9000 → xdebug.client_port = 9003 (default port changed)
xdebug.remote_autostart = 1 → xdebug.start_with_request = yes

PhpStorm Setup

Go to Settings → PHP → Debug and set the Xdebug port to 9003.
Go to Settings → PHP → Servers, add a server matching your Lando URL, and configure the path mapping from your local project root to /app (Lando’s default mount point).
Click Start Listening for PHP Debug Connections (the phone icon) in the toolbar.
Run lando rebuild to apply the config, then load a page — PhpStorm should catch the breakpoint.

WSL2 Note

host.docker.internal resolves correctly on Docker Desktop for Windows and macOS. If you’re running Docker inside WSL2 natively (without Docker Desktop), you may need to use your WSL gateway IP instead — find it with ip route | grep default inside WSL.

Troubleshooting

If breakpoints aren’t hitting:

Check /tmp/xdebug.log inside the container (lando ssh to access it)
Make sure the port isn’t blocked by a firewall
Verify lando php -v shows Xdebug loaded
Try lando rebuild — lando restart doesn’t always pick up php.ini changes