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 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

May I suggest that as this thread continues, and I expect it might, people specify exactly which WSL they’re using, 1 or 2.

Comparing WSL 2 and WSL 1

It took me a while to understand that those 1 and 2 versions aren’t simply an upgrade; they’re slightly different architectures and sometimes you’re better off sticking with v1.

This should make a difference in file system operations and I believe some of the issues described here might be related. I use WSL a lot but, so far, I haven’t tried Hugo on it; I plan to try it soon.

Using WSL 2 here with Ubuntu 20.04, hugo v0.74.3. I found this issue by googling, so, if you’re here with a similar issue, try this workaround.

One of OPs main concerns seems to have been how the hugo server wouldn’t rebuild (and livereload) on changes in the project directory.

I also had this issue while trying to run the server in a project that resided on the Windows mount of filesystem (e.g. /mnt/c/Users/tim/code/myblog/. After starting the server and making changes, the expected log output did not show up. No changes, no rebuilds, etc.

Moving the project onto the Linux filesystem fixed that (e.g /home/tim/code/myblog) for me. After doing so, Hugo logged about seeing changes and rebuilded as expected.

Now for some speculation:

Filesystem change/watch events (what hugo serve looks for with fsnotify) are low-level and OS-specific, and it seems WSL does not yet provide the same kind of environment/functionality for it’s Windows files into the Linux kernel (yet).

Digging a little more into fsnotify, but also while knowing very little about Go, I see they are considering OS-agnostic “polling” with watcher. Maybe if that feature happens, Hugo can choose to use it (or be configured by users to) and solve this issue here for us.


I also have hugo and git in the ubuntu file system with VSCode and web browser on windows and have no problems with git or live reload except when I get confused :wink:

Regarding my last post and looking a little deeper, WSL2 and inotify breakage for the Windows filesystem is a known issue:

But, it seems that it’s an incoming feature. So, perhaps better than waiting for fsnotify to include a polling watcher, we just wait until WSL2 implements this feature (and move our project files over to Linux until then). Polling is relatively slow compared to inotify events.

This worked just fine! I moved the actual repo to the ubuntu fs and then created a symbolic link in windows fs. Now, it works perfectly fine.

Thanks for the help!!