A Cautionary Tale: Mixing Windows and WSL (Windows Subsystem for Linux)


Hello everyone! I wanted to share something that was not obvious to me when I set up and led to quite a few headaches.

I’ve recently gone back to a Windows machine from a Linux box, and I thought WSL was going to be a great way to keep my tooling setup without having to worry about virtually anything in Windows land. I setup my Hugo work environment as follows:

  • On Windows
    • Firefox
    • VS Code (tied to WSL via wslgit.exe)
    • The actual repo files
  • On WSL
    • Hugo
    • git

First, I should say how impressive it is that this mostly worked without any special configs. VSCode mostly played nice, if slow, with the WSL git. The Hugo server from WSL loaded just fine in the Windows browser. Heck, live reload even pretty much worked.

… most of the time.

And then from time to time things would just… stop getting updated in the browser.

The lookup paths wouldn’t seem to go all the way through. Shortcodes I added wouldn’t get recognized. Occasionally it wouldn’t pickup content updates at all. Restarts didn’t seem to help, but interestingly time passing seemed to fix it… for a while.

At first I thought the problem was something I wasn’t visualizing correctly with lookup paths, but then I realized WSL might be to blame.

I’ve since shifted everything to its Windows based version (Windows hugo binary, and switching to fossil for SCM), and everything now works exactly as I expect.

I ran a few searches and didn’t see much here on WSL, so I add this as a cautionary tale that while it may seem to work much of the time, you’ll save youself a lot of headache if you go all in on the Windows version of things… (even if that means switching VCS’s because installing git on Windows is a pain).


What was the issue?

1 Like

I personally use Hugo (0.54.0) on WSL (with your exact setup, except I use Chrome) and it runs fine for me. What Hugo version were you using?

Wait, really? I’ve run the “Git for Windows” installer in the past without issue, and it automatically adds Git to your PATH.

1 Like

Microsoft mentions the pain in their FAQ.:wink:

1 Like

Three main things:

  1. Live reload didn’t seem to work when I changed a file… sometimes
  2. It never picked up a shortcode I wrote that just inserted an h2
  3. The _index.md page for root would occasionally detect changes, and occasionally not

I’d only built two other sites with hugo before, so I wasn’t convinced the problem wasn’t between chair and keyboard, but it just started to smell like something else was afoot given I hadn’t run into these problems on my Mac.

I would love to say I figured out the problem… but that would be a lie (except that it seems to be better now). I don’t think hugo is to blame though. I think it’s much more likely that WSL is just really difficult to pull off correctly, and sometimes it doesn’t work quite right in all cases.


More power to ya. I found it started to break down for me and wanted to share in case anyone else ran into ghosts on their machine. hugo 0.54, Windows 10, non-Insider version of WSL.

The installers do work, but I had some issues in the past ending up with multiple versions installed from different tools and never being sure which was in use in a given shell/ui. Not sure if it’s gotten better recently, but after using installing a few go tools (and fossil, which installs similarly) by putting the binary on the path, it’s hard for me to go back.

Just a personal preference.


Thanks for sharing. Perhaps I just haven’t hit a bump yet. It’s been a recent change for me. Previously I used a Fedora VirtualBox VM, but WSL takes up way less space, and is snappier.


Chiming in to say that I am also encountering issues with WSL, in particular Hugo fails more often than not in picking up partials, shortcodes and internal templates.


@FTWynn @Jickelsen Do you guys have a small test case/git repo to share? I want to see if I can reproduce the issue on my end

1 Like