Xdebug not running inside a docker environment (Running on WSL)

Problem with Xdebug in Docker Automatically Occupying Port 9003

First of all, I apologize if this post violates any site rules. I don’t post here often, so I may miss some details. I’m also in a bit of a hurry since this issue involves an application for my company.

I’m facing a problem with Xdebug running in a Docker container inside a WSL environment (yes, a VM inside another VM). I’ve installed Xdebug in my Docker container, and it appears correctly in phpinfo(). However, I cannot use it because Docker automatically occupies the port configured for Xdebug (9003) as soon as I try to start debugging in VS Code.

In my xdebug.ini file, I’ve set the following configuration:

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.idekey=docker
xdebug.log=/tmp/xdebug.log
xdebug.log_level=7

The host.docker.internal configuration is causing a significant issue. Whenever I start Xdebug in VS Code, Docker automatically occupies the specified port (9003 or any other port I configure). I verified this using PowerShell with the command netstat -ano | findstr :9003, which shows that the port is being used by Docker’s processes:

TCP    0.0.0.0:9003           0.0.0.0:0             LISTENING       9508
TCP    [::]:9003              [::]:0                LISTENING       9508
TCP    [::1]:9003             [::]:0                LISTENING       16556

What I’ve Tried So Far

Changing xdebug.client_host to xdebug.discover_client_host=1:

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.discover_client_host=1
xdebug.client_port=9003
xdebug.idekey=docker
xdebug.log=/tmp/xdebug.log
xdebug.log_level=7

This didn’t work either. Xdebug starts but cannot connect because the localhost within Docker refers to the container itself and not the host application.

Creating a custom bridge in docker-compose.yml:

version: "3"
networks:
  debug_network:
    driver: bridge

services:
  web:
    networks:
      - debug_network
    build:
      context: ./docker
      dockerfile: Dockerfile
    ports:
      - "8000:80"
    volumes:
      - .:/app
      - ./docker/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini
    environment:
      - XDEBUG_MODE=debug
  db:
    image: mysql:8.0
    networks:
      - debug_network
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: database
    ports:
      - "3306:3306"

Even with this setup, Docker still occupies the debugging port.

Ensuring there’s no overriding of xdebug.ini by php.ini.

Docker Compose Configuration

version: "3"
services:
  web:
    build:
      context: ./docker
      dockerfile: Dockerfile
    ports:
      - "8000:80"
      - "9003:9003"
    volumes:
      - .:/app
      - ./docker/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini
    environment:
      - XDEBUG_MODE=debug
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: database
    ports:
      - "3306:3306"

launch.json for VS Code:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/app": "${workspaceFolder}"
      }
    }
  ]
}

Xdebug Verification

root@container:/app# php -m | grep xdebug
xdebug

The Question

Is there a way to prevent Docker from automatically occupying the Xdebug ports (9003 or any configured port)? I’d be grateful for any solution or workaround, as none of the approaches I’ve tried have worked. Thank you!