Install WordPress on Windows Subsystem for Linux

With the latest Creative Update on Windows you can run a full Linux environment, without the need of a virtual machine or other container system. It’s Linux on Windows, and it is pretty nice.

The following instructions are how to setup WordPress on Windows Subsystem for Linux (WSL), it also sometimes called Bash on Windows, but that can be confusing since there are bash shells that do run on Windows without the full Ubuntu/Linux environment.

Enable Windows Subsystem for Linux

First, you need to enable WSL. The Microsoft Installation Guide covers everything you need, so I’ll just give the high level.

  1. You must be running 64-bit Windows 10 with Creators Update (April 2017)
  2. Turn on Developer mode in Settings -> Update & Security -> For developers
  3. Search Turn Windows Features On or Off from Start Menu and enable Windows Subsystem for Linux
  4. From Powershell, run the command
    Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

  5. Reboot when prompted

  6. Run bash from Powershell which will prompt to install Ubuntu
  7. After install a shortcut will show in Start Menu, you can launch from there

This gives you a full Ubuntu Linux environment, you can run just about everything there (non-GUI apps).


The instructions are similar to how you would setup WordPress on any normal Linux. Launch into the Ubuntu environment.

Install Packages

Install mysql, php, and apache packages.

sudo apt-get -y install mysql-client mysql-server 
sudo apt-get -y install php7.0 php7.0-cli php7.0-common php7.0-curl php7.0-mysql php7.0-mcrypt php7.0-json php-mbstring 
sudo apt-get -y install apache2 libapache2-mod-php 

# enable modules
sudo a2enmod rewrite expires vhost_alias 

Setup WordPress

The easiest way (for me) to install and keep WordPress up-to-date is using the wp-cli command-line tool. Here’s the quick install, see their site for full details.

wget https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
mv wp-cli.phar ~/bin/wp

This assumes you have a $HOME/bin directory and it is in your path.

I want to be able to develop using Windows applications, but want the code to be accessible in Linux, so I install at one of the drive mount points. I have a secondary drive (D:) so my mount point on WSL is /mnt/d/

My install location is: /mnt/d/src/wpdev

Install WordPress with wp-cli is as easy as:

  1. mkdir -p /mnt/d/src/wpdev
  2. cd /mnt/d/src/wpdev
  3. wp core install

Now everything is installed, just need to configure up all the bits:

Configure

Apache

Windows needs to listen to Linux on a different port than 80, so edit /etc/apache2/ports.conf and add a Listen to line, I use port 8888

Listen 8888

Add a VirtualHost, I simply add it to /etc/apache2/sites-available/000-default.conf but if you want to create extra files and symlinks, you can add it as its own config file per site.

<VirtualHost *:8888>
        ServerName wpdev.local
        DocumentRoot /mnt/d/src/wpdev
        <Directory /mnt/d/src/wpdev>
                Options Indexes FollowSymLinks
                AllowOverride All
                Require all granted
        </Directory>
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Start Apache using: sudo service apache2 start

MySQL

No extra config should be necessary for MySQL.
Start mysql using: sudo service mysql start

You can test connecting to mysql using: mysql -u root -p
Use the password you created during install.

Create your WordPress database: mysqladmin -u root -p create wpdev

Configure WordPress

cd /mnt/d/src/wpdev
cp wp-config-sample.php wp-config.php

Edit wp-config.php filling in your database parameters, I simply use root db user since this is a development environment and only running locally.

The last piece is you need to update your hosts file, I add it on both Windows Subsystem for Linux and on Windows, so I can access it from either, though there is no GUI environment on Linux, it still can be helpful.

On Linux edit /etc/hosts and add 127.0.0.1 wpdev.local

On Windows, run Notepad as Administrator (right-click in Start Menu) and add the same line to hosts file located at C:\Windows\System32\drivers\etc\

127.0.0.1  wpdev.local

Now cross your fingers and everything should be working, go to your browser in Windows and load: http://wpdev.local:8888/ and it should start the WordPress setup, create your account and you’re off and running.

Develop on Windows

You need to keep the Bash on Ubuntu window running, the Linux environment shuts down if you don’t have it open and the services won’t continue running.

Also, each time you launch WSL, you need to start up Apache + MySQL – a minor annoyance but I always have WSL running since I use it so much, not too big of a deal. There is probably a way to start them via .bashrc or something, but I have aliases setup so its quick and easy to start. The init process doesn’t appear to be the same so the standard scripts don’t quite work.

I do most of my editing and work on Windows using Visual Studio Code, so I access D:\src\wpdev directly from Windows. The files are shared, so it’s not a problem.

I tend to just use the command-line in Linux for git and anything else.

Working with Visual Studio Code

If you do want to use the terminal in Visual Studio Code, note it does not run in Linux, you need Windows native commands. Also to get linting, git, and other things setup properly in VSCode you’ll need to install the native packages. I also do full Javascript development this way so do have the basics installed:

Git & Bash: https://git-scm.com/downloads
PHP: http://windows.php.net/download/
Node: https://nodejs.org/en/download/

Once installed you can configure Visual Studio Code Terminal to use Bash instead of Powershell, and set the PHP executable where you extract it to:

    "terminal.integrated.shell.windows": "C:\\Program Files\\Git\\bin\\bash.exe",
    "php.validate.executablePath": "C:\\bin\\php\\php.exe",

Summary

I hope this helps, I wrote this after the fact and already had everything setup, so haven’t done a full clean run through, so hopefully I didn’t miss any crucial steps, please let me know if you hit a snag.