I've always upgraded my WSL distros the same way I upgrade them on regular installs, following more or less the official debian upgrade docs (taking some shortcuts as I know I can skip some bits in my specific case).
One caveat though, when upgrading a WSL1 distro from bullseye to bookworm, I ran into an issue with the usrmerge
package that merges directories between /
and /usr
. WSL1 runs as a Linux implementation on top of the NT microkernel (which was designed from the beginning to be OS-agnostic), and so the files live on the native NTFS filesystem and Linux processes runs as native NT (but not Win32) processes.
Just like it's often impossible to rename open files on Windows, replacing /lib
with a symlink to /usr/lib
failed with a Permission Denied
error. See for example:
https://github.com/microsoft/WSL/issues/8927
https://github.com/microsoft/WSL/issues/4279#issuecomment-1846822075
Luckily I had the error only with the /lib
directory, which means it only failed to move away /lib
to replace it with a symlink to /usr/lib
.
The steps I used to fix it are as follow. Note that for Windows commands you shouldn't need an admin cmd prompt, but on Linux you will need to use sudo or a root shell.
Ensure you can start a new shell to Debian. Just start a new shell without closing the current one; the next steps involve shutting down WSL so if this fails you likely won't be able to resume the install after that.
From Debian, create a symlink to /usr/lib
with a different name (creating files from windows doesn't set UNIX attributes, but moving them is OK so we'll move it from Windows later).
sudo ln -s /usr/lib /lib-new
Close all shells and processes that may be running on Debian.
From Windows command prompt, ensure WSL1 is shutdown using the following command; it should not list your distribution (if it keeps running after a couple minutes, try shutting it down using the wsl
tool or reboot the computer).
wsl -l --running
Go to your distro root, the path should be something like %LOCALAPPDATA%\Packages\TheDebianProject.DebianGNULinux_<RANDOM_STRING>\LocalState\rootfs
Using dir
you should see lib
and lib-new
. Swap them around.
ren lib lib-old
ren lib-new lib
Restart the Debian shell
From Debian, re-run apt upgrade
(or full-upgrade
, in my case it happened in the first pass, a normal upgrade).
sudo apt upgrade
You can do this before step 8 or later, you will have to clean-up the lib-old
directory.
sudo rm -rf /lib-old
The same steps should work for other directories too. For files, if any fail, a simple move should do, although it may be best checking /usr/lib/usrmerge/convert-usrmerge
and see what it was trying to do first (In my case I made a copy to /tmp
which I modified, adding more debug output to ensure I got a good understanding of the error).
wsl
in Win11, @user1686