[Guide] Developing on Windows 10 using WSL

I think I ran into another small issue which I’m surprised I can’t find anyone talking about on Google.

I was unable to use BrowserSync due to /etc/hosts not being in sync with Windows’ host file so when it goes to proxy my internal host for my Trellis box, it’s unable to resolve it.

cat /mnt/c/Windows/System32/drivers/etc/hosts | grep 192.* | sudo tee -a /etc/hosts

I wrote that just now which is a dirty workaround for this. I’m sure it could be made into a script or something to be included in a ~/.bashrc or ~/.zshrc – but I’m more so curious on any of your guys’ take on a more sane solution?

1 thing to consider is by default, WSL’s /etc/hosts resets it’s self to default when a new instance is made. See Issue #398 on the BashOnWindows repo.

This can be rectified by removing:

# This file was automatically generated by WSL. To stop automatic generation of this file, remove this line.

at the top of the /etc/hosts file.

Another thing to note is this has been brought up as an Issue, but doesn’t seem to of been escalated or pushed in any way. See: Issue #149.

Another small thing to watch for is:

Couldn't open browser (if you are using BrowserSync in a headless environment, you might want to set the open option to false)

I was able to fix this by adding, in my case, Firefox to Windows PATH and then setting:

browser: 'firefox.exe'

in BrowserSync’s options.

Edit: Looks like this is being worked on internally.


Added a few more simple guides for installing zsh and rbenv.

If anyone has any other suggestions, let me know.

Thanks a bunch for this guide!

It looks like Vagrant recently merged full support for running vagrant native inside WSL. :slight_smile:

Thanks for this, was just trying to get Browsersync working and this is a quick fix. Hopefully WSL will sync or at least update from the Windows hosts file eventually.

I’m working on a rewrite of this guide including setting up Valet for seamless development on Windows using Acrylic DNS to manage wildcard hosts (i.e. *.dev automatically pointing to localhost and resolving with no extra setup). It’s a breath of fresh air in the Windows world.

Stay tuned.


just curious but why is the only way to install php 7.1 via some random git repository??

Ondřej just happens to run the official unofficial repository for PHP and has for years. Ubuntu is not a bleeding edge distro thus its packages are usually out of date to maintain “stability”.

An alternative would be to use a distro like Arch Linux for your subsystem instead.


hm… but windows automatically installed ubuntu -.- i did manage to get php 7 via sudo apt-get install php

Yes, Ubuntu is the default. It’s a sensible default…

the process was automatically handled by windows, though. how could have i installed a different distro?

how come linux files aren’t updated after creating a symbolic link to a windows folder and updating files on windows? how can i achieve this?

We really appreciate when someone takes time to create a guide for Roots users here. However, this forum isn’t for general debugging or general questions, we do want to keep it Roots focused. Questions about how to use WSL separate from WordPress and web development would be much better asked and answered on WSL support forums.

Can you point me in the right direction? Where can I find those forums? It’s been so incredibly difficult finding any relevant information via Google.




thanks!! i will be bookmarking your post. i figured out what the issue was. for some reason i could not include a dash in the filename of a CSS file which was referenced by a PHP file, otherwise modifications to the CSS file would not show up in the browser :confused:

Thank you so much for this. It helped me install composer and php. But when I was using composer install, it was working really slowly, saying it couldn’t find zip extension or unzip, so I added php-zip and unzip for it to run MUCH more smoothly!

sudo apt-get install php7.2 php7.2-mbstring php7.2-xml php7.2-zip
sudo apt-get install unzip

I had another issue with node, when I used ‘npm start’ it couldn’t find the node-sass library. I think it wasn’t in /usr/bin and that was causing an issue. Using these commands (in this github comment) helped me resolve it.

Thank you again for providing this because it got me the furthest of anything I have found up to now. I’m running!

I am running Docker (Toolbox) now on WSL, so I don’t need any Virtual Machine for development right now (well, technically the Docker Toolbox uses a VM internally (boot2docker)).


Further notes:

I have since switched to Hackintosh and more than likely will not be upgrading this guide anytime soon.

One suggestion I do have though is to check out valet for WSL with Acrylic DNS instead of running Virtualbox/Hyper-V on top of an environment that already has some rather unfortunate limitations when it comes to disk performance.

For anyone trying to get Browersync working, after adding your browser of choice to your Windows PATH, here’s how to specify it in Sage’s browsersync config (using Chrome as an example). Update this section in webpack.config.watch.js:

new BrowserSyncPlugin({
  open: config.open,
  proxyUrl: config.proxyUrl,
  watch: config.watch,
  delay: 500,
  advanced: {
    browserSync: {
      browser: "chrome.exe",