/wp-env

name: wp-env
description: "Use when setting up, configuring, or troubleshooting local WordPress development environments with @wordpress/env (wp-env). Triggers on mentions of wp-env, local WordPress development, Docker-based WordPress, or requests to start/stop/configure a local WordPress instance."
compatibility: "Targets WordPress 7.0+ (PHP 7.4.0+). Requires Docker and Node.js 18.12+."

@wordpress/env (wp-env)

Zero-config, Docker-based local WordPress development environment for plugins, themes, and core.

When to use

• User asks to set up a local WordPress development environment
• Project contains a `.wp-env.json` file
• User mentions `wp-env`, `@wordpress/env`, or Docker-based WordPress development
• User wants to run WP-CLI commands, PHPUnit tests, or debug with Xdebug locally
• Triage detects a plugin or theme project that needs a local WordPress instance

**wp-env or wp-playground?** For a quick local WordPress, prefer the **wp-playground** skill by default — it's faster, disposable, and needs no Docker. Use **wp-env** when the task actually requires it:

• the repo already contains a `.wp-env.json`
• a real MySQL database is needed (PHPUnit against the DB, `wp db` commands, data that survives restarts)
• arbitrary commands must run inside the environment (shell access, Composer, full WP-CLI via `wp-env run`)
• this is a WordPress core or Gutenberg checkout
• the user explicitly asks for wp-env or Docker

wp-env can also run without Docker by using Playground as its runtime (`npx @wordpress/env start --runtime=playground`, experimental). That is still wp-env, driven by the same `.wp-env.json`, so treat it as a Docker-free fallback for a project that already carries wp-env config, not as a third option. It swaps MySQL for SQLite and drops `wp-env run` and the separate tests environment, which are most of the reasons to pick wp-env in the first place. For a quick Docker-free WordPress with no wp-env config, use the **wp-playground** skill directly.

Inputs required

1. **Docker status** -- verify Docker is installed and running: `docker info` 2. **Node.js version** -- must be >= 18.12.0: `node -v` 3. **Project type** -- plugin, theme, or full site (check for `.wp-env.json`, plugin headers, or `style.css` theme headers) 4. **Existing config** -- read `.wp-env.json` and `.wp-env.override.json` if present

Procedure

1. Install wp-env

# Global (recommended)
npm -g install @wordpress/env

# Or project-local
npm i @wordpress/env --save-dev
# Then use: npx wp-env start

2. Start the environment

wp-env start

Default credentials:

• **URL:** http://localhost:8888/wp-admin/
• **Username:** `admin`
• **Password:** `password`

Common start options:

• `wp-env start --update` -- pull latest sources and reconfigure
• `wp-env start --xdebug` -- enable Xdebug (debug mode)
• `wp-env start --xdebug=profile,trace` -- multiple Xdebug modes
• `wp-env start --auto-port` -- find available ports when defaults are busy

3. Auto-detection (no config file)

When no `.wp-env.json` exists, wp-env scans the current directory:

| Detected type | How detected | Auto-config | |--------------|-------------|-------------| | Plugin | `Plugin Name:` header in a root `.php` file | `{ "plugins": ["."] }` | | Theme | `Theme Name:` header in `style.css` | `{ "themes": ["."] }` | | Core | `wp-includes/version.php` exists | `{ "core": "." }` |

4. Configure with `.wp-env.json`

Place at the project root. All fields are optional.

{
  "core": null,
  "phpVersion": "8.1",
  "plugins": [
    ".",
    "https://downloads.wordpress.org/plugin/akismet.zip",
    "WordPress/classic-editor"
  ],
  "themes": [],
  "port": 8888,
  "multisite": false,
  "phpmyadmin": false,
  "config": {
    "WP_DEBUG": true,
    "SCRIPT_DEBUG": true
  },
  "mappings": {
    "wp-content/mu-plugins": "./mu-plugins"
  },
  "lifecycleScripts": {
    "afterStart": "wp-env run cli wp rewrite structure /%postname%/"
  }
}

Source string formats (for `core`, `plugins`, `themes`, `mappings`)

| Format | Example | |--------|---------| | Local path | `"."`, `"./path"`, `"../path"` | | GitHub shorthand | `"WordPress/classic-editor"`, `"owner/repo#branch"` | | ZIP URL | `"https://downloads.wordpress.org/plugin/akismet.zip"` | | Git SSH | `"ssh://user@host/repo.git#ref"` |

**GOTCHA:** WordPress.org plugin/theme slugs (bare names like `"akismet"`) do NOT work. Use the full ZIP URL.

Local overrides with `.wp-env.override.json`

Create `.wp-env.override.json` next to `.wp-env.json` for personal settings (gitignored). Only `config` and `mappings` are **merged** -- all other fields (including `plugins` and `themes` arrays) **fully replace** the base.

5. Run commands in containers

# WP-CLI commands
wp-env run cli wp user list
wp-env run cli wp plugin list
wp-env run cli wp option update blogname "My Site"
wp-env run cli "wp rewrite structure /%postname%/"

# Run commands in a specific directory
wp-env run cli --env-cwd=wp-content/plugins/my-plugin composer install

# PHPUnit tests
wp-env run cli --env-cwd=wp-content/plugins/my-plugin vendor/bin/phpunit

# Pass flags with -- separator
wp-env run cli php -- --version

# MySQL access
wp-env run mysql mysql -- --user=root --password=password wordpress

Available containers: `mysql`, `wordpress`, `cli`, `composer`, `phpmyadmin`.

6. Manage the environment

wp-env stop                    # Stop and free ports
wp-env reset development       # Reset dev database (keeps test)
wp-env reset all               # Reset all databases
wp-env logs                    # Stream PHP/Docker logs
wp-env logs --no-watch         # Print logs and exit
wp-env status                  # Show URLs, ports, config
wp-env status --json           # Machine-readable status
wp-env cleanup                 # Remove containers/volumes (keep images)
wp-env destroy                 # Remove everything including images

7. Xdebug setup

wp-env