If you’re a WordPress developer or just starting to explore WordPress development, setting up a local development environment can be one of the most powerful upgrades you can make to your workflow. Developing locally provides better performance, security, and control over your environment — plus, it avoids the risks and delays of uploading code changes directly to a live server.

In this guide, we’ll walk through how to fully configure a local WordPress development stack using VS Code, Docker, WP-CLI, and Xdebug. This stack is perfect for professionals who want a fast, flexible, and modern development environment with deep debugging capabilities.

Why Use Docker, WP-CLI, and Xdebug Together?

Before we dive into the setup, let’s take a quick look at what each component brings to the table:

• Docker: Containers isolate your development environment, allowing you to create a clean, reproducible setup across different systems.
• WP-CLI: A command-line interface for WordPress that drastically speeds up common management tasks.
• Xdebug: A PHP debugger that integrates with VS Code to help you step through your code and find bugs quickly and efficiently.

Together, these tools supercharge your development process and reduce the mess of managing PHP versions, conflicting server settings, and sluggish WordPress behavior.

Step 1: Prerequisites

Before setting up the stack, make sure you have the following installed on your computer:

• Visual Studio Code
• Docker Desktop
• Git

You’ll also want the following VS Code extensions:

• PHP Debug (by Felix Becker)
• Docker (Microsoft official plugin)

Once you’re ready, let’s start creating our powerful dev stack!

Step 2: Create the Project Directory

Let’s start fresh by creating a directory for your WordPress project:

mkdir wordpress-local-dev
cd wordpress-local-dev

Inside this directory, we’ll configure Docker by creating a docker-compose.yml file, and some supporting configuration files.

Step 3: Configure Docker Compose

Create a new docker-compose.yml file and add the following:

version: '3.9'
services:
  wordpress:
    image: wordpress:latest
    ports:
      - "8000:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wp_user
      WORDPRESS_DB_PASSWORD: wp_pass
      WORDPRESS_DB_NAME: wp_db
    volumes:
      - ./wordpress:/var/www/html
      - ./xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
    depends_on:
      - db

  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: somepass
      MYSQL_DATABASE: wp_db
      MYSQL_USER: wp_user
      MYSQL_PASSWORD: wp_pass
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

Note how we mount the WordPress site content into the container and configure a custom xdebug.ini file. This file will enable Xdebug support for our PHP environment.

docker compose, wordpress local, vs code</ai-img]

Step 4: Configure WP-CLI

WP-CLI isn’t included by default in the WordPress Docker image. Let’s add a custom shell script to install and configure it!

Create a file called install-wp.sh in your project folder with the following content:

#!/bin/bash

docker-compose run --rm wordpress bash -c "cd /var/www/html && wp core download && \
  wp config create --dbname=wp_db --dbuser=wp_user --dbpass=wp_pass --dbhost=db && \
  wp core install --url=localhost:8000 --title='My Dev Site' --admin_user=admin --admin_password=pass --admin_email=you@example.com"

Make the file executable:

chmod +x install-wp.sh

Now bring up the containers and install WordPress:

docker-compose up -d
./install-wp.sh

At this point, your WordPress site should be up and running at http://localhost:8000.

Step 5: Enable Xdebug

Now let’s configure Xdebug so it will integrate seamlessly with VS Code.

Create the file xdebug.ini at your root project folder with the following content:

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003

We’re using port 9003 because that’s the default for Xdebug 3.x+ versions. After you’ve created the file, restart the containers:

docker-compose restart

Step 6: Configure VS Code for Debugging

Inside your workspace, open the command palette in VS Code (Cmd+Shift+P or Ctrl+Shift+P) and choose Add Configuration inside the launch.json file. Add the following block:

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

Now you’re all set to debug! Make sure your containers are running, place a breakpoint in a PHP file, then start the debugger by clicking the green play button in the Debug sidebar.

Pro Tip: You can use WP-CLI to activate or deactivate plugins and themes while debugging to test specific use cases quickly.

vs code debug, php xdebug, wordpress docker</ai-img]

Optional: Add phpMyAdmin

If you’d like a web-based interface to explore your database, add phpMyAdmin to your docker-compose.yml file:

phpmyadmin:
  image: phpmyadmin/phpmyadmin
  ports:
    - "8080:80"
  environment:
    PMA_HOST: db
    MYSQL_ROOT_PASSWORD: somepass
  depends_on:
    - db

After restarting Docker, open http://localhost:8080 and log in using the credentials defined in your docker-compose.yml.

Final Thoughts

With Docker, WP-CLI, and Xdebug properly configured, you now have a modern WordPress development environment that is flexible, reproducible, and extremely powerful. You can easily destroy and recreate environments, debug with laser precision, and automate tasks through WP-CLI.

Here’s a quick recap of what we’ve achieved:

• Launched WordPress in Docker with a dedicated MySQL service
• Configured automatic WordPress installation via WP-CLI
• Integrated Xdebug with VS Code for enhanced debugging
• Added optional phpMyAdmin access for database inspection

Ready to take your dev game to the next level? Experiment with adding support for mailhog, PHPUnit, or local HTTPS next!

Happy coding!