WordPress Local Development with wp-env: Docker-Powered Zero-Config Setup

@wordpress/env (wp-env) is the official Docker-based local WordPress environment from the Gutenberg team. It spins up a fully configured WordPress instance in under a minute — no XAMPP, MAMP, or manual Docker Compose files required. It supports custom plugins, themes, mapped directories, multiple PHP versions, and test environments alongside development environments, all from a single .wp-env.json config file.

Problem: WordPress local development environments — XAMPP, Local by Flywheel, MAMP — require manual setup, differ from production, and cannot be scripted into a reproducible environment definition that all team members share.

Solution: Use @wordpress/env (wp-env): install with npm install -D @wordpress/env, define the environment in .wp-env.json including WordPress version, active plugins, and mapped directories, then run npx wp-env start. The environment runs in Docker containers and is reproducible across macOS, Linux, and Windows — any developer gets an identical setup with one command.

The commands below install wp-env, configure it with a .wp-env.json file for a plugin project, show common lifecycle commands, and demonstrate the test environment and custom PHP version features.

# 1. Install globally (requires Docker Desktop running)
npm install -g @wordpress/env

# 2. Start environment (from plugin or theme root)
wp-env start       # first run downloads WordPress images (~2 min)
wp-env start --update   # pull latest WordPress/PHP images

# 3. Common lifecycle commands
wp-env stop        # stop containers (data persists)
wp-env clean all   # wipe data and reinstall WordPress
wp-env destroy     # remove containers and volumes completely

# 4. Run WP-CLI inside wp-env
wp-env run cli wp plugin list
wp-env run cli wp user create testuser test@example.com --role=editor
wp-env run cli wp option update blogname "My Dev Site"

# 5. Run PHPUnit in the test environment
wp-env run tests-cli vendor/bin/phpunit
wp-env run tests-cli wp --version   # confirm test WordPress instance

{
    "$schema": "https://schemas.wp.org/trunk/wp-env.json",
    "core":     "WordPress/WordPress#6.8",
    "phpVersion": "8.2",
    "plugins":  [
        ".",
        "https://downloads.wordpress.org/plugin/woocommerce.latest-stable.zip",
        "https://downloads.wordpress.org/plugin/query-monitor.latest-stable.zip"
    ],
    "themes":   [
        "https://downloads.wordpress.org/theme/twentytwentyfive.latest-stable.zip"
    ],
    "mappings": {
        "wp-content/uploads": "./tests/fixtures/uploads"
    },
    "config": {
        "WP_DEBUG":         true,
        "SCRIPT_DEBUG":     true,
        "WP_DEBUG_LOG":     true,
        "SAVEQUERIES":      true
    },
    "env": {
        "tests": {
            "config": {
                "WP_DEBUG": false
            },
            "phpVersion": "8.3"
        }
    }
}

NOTE: wp-env clean all is irreversible — it wipes the WordPress database and all uploaded files in the environment; if you have seeded test data you want to preserve, export it first with wp-env run cli wp db export backup.sql and import after cleaning.