@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