Troubleshooting Ubuntu on WSL

This page includes a few lessons learned by users about specific issues related to Ubuntu on WSL and how to deal with them.

Scope

This page is about unexpected or undesirable behaviors observed only when Ubuntu runs on WSL. This page is not for general WSL issues nor issues encountered running other distros on WSL.

Kernel mismatch

Ubuntu tracks the Linux kernel quite closely, while WSL stays on older LTS versions of the kernel for longer periods of time.

It's possible that some functionality you want in Ubuntu may depend on features or behaviors not yet present in the WSL kernel. If that happens:

1. Upvote an issue against the microsoft/WSL repo, requesting the particular feature. It's likely that the Ubuntu on WSL team would have already opened such issue. If not, you're welcome to do so, if possible pointing to commits in the kernel git history that implement it.
2. Compile your own custom kernel. It is generally not as hard as it may sound, the process is well documented and you may even find videos on YouTube demonstrating it. A short guide can be found at the WSL2 kernel repository . Once compiled, save your custom kernel on the Windows file system and configure WSL2 to use it (see the .wslconfig documentation).

System upgrades

A successful system upgrade requires a few preconditions:

• systemd must be enabled. That's the default on Ubuntu. If it is disabled, then edit your wsl.conf settings and restart your distro instance.
• The current system must be up-to-date. If not run sudo apt update && sudo apt upgrade -y

Those requirements make it essentially impossible to get a clean upgrade on WSL1, especially because postinstall hooks of systemd itself (and some packages that ship systemd units) triggers systemd actions while it's not running.

With those requirements satisfied, if sudo do-release-upgrade finds a suitable upgrade to perform, then it should not fail.

While writing this page, I was upgrading one instance from 24.04.5 to 26.04.1 and another one from 22.04.5 to 24.04.5. Here's what the end of that process looks like (he exact details may differ between Ubuntu releases):

...
Purging configuration files for ubuntu-mono (24.04-0ubuntu2) ...
Purging configuration files for libpython3.12-minimal:amd64 (3.12.3-1ubuntu0.17) ...
Purging configuration files for humanity-icon-theme (0.6.16build1) ...
Purging configuration files for uuid-runtime (2.41.3-3ubuntu2.2) ...
All snaps up to date.

System upgrade is complete.

Action required

Exit all other instances of Ubuntu WSL before continuing.

Unsaved progress may otherwise be lost.

To continue please press [ENTER]


WSL restart required

Exit this instance of Ubuntu WSL.

The upgrade will then be complete.

To continue please press [ENTER]

Yet, there were some cases where users reported different issues:

• A total hang caused by some systemd unit: likely caused by systemd itself or some feature not yet present in the system. At that point in time your system is in a bad state and you must complete the upgrade forcefully. You need to identify which unit is hanging. With the instance still blocked, open a new terminal and shell into that distro instance. Back in the days of 18.04 and 20.04 users mentioned snapd as a common cause for such hangs . If that's your case, remove snapd, clean your local apt repository and try again. On success, reinstall snapd to continue using snaps. Your snaps will remain stored at /var/lib/snapd/snaps/ so a reinstall of snapd will just work.

  sudo apt remove snapd
  sudo apt clean
  sudo do-release-upgrade -y
  

• If systemd itself is the cause, you need to pin it. Uninstall systemd is not an option, even if it's disabled. That's a side effect of how system images are generated. This technique may also be used for other packages known to fail to upgrade. It's been reported to work even in WSL1 !

Snaps

The days when snaps couldn't run at all in WSL are in the past. Yet, there are a few corner cases users hit every once in a while. First of all, we need to make it clear that WSL2 kernel doesn't ship or prefer any Linux Security Module (LSM) implementation, and snapd require the AppArmor LSM to make the confinement of snaps work. So you either compile your own kernel to include AppArmor or accept that snaps will run like in classic/unconfined mode. Second, snapd itself rely on systemd, enabled by default on Ubuntu, so make sure to not disable systemd if you want to run snaps.

Graphics and system dependencies

While snaps bundles most of their dependencies, some users have reported situations in which a snap failed to launch due to a missing dependency. Ubuntu on WSL does not ship an entire desktop system, so it's possible that you find a snap failing to launch due to missing GL-related library, for example.

The short term fix is installing the missing library with apt, but you should consider opening a bug report suggesting that the publisher stages the missing package. Sometimes that's not viable, because the missing package is tied to the hardware, or multiple packages may offer the same API, so it's ultimately a user's runtime choice which package to install. The snap ecosystem has improved over time with concepts like SDKs for shipping common dependencies and components to cope with optional, mutually exclusive dependencies. Fortunately none of the examples I've seen in the past are reproducible today, so I cannot give any screen shot or terminal log illustrating this. If you have an example, please feel free to add it here.

Non-Ubuntu specific issues and workarounds

Those do not fit here, but you can find invaluable information at the WSL2 repository on GitHub. Their issues and discussion pages contain lots of reports from users of different backgrounds who are using WSL in different environments. Their discussion mention antivirus software blocking certain actions, corporate policies affecting certain features, etc. The only challenge is fighting your search engine to find what you need amongst the vast amount of information available.

Has an issue been missed?

You're welcome to contribute other issues to this page, and to help keep it current and useful.