Upgrade an Ubuntu Release Inside WSL Without Losing the Recovery Path

There are two different things administrators casually call “updating WSL.” wsl --update updates the Windows Subsystem for Linux platform package, while apt upgrade updates packages inside one Linux distribution. Moving Ubuntu from one release to another is a third operation, managed by Ubuntu’s release upgrader. These changes have separate compatibility, downtime, and recovery paths; applying one does not perform the others.

This runbook covers an Ubuntu release upgrade within a WSL distribution. It is intentionally Ubuntu-specific: the release upgrader, supported upgrade route, repositories, and prompts are owned by Ubuntu, not by Microsoft. The cited Canonical guide describes Ubuntu Server and cloud images, not a WSL-specific support guarantee, so rehearse the exact upgrade in a restored copy first and stop if the target upgrader depends on host behavior WSL cannot provide. WSL adds host-level registration, export/restore, and shutdown behavior around that Linux userspace. Keep those layers separate throughout the change.

Confirm you are upgrading the intended layer

From PowerShell, capture the platform and distro state:

wsl.exe --version
wsl.exe --status
wsl.exe --list --verbose

Inside the Ubuntu distro, identify the current Ubuntu release and package state:

cat /etc/os-release
uname -r
dpkg --print-architecture
sudo apt update
apt list --upgradable

uname -r describes the Linux kernel exposed to the distro and is not the Ubuntu release identifier. cat /etc/os-release reports the userspace release. A successful wsl --update can update the WSL package/kernel without moving that userspace to a new Ubuntu release; conversely, changing Ubuntu releases does not automatically update WSL itself.

Check the exact Ubuntu release notes, end-of-standard-support status, architecture, and supported upgrade path before starting. Ubuntu’s guidance allows direct upgrades between sequential LTS releases, not arbitrary skips. The release prompt’s availability can depend on Ubuntu’s release policy and point-release timing. Do not force a development release or use do-release-upgrade -d in a production workflow simply because the target is not yet offered.

Inventory what must survive

Treat the upgrade as a system change, even though WSL is often used for development. Record installed packages, repositories and PPAs, manually installed tools, service units, containers and volumes, databases, language runtimes, custom kernel modules, scheduled jobs, and data stored outside the distro’s root filesystem. Third-party repositories and PPAs are disabled during Ubuntu’s release upgrade; packages installed from them may remain, but their source may need a release-compatible replacement afterward.

Identify which state lives under the distro’s ext4 filesystem and which state lives on Windows mounts, another VHDX, a network share, Docker Desktop’s data distribution, or another WSL distro. A distro export cannot silently turn those external locations into part of the root-filesystem backup. Back up each stateful system with its own consistency procedure. In particular, stop or snapshot databases using their supported method instead of assuming that an online tar/export is application-consistent.

Export the distro from Windows after quiescing writers. Use a unique dated path on a protected volume with sufficient capacity:

wsl.exe --terminate Ubuntu-Dev
wsl.exe --export Ubuntu-Dev D:\WSL-Backups\Ubuntu-Dev-pre-release-upgrade.tar
Get-FileHash D:\WSL-Backups\Ubuntu-Dev-pre-release-upgrade.tar -Algorithm SHA256

Keep the archive until the upgraded distro passes application checks and you have tested a restore. An export is a recovery artifact, not proof of a restorable system. If the workload matters, import a copy under a temporary unique name and rehearse the same release-upgrade path before changing the main registration. Do not unregister the original to “make room” until the backup and restore are independently verified.

Bring the current release fully up to date

Ubuntu’s release-upgrade guidance asks administrators to apply current package updates first, review the package plan, ensure adequate free space, and have time to answer prompts. In the Ubuntu distro:

sudo apt update
sudo apt dist-upgrade -o APT::Get::Always-Include-Phased-Updates=true
df -h /
if [ -e /run/reboot-required ]; then echo "Ubuntu requests a restart"; fi

Review removals and held packages rather than accepting a surprising plan automatically. The command can install new dependencies and remove packages; this is broader than the ordinary apt upgrade path. Confirm the package operation completed without errors and that the root filesystem has enough room for several gigabytes of downloads and unpacked packages. The backing VHDX can grow as writes occur; deleting package archives later does not itself prove that Windows has reclaimed the same host disk space.

If Ubuntu indicates a restart is needed, capture that state and follow a deliberate WSL stop/relaunch procedure. WSL is not a separate physical Linux machine with an independent firmware reboot; use Microsoft’s documented wsl --terminate <Distro> or wsl --shutdown host commands as appropriate, understanding that shutdown stops every running distribution. Relaunch the named distro and verify the pending-restart condition is resolved before continuing. If the release upgrader requires reboot behavior the installed WSL configuration cannot satisfy, stop and use a supported Ubuntu VM or machine rather than improvising around the upgrader.

Run the interactive release upgrade

Ubuntu recommends do-release-upgrade for Server editions and cloud images because it can handle configuration changes needed between releases. Its interactive summary lists package removals, additions, downloads, and unsupported packages before the operation proceeds. In WSL, plan to stay at the console for the entire upgrade and do not put it in a detached shell that may be terminated by WSL lifecycle events.

sudo do-release-upgrade

Read the preflight summary before confirming. During the operation, package configuration prompts may ask whether to keep a locally modified file or install the distributor’s version. Inspect the diff and decide per file; there is no universally safe “always keep” or “always replace” answer. Preserve the transcript and the final summary. Do not close the Windows terminal, run wsl --shutdown, or reboot Windows while package unpacking and configuration are in progress.

If the upgrader says no new release is available, first confirm the current source release, update channel, upgrade policy, architecture, and release notes. Do not rewrite /etc/apt/sources.list or deb822 source files by substituting release names manually; doing so bypasses release-specific transitions and can create a mixed package universe. Do not launch a second upgrader after an interrupted run until you have inspected dpkg/apt state and followed Ubuntu’s recovery guidance.

Complete the WSL lifecycle and verify the userspace

After the upgrader reaches its completed state, capture any instruction about restarting. From PowerShell, terminate only the upgraded distro when possible; reserve wsl --shutdown for cases where a full WSL VM restart is actually needed because it stops every running distro:

wsl.exe --terminate Ubuntu-Dev
wsl.exe --distribution Ubuntu-Dev --exec sh -lc 'cat /etc/os-release; dpkg --audit'

Run a package repair command only if the package manager indicates it is needed and after consulting Ubuntu’s recovery guidance; dpkg --configure -a is a repair action and should not be blindly executed as a routine success step. Verify the release identifier, package database health, and configured repositories. Then run sudo apt update, inspect apt list --upgradable, and review systemctl --failed if systemd is enabled. An empty failed-unit list is not by itself proof that your applications are healthy.

Test the real workload: launch each required service, validate database integrity and recovery, execute representative builds and tests, check DNS and network access, verify Windows interop, test mounted filesystems, and confirm any scheduled jobs. Validate after both a distro terminate/relaunch and a Windows reboot if that transition is part of the environment’s normal lifecycle. Compare the final package/repository inventory against the pre-upgrade record, paying special attention to disabled PPAs, third-party agents, and manually installed binaries.

Recover without destroying the only copy

If the distribution will not start or the workload fails, do not immediately unregister it. Preserve command output, WSL and Ubuntu version data, and logs. Keep the failed distro intact for diagnosis, then import the pre-upgrade archive under a different registration and compare expected files and application state. Restore databases with their own recovery checks. Only after the restore is proven should you decide whether to retry the upgrade on a clone, repair the existing distro, or return to the old release.

The acceptance record should include the source/target Ubuntu releases, supported upgrade route, WSL package and distro mode, export path and hash, package plan, PPA/repository actions, restart steps, and workload test results. This makes the upgrade reproducible and makes “roll back” mean a tested operation rather than a hopeful copy of a VHDX.

Related:

Sources: