Sometimes you get a great idea, one that is so compelling that you really want to try it out right now! And since you’re a WordPress developer, that means you want to start coding up a quick proof of concept straight away.
The last thing you want to do is waste your time and creative energy setting up a new local WordPress instance. Depending on your local environment, that process can involve a variety of steps:
- downloading and installing WordPress,
- creating a database,
- editing the
- and more…
All of these things can be rather tiresome and none of them involve actually working on coding up your idea. Instead they’re things that hold you back, albeit temporarily, when what you really want to do is Just! Get! Coding!
Local-dev options you’ve probably heard of
So how fast can you get coding with the local-development options that are out there now?
Local (by Flywheel) is pretty good. You only need to install it once and after that, you have a short and painless path to an up-and-running WordPress installation, though you do still have to launch the app first whenever you want a development environment.
MAMP/WAMP/XAMPP, on the other hand, is at the other end of the scale. WAMP and XAMPP require you to install Apache, PHP, and MySQL/MariaDB separately. MAMP is a little easier, since the Mac operating system comes with PHP and Apache. And then, every time you want a new WordPress site, you have to:
- download the WordPress files,
- install the WordPress files,
- and laboriously configure the WordPress files.
Furthermore, if you need to host several sites locally you may also have to set up separate virtual hosts in Apache. (Maybe you should have started by writing down that brilliant idea in a notes app! 😄)
Another disadvantage of both Local and MAMP/WAMP/XAMPP, and also of the other environments you might use, like Laravel Valet, DevKinsta, and the now sadly defunct DesktopServer, is that they all make you build your theme or plugin in the
wp-content directory of your local WordPress installation.
Yes, it is possible to develop in another location, but then you then need to create a symlink in
wp-content/plugins that points to the directory you’re developing in.
And you’re still not coding yet!
So what do you do if, like me, you you don’t want to have to set up a whole new WordPress installation for every idea you want to experiment with? And moreover, if you would rather keep all your development projects in a single, easy-to-back-up
wp-env enables you to quickly spin up an almost instant WordPress environment from the command line, from whichever directory your project happens to be in, with zero configuration.
Gutenberg contributors developed
wp-env to aid developers in creating blocks and contributing to Gutenberg, but it can be used for any plugin or theme project.
It’s an extremely convenient way of getting a WordPress installation up and running quickly and easily so that you can get on with the business of developing your new project.
As you’ll see a little later on,
wp-env can also be included as a dev dependency in your project. This means that other developers collaborating on the project can clone it and spin up an identical environment.
Easy to install, easy to run
It’s extremely easy to install
wp-env. But hold on, there’s a couple of prerequisites.
wp-env requires Docker
Docker is used to package the WordPress installation that
wp-env creates into a sandboxed process known as a container, which is a virtualized application consisting of a web server, a database, and WordPress itself.
Putting your installation into a container isolates it from other processes on your machine. This distinguishes
wp-env from the other environments mentioned earlier which are not isolated in this way.
The container also enables the application state to persist across instances of the application. So the next time you you spin up
wp-env, all your posts, pages, and other content will be right where you left them.
wp-env requires Node/NPM
Node is how you install
wp-env, and NPM is how you run it. In fact, everything you do with
wp-env, you’ll do from the command line.
If you don’t already have Node/NPM installed head over there and follow the installation instructions.
So once you have Docker and Node/NPM in place, you can install
You can install it either locally to your project, or globally. Ideally you should install
wp-env globally, because then you’ll have it available everywhere on your development machine for any project that you want to use it with.
wp-env globally enter this command in the terminal:
npm -g i @wordpress/env
You can check that the installation has been successful with this command:
Alternatively, you can list the globally installed NPM packages:
npm list -g
And now it’s simple to get WordPress up and running. Just run the command:
from the directory where you want to create your project.
You can also install
wp-env locally to your project. In this case it’s only available to that one project, but you may prefer to keep the NPM global space clean. Installing locally also means that it will be a development dependency. Collaborators can then clone the project and be assured of an identical environment.
wp-env locally to the project enter this code from the project directory:
npm i @wordpress/env --save-dev
This will install
wp-env as a development dependency to the project and the
devDependencies property in
package.json will be updated to include this:
wp-env locally type this command in the terminal:
npx wp-env start
Alternatively you could add it to the
scripts property in
Then, to run it, type:
npm run wp-env start
Whether you installed it globally or locally to the project, this is what you should see in the terminal when the
wp-env environment has started:
WordPress development site started at http://localhost:8888/
WordPress test site started at http://localhost:8889/
MySQL is listening on port 62378
MySQL for automated testing is listening on port 62379
The address for the development site will be
http://localhost:8888/. Enter that into your browser’s address bar, and you’re good to go.
You can treat it just like any other WordPress site, and, as mentioned earlier, the containerisation provided by Docker ensures that the state, i.e. your content and settings, will persist across instantiations of
wp-env that you run from the same directory.
You’ll have noticed that there’s a development site on port 8888 and a test site on port 8889. You may be wondering, why two separate sites? The difference between them is that in the test site, the
SCRIPT_DEBUG are set to
false. The test site gives you unit tests and end-to-end tests you can run automated tests against. The development site is for testing with your own content. Any content that you add yourself to the test site will be deleted on running the tests.
Using WordPress in the environment
To access the WordPress admin panel use
http://localhost:8888/wp-admin. The logon credentials are “admin” and “password”—please don’t use these for your online banking! 😄
Once you’re logged in, you’ll find that the theme or plugin you’re working on has been automatically activated. So you can simply get on with working on your project.
When you’re done developing you can stop
wp-env by typing:
in the case of a global installation, or with one of the following in the case of a local-to-project installation:
npx wp-env stop
npm run wp-env stop
Which you use depends on how you started it in the first place.
And that’s pretty much it. It’s as simple as that.
wp-env is simple to install and super-simple to use. It neatly circumvents all the setup and configuration you need to do to get your WordPress installation up and running with other environments, and it lets you do your building wherever you like, not just in the
which will remove the Docker container when you don’t need it any more.
You can even run WP-CLI commands with:
wp-env run cli [command]
If you need to customize your WordPress installation, for example, if you want certain plugins to be installed and activated whenever you spin it up, you can specify a
.wp-env.json file in the directory you run
wp-env from. You can find out more in the section of the handbook page that talks about this.
If you’d like to delve into the inner workings of
wp-env, the code is a package in the Gutenberg repository on GitHub.
Finally, for a potential alternative in the future, keep your eye on the WordPress Playground project. That project aims to get WordPress working in the browser using WASM. There’s a demo available if you want to see it in action.
wp-envin the Block Editor handbook
wp-envfor Gutenberg contributors
wp-envpackage on GitHub