Skip to main content
The @wordpress/env package (wp-env) lets you set up a local WordPress environment (site) for building and testing plugins and themes, without any additional configuration. Before following this guide, install Node.js development tools if you have not already done so.

​
Quick Start

​
Docker Desktop Setup

The wp-env tool uses Docker to create a virtual machine that runs the local WordPress site. The Docker Desktop application is free for small businesses, personal use, education, and non-commercial open-source projects. See their FAQ for more information. Use the links below to download and install Docker Desktop for your operating system: After successful installation, start the Docker Desktop application and follow the prompts to get set up. You should generally use the recommended (default) settings, and creating a Docker account is optional.

​
Configuration

​
Where to Run wp-env

The wp-env tool can run from practically anywhere. When using the script while developing a single plugin, wp-env start can mount and activate the plugin automatically when run from the directory containing the plugin. This also works for themes when run from the directory in which you are developing the theme. A generic WordPress environment will be created if you run wp-env start from a directory that is not a plugin or theme. The script will display the following warning, but ignore if this is your intention:

​
Using .wp-env.json

You can use the .wp-env.json configuration file to create an environment that works with multiple plugins and/or themes. Example configuration from the Gutenberg project:
Some projects, like Gutenberg, include their own specific wp-env configurations, and the documentation might prompt you to run npm run wp-env start instead.

​
Common Commands

​
Development Workflow

​
Managing the Environment

​
Example Gutenberg Workflow

​
Uninstall or Reset

Here are a few instructions if you need to start over or want to remove what was installed:
  • Reset database: Run wp-env clean all to clean the WordPress database
  • Remove environment: Run wp-env destroy to remove the local environment completely for a specific project
  • Uninstall wp-env: Run npm -g uninstall @wordpress/env to globally uninstall the wp-env tool

​
Troubleshooting

​
Docker Command Error

When using wp-env, it’s common to get the error: Error while running docker-compose command
  • Check that Docker Desktop is started and running
  • Check Docker Desktop dashboard for logs, restart, or remove existing virtual machines
  • Then try rerunning wp-env start

​
Host Already in Use

If you see the error: Host is already in use by another container
  • The container you are attempting to start is already running, or another container is
  • You can stop an existing container by running wp-env stop from the directory that you started it in
  • If you do not remember the directory, you can stop all containers by running docker stop $(docker ps -q) (use with caution)
  • Then try rerunning wp-env start

​
Ubuntu Docker Setup (Pre-20.04.1)

If you are using a version of Ubuntu prior to 20.04.1, you may encounter errors when setting up a local WordPress environment with wp-env.
Your environment should now be set up at http://localhost:8888.

​
Additional Resources