NB! Needs an update!
To start contributing to the WordPress core codebase, you will need to set up a local development environment. This environment consists of everything necessary to run the WordPress software and track your changes for the team to see. The following are instructions for setting up a local development environment for WordPress.
- To understand how to setup a Local development environment.
- How to uninstall the environment.
Mac and Linux
1. Install required software for modifying codebase and tracking changes.
The WordPress core development environment requires a few important pieces of software that you will need on your local machine before you start contributing. We will first install Homebrew to help us download these software packages.
In terminal, type this command.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
You will likely be asked to insert your OS password. Type it in and press enter.
You might also be asked if you want to install the Xcode Command Line Tools. Confirm “yes” to ensure Homebrew operates as expected. It can take a few minutes for it to download all that is needed. Give it some time and wait for the prompt to return.
Next, you will need to instal Git to allow you to track changes alongside the WordPress core team. Install Git using Homebrew with this command:
brew install git
Third, you will need to install Docker. Think of Docker as a container that stores all the really complicated tools you will need to run a server on your computer. With Docker, distributed teams like WordPress can set up the same configurations and simplify their workflows.
To install Docker, visit https://www.docker.com/products/docker-desktop and follow the instructions provided. (NB! If you happen to have MAMP, VVV or anything else like that running. It might create a problem to get Docker running correctly. It is advised to close these other programs.)
You can alternatively install Docker with this command:
brew cask install docker
If that does not work type:
brew install cask docker
Finally, you will need to install Node.js. We use Node in a lot of ways at WordPress, such as automatic testing, so this will be a key part to your development puzzle. In terminal, type this command to install Node:
brew install node
2. Create your development environment
Open the Docker application on your computer and ignore the welcome screen that tells you to create a container. We will use the container that the WordPress team uses instead.
Next, you will need to clone the core WordPress Github repository. A repository is simply a folder. In our case, it is a folder with many other files inside of it.
In terminal navigate to a place in your file system that you like your WordPress environment to live in. For example, if you wanted your environment to live in your Documents folder, you could type this command.
Now that you are in the directory you want WordPress to live in, clone the WordPress core repository from Github into your folder:
git clone https://github.com/WordPress/wordpress-develop.git
The above command automatically creates a wordpress-develop folder for you. Navigation to the folder with this command:
Next, you will need to install dependencies in your environment. Dependencies are necessary code packages to make your environment work as expected. Install those dependencies by typing:
Now build the structure of your environment! Run this command:
npm run build:dev
With your environment built, we will run two more commands to help create the database and server configurations.
npm run env:start
If you have problems running npm run env:start then use
brew install subversion
Then finally type:
npm run env:install
3. Explore your development environment
When you installed your dependencies and set up your server configurations, you also created a way to access a development site from your computer. You should now be able to access the development version of WordPress at http://localhost:8889/ . To sign in to your local WordPress install, go to
http://localhost:8889/wp-login.php and use the following default credentials:
For more information on end-to-end testing, shutting down your environment, and database configurations, please refer to the README.md file in the
wordpress-develop repository: https://github.com/WordPress/wordpress-develop.
One great place to get started using the local environment is by testing a Trac ticket or a Github pull request.
In order for Docker to run, you cannot be running MAMP, VVV or any similar program at the same time.
Creating a development environment is a complicated task. Below are some common errors you may run into and how to fix them:
Docker authorization error when the
npm run env:start or
npm run env:install commands are run:
Pulling php (wordpressdevelop/php:latest)… Head https://registry-1.docker.io/v2/wordpressdevelop/php/manifests/latest: unauthorized: incorrect username or password child_process.js:669 throw err; ^
npm run env:start or
npm run env:install commands are run, Docker commands are simultaneously run from the command line.
For security, Docker requires you to sign in with your Docker ID and password in the Docker application on your computer. If you have no already, create a Docker account and sign in with your Docker ID. If you forgot your password, you can request a new one from Docker’s login area. Refer to this article from Dylan Pierce or this Github issue for more information.
Subversion software not found when
npm run env:install is run:
/bin/sh: svn: command not found child_process.js:669 throw err; ^
Subversion (svn) is a version control system similar to Git that WordPress uses to power its Trac system. When you use the
npm run env:install command, your local environment attempts to pull the most recent WordPress core files from Trac using Subversion.
If you do not have Subversion installed on your computer, you will likely see the error message above. Simply install Subversion with the command below and run the
npm run env:install code immediately after:
brew install subversion
5. Uninstall instructions
In terminal (root) add the following:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/uninstall.sh)"
Type y to confirm and type your password.
Open Docker and go to the Dashboard.
Click the bug icon button seen in the top blue bar.
Click the Uninstall button.
Then drag the Docker app to your trash can.
If you do not want to remove Docker.
Uninstall WordPress developer environment
In terminal type:
npm run env:reset
This will uninstall the Docker image and all the virtual discs it creates.
Open the Operating system user folder. The wordpress-develop folder is located there. Select it and drag it to the trash can.