@wordpress/env - Gutenberg Block Editor

wp-env lets you easily set up a local WordPress environment for building and testing plugins and themes. It requires no configuration and runs on Docker or WordPress Playground.

Quick Start

Navigate to your plugin directory

cd /path/to/a/wordpress/plugin

Install wp-env globally

npm -g i @wordpress/env

Start the environment

wp-env start

Access WordPress

Open http://localhost:8888 in your browser.Credentials:

Username: admin
Password: password

Database:

User: root
Password: password

Prerequisites

Docker (default runtime)

Docker powers wp-env by default. Install Docker for your platform:

Windows (WSL2 backend recommended)
macOS
Linux

Node.js

Install Node.js using a version manager like nvm or download directly.Required versions:

Node.js: >= 18.12.0
npm: >= 8.19.2

Git

Git is used for downloading WordPress, plugins, and themes from source control.Install Git

Installation

Global Installation

Install wp-env globally to use it across all projects:

npm -g i @wordpress/env

You can now run wp-env from any directory.

Local Installation

Install as a project dependency:

npm i @wordpress/env --save-dev

{
  "scripts": {
    "wp-env": "wp-env"
  }
}

npm run wp-env start -- --update

npx wp-env start --update

When using npm scripts, add -- before flags to pass them to wp-env instead of npm.

Runtime Options

Docker Runtime (Default)

The default Docker runtime provides full features:

wp-env start

WordPress Playground Runtime (Experimental)

Playground runs WordPress in WebAssembly without Docker:

wp-env start --runtime=playground

Feature Comparison:

Feature	Docker	Playground
Requires Docker	Yes	No
Xdebug	Yes	Yes
SPX profiling	Yes	No
phpMyAdmin	Yes	Yes
MySQL database	Yes	No (SQLite)
Multisite	Yes	Yes
Custom PHP version	Yes	Yes
Plugin/theme mounting	Yes	Yes
`wp-env run` command	Yes	No

Once started with a runtime, wp-env automatically uses the same runtime for subsequent commands until destroyed.

Commands

wp-env start

Installs and initializes the WordPress environment.

wp-env start

Start Command Options

wp-env start [options]

Options:

--update - downloads source updates and re-applies WordPress configuration
--runtime=<docker|playground> - select runtime to use
--xdebug[=<mode>] - enables Xdebug (default mode: debug)
--spx[=<mode>] - enables SPX profiling (default mode: enabled)
--scripts - execute configured lifecycle scripts (default: true)
--auto-port - automatically find available ports when configured ports are busy
--debug - enable debug output

Examples:

Terminal

# Start with latest sources
wp-env start --update

# Start with Xdebug enabled
wp-env start --xdebug

# Start with specific Xdebug modes
wp-env start --xdebug=profile,trace,debug

# Start with Playground runtime
wp-env start --runtime=playground

# Start with automatic port selection
wp-env start --auto-port

Example Output:

Terminal

$ wp-env start

ℹ Starting WordPress environment...
ℹ Downloading WordPress...
ℹ Extracting WordPress...
ℹ Starting containers...
✔ WordPress started at http://localhost:8888
  Username: admin
  Password: password

wp-env stop

Stops the WordPress environment and frees ports.

wp-env stop

Example Output:

Terminal

$ wp-env stop

ℹ Stopping WordPress environment...
✔ Stopped WordPress environment.

wp-env reset

Resets the WordPress database.

wp-env reset [environment]

This permanently deletes all posts, pages, media, etc. in the local installation.

Arguments:

environment - which databases to reset (choices: all, development, tests, default: development)

Options:

--scripts - execute lifecycle scripts (default: true)
--debug - enable debug output

Examples:

Terminal

# Reset development database
wp-env reset

# Reset all databases
wp-env reset all

# Reset test database only
wp-env reset tests

wp-env run

Runs arbitrary commands in Docker containers.

wp-env run <container> [command...]

This command is not available with the Playground runtime.

Containers:

cli - WordPress CLI container (includes composer, phpunit, wp-cli)
wordpress - WordPress web server
mysql - MySQL database
composer - Composer container
phpmyadmin - phpMyAdmin container

Options:

--env-cwd=<path> - working directory inside container (default: WordPress root)
--debug - enable debug output

Run Command Examples

List WordPress Users

Terminal

$ wp-env run cli wp user list

⠏ Running `wp user list` in 'cli'.

ID      user_login      display_name    user_email              user_registered roles
1       admin           admin           wordpress@example.com   2020-03-05      administrator

✔ Ran `wp user list` in 'cli'. (in 2s 374ms)

Create a Post

Terminal

$ wp-env run cli "wp post create --post_type=page --post_title='Ready'"

ℹ Starting 'wp post create --post_type=page --post_title='Ready'' on the cli container.

Success: Created post 5.
✔ Ran `wp post create --post_type=page --post_title='Ready'` in 'cli'. (in 3s 293ms)

Open WordPress Shell

Terminal

$ wp-env run cli wp shell

ℹ Starting 'wp shell' on the cli container. Exit with ctrl-c.

wp> echo( 'hello world!' );
hello world!
wp> ^C
✔ Ran `wp shell` in 'cli'. (in 16s 400ms)

Install Plugin

Terminal

$ wp-env run cli wp plugin install custom-post-type-ui

Installing Custom Post Type UI (1.9.2)
Downloading installation package...
Unpacking the package...
Installing the plugin...
Plugin installed successfully.
Success: Installed 1 of 1 plugins.
✔ Ran `plugin install custom-post-type-ui` in 'cli'. (in 6s 483ms)

Run Composer in Plugin Directory

Terminal

$ wp-env run cli --env-cwd=wp-content/plugins/my-plugin composer install

Change Permalink Structure

Terminal

# Set to post name only
wp-env run cli "wp rewrite structure /%postname%/"

# Set to year, month, post name
wp-env run cli "wp rewrite structure /%year%/%monthnum%/%postname%/"

Use -- before conflicting options: wp-env run cli php -- --help

wp-env cleanup

Cleans up the WordPress environment, removing containers, volumes, and networks but preserving Docker images.

wp-env cleanup

Options:

--scripts - execute lifecycle scripts (default: true)
--force - skip confirmation prompt
--debug - enable debug output

wp-env destroy

Completely destroys the WordPress environment including Docker images.

wp-env destroy

This permanently deletes all posts, pages, media, etc. in the local installation.

Options:

--scripts - execute lifecycle scripts (default: true)
--force - skip confirmation prompt
--debug - enable debug output

wp-env logs

Displays PHP and Docker logs.

wp-env logs [environment]

Arguments:

environment - which environment logs to display (default: development)

Options:

--watch - watch for logs as they happen (default: true)
--debug - enable debug output

Example:

Terminal

# Watch development logs
wp-env logs

# View logs without watching
wp-env logs --no-watch

wp-env status

Displays status, URLs, ports, and configuration.

wp-env status

Example Output:

Terminal

$ wp-env status

status: running
    - runtime: docker
    - install path: /home/user/.wp-env/63263e6506becb7b8613b02d42280a49
    - config: /home/user/my-plugin

environment:
        - url: http://localhost:8888
        - multisite: no
        - xdebug: off
        - http port: 8888
        - mysql port: 13306

Options:

--json - output status as JSON
--debug - enable debug output

Configuration

.wp-env.json

Create a .wp-env.json file to customize your environment:

{
  "core": null,
  "plugins": ["."]
}

{
  "core": null,
  "themes": ["."]
}

{
  "plugins": ["."],
  "port": 4013
}

{
  "phpVersion": "7.4",
  "plugins": ["."]
}

{
  "core": "WordPress/WordPress#5.2.0",
  "plugins": [
    "WordPress/wp-lazy-loading",
    "WordPress/classic-editor"
  ],
  "themes": ["WordPress/theme-experiments"]
}

{
  "multisite": true,
  "plugins": ["."]
}

Configuration Fields

Field	Type	Default	Description
`core`	`string\|null`	`null`	WordPress installation to use (null = latest production)
`phpVersion`	`string\|null`	`null`	PHP version to use
`plugins`	`string[]`	`[]`	Plugins to install and activate
`themes`	`string[]`	`[]`	Themes to install
`port`	`integer`	`8888`	Port number for the installation
`testsPort`	`integer`	`8889`	Port number for test site
`autoPort`	`boolean`	`false`	Auto-find available ports
`config`	`Object`	See below	wp-config.php constants
`mappings`	`Object`	`{}`	Directory mappings to mount
`mysqlPort`	`integer`	random	MySQL port to expose
`phpmyadmin`	`boolean`	`false`	Enable phpMyAdmin
`phpmyadminPort`	`integer`	random	phpMyAdmin port
`multisite`	`boolean`	`false`	Enable multisite
`lifecycleScripts`	`Object`	`{}`	Lifecycle commands

Source Types

You can specify various source types for core, plugins, and themes:

Type	Format	Example
Relative path	`.<path>\|~<path>`	`"./a/directory"`, `"~/a/directory"`
Absolute path	`/<path>\|<letter>:\<path>`	`"/a/directory"`, `"C:\\a\\directory"`
GitHub repo	`<owner>/<repo>[/<path>][#<ref>]`	`"WordPress/WordPress"`, `"WordPress/gutenberg#trunk"`
SSH repo	`ssh://user@host/<owner>/<repo>.git[#<ref>]`	`"ssh://git@github.com/WordPress/WordPress.git"`
ZIP file	`http[s]://<host>/<path>.zip`	`"https://wordpress.org/wordpress-5.4-beta2.zip"`

Default wp-config Values

These constants are set by default in the development instance:

WP_DEBUG: true
SCRIPT_DEBUG: true
WP_PHP_BINARY: 'php'
WP_TESTS_EMAIL: 'admin@example.org'
WP_TESTS_TITLE: 'Test Blog'
WP_TESTS_DOMAIN: 'localhost'
WP_SITEURL: 'http://localhost:8888'
WP_HOME: 'http://localhost:8888'

You can override these in your .wp-env.json:

.wp-env.json

{
  "config": {
    "WP_DEBUG": false,
    "WP_DEBUG_LOG": true
  }
}

.wp-env.override.json

Create this file (typically git-ignored) for local development overrides:

.wp-env.override.json

{
  "port": 3000,
  "config": {
    "WP_DEBUG_LOG": true
  }
}

The config and mappings fields are merged; all other fields override completely.

Lifecycle Scripts

Execute commands at specific points in the lifecycle:

.wp-env.json

{
  "lifecycleScripts": {
    "afterStart": "node tests/e2e/bin/setup-env.js",
    "afterReset": "wp-env run cli wp plugin activate my-plugin",
    "afterCleanup": "echo 'Cleanup complete'",
    "afterDestroy": "echo 'Environment destroyed'"
  }
}

Available lifecycle events:

afterStart - runs after wp-env start
afterReset - runs after wp-env reset
afterCleanup - runs after wp-env cleanup
afterDestroy - runs after wp-env destroy

Environment-Specific Configuration

Use the env key to override settings for specific environments:

.wp-env.json

{
  "plugins": ["."],
  "env": {
    "development": {
      "themes": ["./one-theme"]
    }
  }
}

Advanced Usage

Running Parallel Environments

Run multiple wp-env instances from the same folder using different config files:

Create custom config files

staging.json

{
  "core": "WordPress/WordPress#5.9",
  "plugins": ["."],
  "port": 8890
}

Start each environment

Terminal

# Start default environment
wp-env start

# Start staging environment
WP_ENV_PORT=8890 wp-env start --config=./staging.json

Manage environments separately

Terminal

# Check default status
wp-env status

# Check staging status
wp-env status --config=./staging.json

# Stop staging
wp-env stop --config=./staging.json

Each config file gets isolated Docker containers and data.

Using Xdebug

Enable Xdebug for step debugging:

Start with Xdebug enabled

wp-env start --xdebug

Or enable specific modes:

wp-env start --xdebug=profile,trace,debug

Configure your IDE

Example VS Code launch.json:

.vscode/launch.json

{
  "name": "Listen for XDebug",
  "type": "php",
  "request": "launch",
  "port": 9003,
  "pathMappings": {
    "/var/www/html/wp-content/plugins/my-plugin": "${workspaceFolder}/"
  }
}

Start debugging

Launch the debugger in your IDE
Set a breakpoint in your PHP code
Refresh your browser at http://localhost:8888
The breakpoint should trigger

Xdebug is only available for PHP 7.2+ (the default version).

Using SPX Profiling

SPX provides low-overhead profiling with a web UI:

Enable SPX

wp-env start --spx

Access SPX UI

Visit any page with SPX query parameters:

http://localhost:8888/?SPX_KEY=dev&SPX_UI_URI=/

Analyze performance

From the SPX interface you can:

Enable profiling for requests
View flame graphs
Analyze function timelines
Examine memory usage

Adding mu-plugins

Use the mappings config to add mu-plugins:

.wp-env.json

{
  "plugins": ["."],
  "mappings": {
    "wp-content/mu-plugins": "./path/to/local/mu-plugins",
    "wp-content/themes": "./path/to/local/themes"
  }
}

Custom PHP Settings

Map an .htaccess file to customize PHP settings:

Configure mapping

.wp-env.json

{
  "mappings": {
    ".htaccess": ".htaccess"
  }
}

Create .htaccess file

.htaccess

# Increase upload limits
php_value post_max_size 2G
php_value upload_max_filesize 2G
php_value memory_limit 2G

Environment Variables

Override configuration using environment variables:

WP_ENV_HOME - wp-env home directory (default: ~/.wp-env)
WP_ENV_PORT - development environment port
WP_ENV_TESTS_PORT - test environment port
WP_ENV_PHPMYADMIN_PORT - phpMyAdmin port
WP_ENV_MYSQL_PORT - MySQL port
WP_ENV_CORE - WordPress version to use
WP_ENV_PHP_VERSION - PHP version to use
WP_ENV_LIFECYCLE_SCRIPT_<EVENT> - lifecycle script commands
CI - when set, disables automatic port selection

Example:

WP_ENV_PORT=3000 wp-env start

Troubleshooting

Check wp-env is running

docker ps

You should see containers for wordpress and mariadb.

Check port number

docker ps

Inspect the PORTS column to see which port wp-env is using.Change port if needed:

WP_ENV_PORT=3333 wp-env start

Restart with updates

wp-env start --update

This downloads updates and reconfigures WordPress.

Restart Docker

Click Docker icon in system tray
Select “Restart”
Run wp-env start again

Reset the database

wp-env reset all
wp-env start

This permanently deletes all data.

Destroy and start fresh

wp-env destroy
wp-env start

This permanently deletes all data and images.

Package Information

Version: 11.0.0
Node.js: >= 18.12.0
npm: >= 8.19.2
License: GPL-2.0-or-later

@wordpress/scripts - Build and test scripts
@wordpress/create-block - Block scaffolding tool
@wordpress/e2e-test-utils-playwright - E2E testing utilities

​Quick Start

​Prerequisites

​Installation

​Global Installation

​Local Installation

​Runtime Options

​Docker Runtime (Default)

​WordPress Playground Runtime (Experimental)

​Commands

​wp-env start

​wp-env stop

​wp-env reset

​wp-env run

​List WordPress Users

​Create a Post

​Open WordPress Shell

​Install Plugin

​Run Composer in Plugin Directory

​Change Permalink Structure

​wp-env cleanup

​wp-env destroy

​wp-env logs

​wp-env status

​Configuration

​.wp-env.json

​Configuration Fields

​Source Types

​Default wp-config Values

​.wp-env.override.json

​Lifecycle Scripts

​Environment-Specific Configuration

​Advanced Usage

​Running Parallel Environments

​Using Xdebug

​Using SPX Profiling

​Adding mu-plugins

​Custom PHP Settings

​Environment Variables

​Troubleshooting

​Package Information

​Related Packages

Quick Start

Prerequisites

Installation

Global Installation

Local Installation

Runtime Options

Docker Runtime (Default)

WordPress Playground Runtime (Experimental)

Commands

wp-env start

wp-env stop

wp-env reset

wp-env run

List WordPress Users

Create a Post

Open WordPress Shell

Install Plugin

Run Composer in Plugin Directory

Change Permalink Structure

wp-env cleanup

wp-env destroy

wp-env logs

wp-env status

Configuration

.wp-env.json

Configuration Fields

Source Types

Default wp-config Values

.wp-env.override.json

Lifecycle Scripts

Environment-Specific Configuration

Advanced Usage

Running Parallel Environments

Using Xdebug

Using SPX Profiling

Adding mu-plugins

Custom PHP Settings

Environment Variables

Troubleshooting

Package Information

Related Packages