Setting Up a Modern WordPress Development Environment Using wp-env

What is wp-env?

wp-env is a Node.js-based tool that automates the creation and management of local WordPress installations. It leverages Docker containers to ensure consistency across environments, making it easier to test themes, plugins, and core contributions without manual setup.

wp-env is a zero-config tool for painless local WordPress environments. It provides decisions over options so that users can quickly spin up WordPress without wasting time. The tool is officially maintained by the WordPress team and is designed to be simple enough for designers, managers, and anyone else to use, not just developers.

For ease of use, Composer, PHPUnit, and wp-cli are available for in the environment. This makes it an ideal choice for both simple plugin development and complex testing scenarios.

Complete Installation Guide

Prerequisites and System Requirements

Before installing wp-env, ensure your system meets these requirements:

Operating System Requirements:

Windows 10/11 (Pro, Enterprise, or Education for Hyper-V; Home edition for WSL2)
macOS (current and two previous major versions)
Linux (Ubuntu, Debian, or other Docker-compatible distributions)

Step 1: Install Node.js

Node.js is required to run wp-env. Run npm -g install @wordpress/env in the terminal to install wp-env globally.

Download and Install Node.js:

Official Download: Node.js® is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts.
Download Link: https://nodejs.org/en/download
Recommended Version: Node.js 14 or higher (LTS version recommended)

Installation Steps:

Visit the official Node.js download page
Download the LTS version for your operating system
Run the installer and follow the setup wizard
Accept default settings unless you have specific requirements
Verify installation by opening terminal/command prompt and running: node --versionnpm --version

Step 2: Install Docker Desktop

Download, install, and start Docker Desktop following the instructions for your operating system. Docker is essential as wp-env uses Docker containers to run WordPress environments.

Download Docker Desktop:

Official Site: https://www.docker.com/products/docker-desktop/
Direct Downloads:
- Windows: https://docs.docker.com/desktop/setup/install/windows-install/
- macOS: https://docs.docker.com/desktop/setup/install/mac-install/
- macOS: https://orbstack.dev/ (Docker Desktop alternative, much faster).
- Linux: https://docs.docker.com/desktop/setup/install/linux/

System Requirements:

Windows: Windows 11 64-bit: Home or Pro version 22H2 or higher, or Enterprise or Education version 22H2 or higher. Windows 10 64-bit: Minimum required is Home or Pro 22H2 (build 19045) or higher, or Enterprise or Education 22H2 (build 19045) or higher.

macOS: A supported version of macOS. Docker Desktop is supported on the current and two previous major macOS releases. At least 4 GB of RAM.

Installation Steps:

Download Docker Desktop for your operating system
Run the installer with administrator privileges
Follow the installation wizard:
- Windows: Choose WSL 2 backend (recommended) or Hyper-V
- macOS: Use recommended settings during setup
Restart your computer if prompted
Start Docker Desktop and complete the initial setup
Verify installation by running: docker --versiondocker-compose --version

Step 3: Install wp-env Globally

Once Node.js and Docker are installed:

npm install -g @wordpress/envCode language: CSS (css)

Verify Installation:

wp-env --version

This should display the current version of wp-env, confirming successful installation.

Basic Usage

Quick Start

Navigate to any directory and run:

wp-env start

Once the script completes, you can access the local environment at: http://localhost:8888. Log into the WordPress dashboard using username admin and password password.

Working with Plugins and Themes

The directory you are in when you start wp-env (/foo or /bar or whatever) is treated like /wp-content/plugins/new-plugin-name. When you run wp-env from a plugin or theme directory, it automatically maps that directory into the WordPress installation.

Advanced .wp-env.json Configuration

Basic Configuration Structure

Create a .wp-env.json file in your project root for advanced configurations:

{
  "core": "WordPress/WordPress",
  "plugins": ["."],
  "themes": [],
  "port": 8888,
  "testsPort": 8889,
  "config": {},
  "mappings": {},
  "env": {
    "development": {},
    "tests": {}
  }
}Code language: JSON / JSON with Comments (json)

Configuration Options

Core WordPress Version

{
  "core": "WordPress/WordPress",          // Latest WordPress
  "core": "WordPress/WordPress#5.8",      // Specific version
  "core": "WordPress/WordPress#trunk",    // Development version
  "core": "./path/to/wordpress",          // Local WordPress build
  "core": null                            // Use existing WordPress in container
}Code language: JSON / JSON with Comments (json)

Plugins Configuration

{
  "plugins": [
    ".",                                   // Current directory as plugin
    "WordPress/gutenberg",                 // Official WordPress plugin
    "WordPress/gutenberg#trunk",           // Specific branch/tag
    "./path/to/local/plugin",              // Local plugin path
    "https://github.com/user/plugin.git", // Git repository
    {
      "source": "WordPress/jetpack",      // Plugin source
      "activate": true                     // Auto-activate plugin
    }
  ]
}Code language: JSON / JSON with Comments (json)

Themes Configuration

{
  "themes": [
    ".",                                   // Current directory as theme
    "WordPress/twentytwentythree",         // Official WordPress theme
    "./path/to/local/theme",               // Local theme path
    "https://github.com/user/theme.git"   // Git repository
  ]
}Code language: JSON / JSON with Comments (json)

Port Configuration

{
  "port": 8888,        // Development environment port
  "testsPort": 8889    // Testing environment port
}Code language: JSON / JSON with Comments (json)

WordPress Configuration (wp-config.php)

{
  "config": {
    "WP_DEBUG": true,
    "WP_DEBUG_LOG": true,
    "WP_DEBUG_DISPLAY": false,
    "SCRIPT_DEBUG": true,
    "WP_ENVIRONMENT_TYPE": "development",
    "WP_DISABLE_FATAL_ERROR_HANDLER": true,
    "CUSTOM_CONSTANT": "custom_value"
  }
}Code language: JSON / JSON with Comments (json)

File Mappings

{
  "mappings": {
    "my-custom-folder": "/var/www/html/wp-content/my-custom-folder",
    "uploads": "/var/www/html/wp-content/uploads"
  }
}Code language: JSON / JSON with Comments (json)

Environment-Specific Configurations

The env key allows you to override any configuration option for specific environments (development vs tests). This is powerful for scenarios where you need different setups for development and testing.

Real-world Example – E-commerce Plugin Development:

{
  "core": "WordPress/WordPress",
  "plugins": [
    ".",
    "woocommerce/woocommerce"
  ],
  "themes": ["WordPress/storefront"],
  "config": {
    "WP_DEBUG": false,
    "WP_DEBUG_LOG": false,
    "WOOCOMMERCE_DOWNLOADS_REQUIRE_LOGIN": false
  },
  "env": {
    "development": {
      "plugins": [
        ".",
        "woocommerce/woocommerce",
        "WordPress/query-monitor",
        "WordPress/debug-bar"
      ],
      "config": {
        "WP_DEBUG": true,
        "WP_DEBUG_LOG": true,
        "WP_DEBUG_DISPLAY": true,
        "SCRIPT_DEBUG": true,
        "SAVEQUERIES": true
      },
      "port": 8888
    },
    "tests": {
      "themes": ["WordPress/twentytwentythree"],
      "config": {
        "WP_DEBUG": false,
        "WP_DEBUG_LOG": false,
        "WP_TESTS_DOMAIN": "example.org",
        "WP_TESTS_EMAIL": "test@example.org"
      },
      "port": 8889
    }
  }
}Code language: JSON / JSON with Comments (json)

What this configuration does:

Global settings: Installs WooCommerce and Storefront theme by default for both environments
Development environment:
- Adds debugging plugins (Query Monitor, Debug Bar)
- Enables all debugging options for detailed error reporting
- Runs on port 8888
Testing environment:
- Uses a minimal theme (Twenty Twenty-Three) for consistent testing
- Disables debugging to simulate production conditions
- Sets up proper test domain and email
- Runs on port 8889

This approach lets you develop with full debugging capabilities while testing in a clean, production-like environment.

Advanced Use Cases

Multi-Site Configuration

{
  "core": "WordPress/WordPress",
  "config": {
    "WP_ALLOW_MULTISITE": true,
    "MULTISITE": true,
    "SUBDOMAIN_INSTALL": false,
    "DOMAIN_CURRENT_SITE": "localhost:8888",
    "PATH_CURRENT_SITE": "/",
    "SITE_ID_CURRENT_SITE": 1,
    "BLOG_ID_CURRENT_SITE": 1
  }
}Code language: JSON / JSON with Comments (json)

PHP Version Specification

While wp-env doesn’t directly support PHP version specification in .wp-env.json, you can use command line flags:

wp-env start --php=8.1

Development with Gutenberg

{
  "core": "WordPress/WordPress",
  "plugins": [
    ".",
    "WordPress/gutenberg"
  ],
  "themes": ["WordPress/twentytwentyfive"],
  "config": {
    "GUTENBERG_DEVELOPMENT_MODE": true,
    "WP_DEBUG": true
  }
}Code language: JSON / JSON with Comments (json)

Testing Environment Setup

{
  "env": {
    "tests": {
      "config": {
        "WP_DEBUG": false,
        "WP_TESTS_DOMAIN": "localhost",
        "WP_TESTS_EMAIL": "admin@example.org",
        "WP_TESTS_TITLE": "Test Blog"
      }
    }
  }
}Code language: JSON / JSON with Comments (json)

Complete Command Reference

Primary Commands

`wp-env start`

Starts WordPress for development on port 8888 (http://localhost:8888) (override with WP_ENV_PORT) and tests on port 8889 (http://localhost:8889) (override with WP_ENV_TESTS_PORT).

Options:

--update – Tell wp-env to update sources and apply the configuration options again with wp-env start –update.
--xdebug – Sets the Xdebug mode to “debug” (for step debugging): wp-env start –xdebug
--xdebug=profile,trace,debug – Enable specific Xdebug modes

`wp-env stop`

Stops running WordPress for development and tests and frees the ports.

`wp-env destroy`

Deletes Docker containers, volumes, and networks associated with the WordPress environment and removes local files.

Options:

--debug – Enable debug output
--scripts – Execute any configured lifecycle scripts

Environment Management

`wp-env clean`

Resets the WordPress database to its initial state.

Usage:

wp-env clean             # Clean development database
wp-env clean tests       # Clean tests database
wp-env clean all         # Clean both databasesCode language: PHP (php)

`wp-env logs`

displays PHP and Docker logs for given WordPress environment.

Usage:

wp-env logs              # Development environment logs
wp-env logs tests        # Tests environment logs
wp-env logs all          # All environment logsCode language: PHP (php)

Options:

--watch – Watch for logs as they happen (default: true)
--debug – Enable debug output

Running Commands

`wp-env run`

Runs an arbitrary command in one of the underlying Docker containers. For example, it can be useful for running wp cli commands.

Container Options:

cli – Development WordPress with CLI tools
tests-cli – Testing WordPress with CLI tools
wordpress – Development WordPress web server
tests-wordpress – Testing WordPress web server

Examples:

# Run WP-CLI commands
wp-env run cli wp post list
wp-env run cli wp user create testuser test@example.com

# Run Composer commands
wp-env run cli composer install
wp-env run cli composer update

# Run PHPUnit tests
wp-env run tests-cli phpunit

# Access bash shell
wp-env run cli bash
wp-env run tests-cli bash

# Run WordPress shell
wp-env run cli wp shellCode language: PHP (php)

Advanced Options:

--env-cwd – The command’s working directory inside the container. Paths without a leading slash are relative to the WordPress root.

Example:

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

Environment Information

`wp-env info`

Get the path where all the environment files are stored. This includes the Docker files, WordPress, PHPUnit files, and any sources that were downloaded.

Environment Variables

Control wp-env behavior with environment variables:

WP_ENV_PORT – Override development port (default: 8888)
WP_ENV_TESTS_PORT – Override tests port (default: 8889)
WP_ENV_HOME – To change the wp-env home directory, set the WP_ENV_HOME environment variable.

Example:

WP_ENV_PORT=3000 wp-env start
WP_ENV_HOME="/custom/path" wp-env startCode language: JavaScript (javascript)

Working with npm Scripts

When wp-env is installed locally in a project:

{
  "scripts": {
    "wp-env": "wp-env",
    "env:start": "wp-env start",
    "env:stop": "wp-env stop",
    "env:reset": "wp-env clean all"
  }
}Code language: JSON / JSON with Comments (json)

Usage:

npm run wp-env start
npm run wp-env run cli wp post list
npm run env:start -- --updateCode language: CSS (css)

Note: You must add another double dash to pass flags to the script (wp-env) rather than to npm itself

Troubleshooting Commands

Check Docker Status

docker ps                   # List running containers
docker images               # List Docker images
docker system df            # Show Docker disk usageCode language: PHP (php)

Reset Everything

wp-env destroy              # Remove wp-env containers and data
docker system prune -a      # Remove all unused Docker dataCode language: PHP (php)

Debug Mode

wp-env start --debug        # Enable verbose output
wp-env logs --debug         # Show debug logsCode language: PHP (php)

One of the standout features of wp-env is its ability to create consistent and shareable development environments. By leveraging Docker containers, wp-env ensures that every team member works in an identical setup, eliminating the “it works on my machine” problem. This makes collaboration seamless, especially in teams with diverse operating systems and configurations.

Another advantage is that wp-env configuration files (e.g., .wp-env.json) can be committed to your Git repository. This allows teams to share the same environment setup effortlessly, ensuring consistency across development and testing workflows.

Alternative tools

Additionally, for those who prefer alternative tools, WordPress.com offers Studio and WP Engine provides Local, which are excellent options for setting up local WordPress environments. These tools provide user-friendly interfaces and additional features tailored for WordPress development, making them great companions to wp-env.

Summarizing

I hope this guide covers everything you need to know about wp-env, from basic installation to advanced configurations and a complete command reference. The tool’s power lies in its simplicity for basic use cases while providing extensive customization options for complex development scenarios.

What is wp-env?

Complete Installation Guide

Prerequisites and System Requirements

Step 1: Install Node.js

Step 2: Install Docker Desktop

Step 3: Install wp-env Globally

Basic Usage

Quick Start

Working with Plugins and Themes

Advanced .wp-env.json Configuration

Basic Configuration Structure

Configuration Options

Core WordPress Version

Plugins Configuration

Themes Configuration

Port Configuration

WordPress Configuration (wp-config.php)

File Mappings

Environment-Specific Configurations

Advanced Use Cases

Multi-Site Configuration

PHP Version Specification

Development with Gutenberg

Testing Environment Setup

Complete Command Reference

Primary Commands

wp-env start

wp-env stop

wp-env destroy

Environment Management

wp-env clean

wp-env logs

Running Commands

wp-env run

Environment Information

wp-env info

Environment Variables

Working with npm Scripts

Troubleshooting Commands

Check Docker Status

Reset Everything

Debug Mode

Why wp-env is Great for Sharing Environments

Alternative tools

Summarizing

@wordpress/create-block Major Updates & New Features Guide

Mastering Complex Attributes in WordPress Blocks: Handling Objects, Arrays, and Nested Data

Building Blocks That Work Seamlessly with Block Themes and the Site Editor

`wp-env start`

`wp-env stop`

`wp-env destroy`

`wp-env clean`

`wp-env logs`

`wp-env run`

`wp-env info`