wp-env: the official local WordPress environment

wp-env (@wordpress/env) is the WordPress project's own Docker wrapper — the same tool core and Gutenberg development uses. For plugin/block development it beats a hand-written docker-compose file: one JSON file maps your plugin in, you get a dev site and a separate tests site with the WP PHPUnit suite preinstalled, and Xdebug is a flag. This skill covers configuring and driving it; when you need custom services (Redis, Mailpit, nginx), that is where its abstraction ends — switch to wp-docker-compose-stack.

When to use this skill

• Setting up a local WordPress for plugin, theme, or block development.
• A .wp-env.json / .wp-env.override.json exists in the repo or needs writing.
• The user asks for a "quick local WP", a WordPress sandbox, or Docker-based WP dev.
• Wiring PHPUnit against a real WP test suite (the tests instance ships it).
• Before hand-rolling docker-compose for WordPress — wp-env is the default; compose is the escape hatch.

Prerequisites and the npx wp-env trap

Docker must be installed and running (Docker Desktop on macOS/Windows — WSL2 backend recommended on Windows — or Docker Engine on Linux), plus Node.js LTS.

Invoke it as npx @wordpress/env. Bare npx wp-env in a project that doesn't have @wordpress/env installed downloads an unrelated npm package named wp-env — a stub that just prints "Please run the command 'npx @wordpress/env' instead" (verified: it resolves to wp-env@1.0.1, not the WordPress tool). The short wp-env command is only safe once the real package is a dev dependency, because then the local bin wins: