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

1
Install Docker Desktop
2
Download, install, and start Docker Desktop following the instructions for your operating system.
3
Install wp-env Globally
4
Run the following command in the terminal to install wp-env globally:
5
npm -g install @wordpress/env
7
In the terminal, navigate to an existing plugin directory, theme directory, or a new working directory.
8
cd /path/to/your-plugin
9
Start the Local Environment
10
Run the following command to start the local WordPress environment:
11
wp-env start
12
Access WordPress
13
After the script runs, navigate to http://localhost:8888/wp-admin and log into the WordPress dashboard using:
14
  • Username: admin
  • Password: password

    • ​
    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: 
    !! Warning: could not find a .wp-env.json configuration file and could not determine if 'DIR' is a WordPress installation, a plugin, or a theme.

    ​
    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: 
    {
  "$schema": "./schemas/json/wp-env.json",
  "testsEnvironment": false,
  "core": "WordPress/WordPress",
  "plugins": [ "." ],
  "themes": [ "./test/emptytheme" ],
  "phpmyadminPort": 9000
}
    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

    npm run wp-env status   # Check status
npm run wp-env start    # Start environment
npm run wp-env stop     # Stop environment

    ​
    Managing the Environment

    # Clean the WordPress database
wp-env clean all

# Remove the local environment completely
wp-env destroy

# Check wp-env version
wp-env --version

    ​
    Example Gutenberg Workflow

    # Setup
npm install && composer install
npm run wp-env status   # Always check status first
npm run wp-env start    # Only start if not already running

# Development
npm start               # Development with watch
npm run build          # Production build

    ​
    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.
    1
    Install Docker
    2
    Follow the installation guide from Docker. docker-compose is also required, which you may need to install separately. Refer to the Docker compose documentation.
    3
    Check if Docker is Running
    4
    Run the following command:
    5
    ps -ef | grep docker
    6
    You should see something like:
    7
    /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
    8
    Start Docker Service
    9
    If Docker is not running, try starting the service:
    10
    sudo systemctl start docker.service
    11
    Configure Docker Remote Access
    12
    If Docker is running but not listening correctly, add the following service override file:
    13
    # /etc/systemd/system/docker.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2376
    14
    Restart Docker Service
    15
    Restart the service from the command-line:
    16
    sudo systemctl daemon-reload
sudo systemctl restart docker.service
    17
    Set Environment Variable and Start
    18
    After restarting the services, set the environment variable DOCKER_HOST and start wp-env:
    19
    export DOCKER_HOST=tcp://127.0.0.1:2376
wp-env start
    Your environment should now be set up at http://localhost:8888.

    ​
    Additional Resources

    Build docs developers (and LLMs) love

    Get started for freeTalk to us