`wp-env`

wp-env lets you easily set up a local WordPress environment for building and testing plugins and themes. It's simple to install and requires no configuration.

Quick (tl;dr) instructions

Ensure that Docker is running, then:

$ cd /path/to/a/wordpress/plugin
$ npx wp-env start

The local environment will be available at http://localhost:8888.

Instructions

Installation

wp-env requires Docker to be installed. There are instructions available for installing Docker on Windows 10 Pro, all other versions of Windows, macOS, and Linux.

After confirming that Docker is installed, you can install wp-env globally like so:

$ npm -g i @wordpress/env

You're now ready to use wp-env!

Starting the environment

First, ensure that Docker is running. You can do this by clicking on the Docker icon in the system tray or menu bar.

Then, change to a directory that contains a WordPress plugin or theme:

$ cd ~/gutenberg

Then, start the local environment:

$ wp-env start

Finally, navigate to http://localhost:8888 in your web browser to see WordPress running with the local WordPress plugin or theme running and activated. Default login credentials are username: admin password: password.

Stopping the environment

To stop the local environment:

$ wp-env stop

Troubleshooting common problems

Many common problems can be fixed by running through the following troubleshooting steps in order:

1. Check that `wp-env` is running

First, check that wp-env is running. One way to do this is to have Docker print a table with the currently running containers:

$ docker ps

In this table, by default, you should see three entries: wordpress with port 8888, tests-wordpress with port 8889 and mariadb with port 3306.

2. Check the port number

By default wp-env uses port 8888, meaning that the local environment will be available at http://localhost:8888.

You can configure the port that wp-env uses so that it doesn't clash with another server by specifying the WP_ENV_PORT environment variable when starting wp-env:

$ WP_ENV_PORT=3333 wp-env start

Running docker ps and inspecting the PORTS column allows you to determine which port wp-env is currently using.

You may also specify the port numbers in your .wp-env.json file, but the environment variables take precedent.

3. Restart `wp-env`

Restarting wp-env will restart the underlying Docker containers which can fix many issues.

To restart wp-env:

$ wp-env stop
$ wp-env start

4. Restart Docker

Restarting Docker will restart the underlying Docker containers and volumes which can fix many issues.

To restart Docker:

Click on the Docker icon in the system tray or menu bar.
Select Restart.

Once restarted, start wp-env again:

$ wp-env start

5. Reset the database

Resetting the database which the local environment uses can fix many issues, especially when they are related to the WordPress installation.

To reset the database:

⚠️ WARNING: This will permanently delete any posts, pages, media, etc. in the local WordPress installation.

$ wp-env clean all
$ wp-env start

6. Nuke everything and start again 🔥

When all else fails, you can try forcibly removing all of the underlying Docker containers and volumes, the underlying WordPress directory, and starting again from scratch.

To nuke everything:

⚠️ WARNING: This will permanently delete any posts, pages, media, etc. in the local WordPress installation.

$ docker rm -f $(docker ps -aq)
$ docker volume rm -f $(docker volume ls -q)
$ rm -rf "../$(basename $(pwd))-wordpress"
$ wp-env start

Command reference

wp-env creates generated files in the wp-env home directory. By default, this is ~/.wp-env. The exception is Linux, where files are placed at ~/wp-env for compatibility with Snap Packages. The wp-env home directory contains a subdirectory for each project named /$md5_of_project_path. To change the wp-env home directory, set the WP_ENV_HOME environment variable. For example, running WP_ENV_HOME="something" wp-env start will download the project files to the directory ./something/$md5_of_project_path (relative to the current directory).

`wp-env start [ref]`

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). The current working directory must be a
WordPress installation, a plugin, a theme, or contain a .wp-env.json file.


Positionals:
  ref  A `https://github.com/WordPress/WordPress` git repo branch or commit for
       choosing a specific version.                 [string] [default: "master"]

`wp-env stop`

wp-env stop

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

`wp-env clean [environment]`

wp-env clean [environment]

Cleans the WordPress databases.

Positionals:
  environment  Which environments' databases to clean.
            [string] [choices: "all", "development", "tests"] [default: "tests"]

`wp-env run [container] [command]`

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

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


Positionals:
  container  The container to run the command on.            [string] [required]
  command    The command to run.                           [array] [default: []]

For example:

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 10:45:14     administrator

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

`docker logs -f [container_id] >/dev/null`

docker logs -f <container_id> >/dev/null 

Shows the error logs of the specified container in the terminal. The container_id is the one that is visible with `docker ps -a`

.wp-env.json

You can customize the WordPress installation, plugins and themes that the development environment will use by specifying a .wp-env.json file in the directory that you run wp-env from.

.wp-env.json supports five fields:

Field	Type	Default	Description
`"core"`	`string\|null`	`null`	The WordPress installation to use. If `null` is specified, `wp-env` will use the latest production release of WordPress.
`"plugins"`	`string[]`	`[]`	A list of plugins to install and activate in the environment.
`"themes"`	`string[]`	`[]`	A list of themes to install in the environment. The first theme in the list will be activated.
`"port"`	`integer`	`8888`	The primary port number to use for the insallation. You'll access the instance through the port: 'http://localhost:8888'.
`"testsPort"`	`integer`	`8889`	The port number to use for the tests instance.
`"config"`	`Object`	`"{ WP_DEBUG: true, SCRIPT_DEBUG: true }"`	Mapping of wp-config.php constants to their desired values.

Note: the port number environment variables (WP_ENV_PORT and WP_ENV_TESTS_PORT) take precedent over the .wp-env.json values.

Several types of strings can be passed into the core, plugins, and themes fields:

Type	Format	Example(s)
Relative path	`.<path>\|~<path>`	`"./a/directory"`, `"../a/directory"`, `"~/a/directory"`
Absolute path	`/<path>\|<letter>:\<path>`	`"/a/directory"`, `"C:\\a\\directory"`
GitHub repository	`<owner>/<repo>[#<ref>]`	`"WordPress/WordPress"`, `"WordPress/gutenberg#master"`
ZIP File	`http[s]://<host>/<path>.zip`	`"https://wordpress.org/wordpress-5.4-beta2.zip"`

Remote sources will be downloaded into a temporary directory located in ~/.wp-env.

.wp-env.override.json

Any fields here will take precedence over .wp-env.json. This file is useful, when ignored from version control, to persist local development overrides.

Examples

Latest production WordPress + current directory as a plugin

This is useful for plugin development.

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

Latest development WordPress + current directory as a plugin

This is useful for plugin development when upstream Core changes need to be tested.

{
	"core": "WordPress/WordPress#master",
	"plugins": [ "." ]
}

Local `wordpress-develop` + current directory as a plugin

This is useful for working on plugins and WordPress Core at the same time.

{
	"core": "../wordpress-develop/build",
	"plugins": [ "." ]
}

A complete testing environment

This is useful for integration testing: that is, testing how old versions of WordPress and different combinations of plugins and themes impact each other.

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

Custom Port Numbers

You can tell wp-env to use a custom port number so that your instance does not conflict with other wp-env instances.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

`wp-env`

Quick (tl;dr) instructions

Instructions

Installation

Starting the environment

Stopping the environment

Troubleshooting common problems

1. Check that `wp-env` is running

2. Check the port number

3. Restart `wp-env`

4. Restart Docker

5. Reset the database

6. Nuke everything and start again 🔥

Command reference

`wp-env start [ref]`

`wp-env stop`

`wp-env clean [environment]`

`wp-env run [container] [command]`

`docker logs -f [container_id] >/dev/null`

.wp-env.json

.wp-env.override.json

Examples

Latest production WordPress + current directory as a plugin

Latest development WordPress + current directory as a plugin

Local `wordpress-develop` + current directory as a plugin

A complete testing environment

Custom Port Numbers

Files

README.md

Latest commit

History

README.md

File metadata and controls

wp-env

Quick (tl;dr) instructions

Instructions

Installation

Starting the environment

Stopping the environment

Troubleshooting common problems

1. Check that wp-env is running

2. Check the port number

3. Restart wp-env

4. Restart Docker

5. Reset the database

6. Nuke everything and start again 🔥

Command reference

wp-env start [ref]

wp-env stop

wp-env clean [environment]

wp-env run [container] [command]

docker logs -f [container_id] >/dev/null

.wp-env.json

.wp-env.override.json

Examples

Latest production WordPress + current directory as a plugin

Latest development WordPress + current directory as a plugin

Local wordpress-develop + current directory as a plugin

A complete testing environment

Custom Port Numbers

`wp-env`

1. Check that `wp-env` is running

3. Restart `wp-env`

`wp-env start [ref]`

`wp-env stop`

`wp-env clean [environment]`

`wp-env run [container] [command]`

`docker logs -f [container_id] >/dev/null`

Local `wordpress-develop` + current directory as a plugin