WSL 3.0 is out for all users, and the version bump is not the interesting part: this branch can run Linux containers, which is a new capability for the Windows Subsystem for Linux. I moved a working WSL 2 machine to the 3.x package on Windows 11 x64 and kept notes on the order that worked, the checks that caught problems early, and the two details the release material simply does not confirm.

Budget 25–35 minutes. Nothing here is exotic, but the steps are order-dependent, and skipping the backup is the one shortcut I would not take.

What the release does and does not confirm

Confirmed: Microsoft has published WSL 3.0, the release is available to everyone rather than as a limited preview, and containers are new to WSL in this release. A container, in plain terms, is an isolated way to run an application together with its dependencies.

Not confirmed: an exact release date, and the build string 3.0.3.0 that circulates in download posts. The announcement I worked from names neither. So the only build number worth trusting is the one your own machine prints:

wsl --version

Cross-check that value against the official release notes instead of a third-party page.

Prerequisites worth checking first

  • Windows 11 on x64 hardware.
  • Virtualization (Intel VT-x or AMD-V) enabled in UEFI/BIOS. Without it the WSL 2/3 utility VM cannot start.
  • The Virtual Machine Platform and Windows Subsystem for Linux optional features enabled.
  • One existing WSL 2 distribution — mine was Ubuntu — so you have something to launch and test afterwards.
  • One elevated PowerShell session (7 or 5.1).
  • At least 5 GB free on the system drive, plus room for an exported backup.

For context, WSL is the Windows feature that runs Linux binaries on top of a real Linux kernel inside a lightweight VM. The update replaces a package; it does not reinstall Windows.

Step 1: take inventory and export a backup

Before changing anything, record the current state and export one distribution to a .tar file. Run this in an administrator PowerShell:

wsl --version wsl --status wsl --list --verbose Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform | Select-Object FeatureName, State Get-CimInstance Win32_Processor | Select-Object Name, VirtualizationFirmwareEnabled Get-PSDrive C | Select-Object Used, Free

Then export, replacing the distro name and the target folder with your own:

New-Item -ItemType Directory -Force -Path D:\wsl-backup | Out-Null wsl --export Ubuntu "D:\wsl-backup\ubuntu-$(Get-Date -Format yyyyMMdd).tar"

On a healthy install, wsl --list --verbose prints a header and one line per distro, and the VERSION column reads 2 — meaning the distro runs on the WSL 2 architecture. wsl --version prints a small block of fields; the first one tells you which branch of the package is answering wsl.exe.

Do not continue until this list is fully ticked:

  • [ ] wsl --version prints a WSL version line starting with 2. (or 3. if you are already updated)
  • [ ] VirtualMachinePlatform state is Enabled
  • [ ] VirtualizationFirmwareEnabled is True
  • [ ] wsl --list --verbose lists at least one distribution
  • [ ] Get-PSDrive C shows more than 5 GB of free space
  • [ ] the .tar backup file exists on disk

If VirtualizationFirmwareEnabled is False, stop here and turn on VT-x/AMD-V in UEFI before going further.

Step 2: swap the package to the 3.x branch

Shut everything down first, then update:

wsl --shutdown wsl --update wsl --version wsl --help

The shutdown matters: a running utility VM keeps the old files locked, so the package swap can fail or appear to succeed without taking effect.

If wsl --update errors out because the Store or Windows Update endpoint is unreachable, use the direct download path — but confirm the flag exists in your build first:

wsl --help | Select-String -Pattern "web-download" wsl --update --web-download

Next, check which values your build accepts for the default version, and set it to 3 only if 3 is actually listed:

wsl --help | Select-String -Pattern "set-default-version" wsl --set-default-version 3

A successful update ends with a short progress indicator and a line saying the update was installed; afterwards wsl --version should report WSL version: 3.<minor>.<build>.<revision>. If the first field still starts with 2., the old inbox component is still the one answering — see Troubleshooting.

One caveat about --set-default-version: it affects only new distributions. Existing distros keep the version recorded for them until you convert them, and the release material does not describe a forced per-distribution migration. Read the release notes before converting anything you care about.

Step 3: prove the update actually took

A version string alone proves a package was replaced — nothing more. Verify three separate things: the new build answers, a distro boots on the new kernel, and the container capability is present in the binary you run.

wsl --version wsl --help | Select-String -Pattern "container" wsl -d Ubuntu -- uname -r wsl -d Ubuntu -- sh -c "curl -s -o /dev/null -w '%{http_code}\n' https://example.com"

Expected results: uname -r prints a kernel release string such as 6.6.x.x-1, and the curl line prints exactly 200, which means DNS and outbound HTTPS work from inside the distro. If the container search returns nothing, your wsl.exe is still the pre-3.0 build.

Check Command Pass condition
Build branch wsl --version first line starts with 3.
Distro state wsl --list --verbose your distro listed, no error
Kernel wsl -d Ubuntu -- uname -r a kernel release string is printed
Network curl ... https://example.com 200
Container support `wsl --help \ Select-String container`

About the container run itself: the release material confirms the capability but does not name the subcommand. Take the exact syntax from wsl --help on your own build or from the official docs. Pasting a container command from a blog post into an elevated shell, without first confirming it appears in your help output, is how people end up debugging something unrelated at 1 a.m.

Troubleshooting

wsl --update fails immediately with a network error. This is usually the Store or Windows Update endpoint being unreachable rather than a broken install. Search your help output for the web-download flag, confirm it exists, and retry the update through it as shown in step 2.

wsl --version still reports 2.x after a seemingly successful update. The old component is still answering. Run wsl --shutdown again, confirm the Store access or the direct download path works, and re-run the update. Verify with wsl --version before changing any default-version setting.

A distro no longer starts after the update. This is exactly what the .tar export in step 1 is for; import it back rather than rebuilding the environment from memory.

A build number looks wrong. Re-read it from wsl --version and compare it with the release notes. Do not treat a number you saw in a download post as ground truth.

If you want the long-form version of these notes, the original write-up lives on AI Release — https://ai-release.org — and short release notes for this kind of tooling land in the Telegram channel https://t.me/ai_release1.

Takeaways

  • Confirm the branch on your own machine with wsl --version; treat the specific build string and release date in download posts as unverified until the release notes agree.
  • Export a distro to .tar before touching the package. It costs a minute and it is your only rollback.
  • wsl --shutdown is not optional before --update, and --set-default-version only affects new distros.
  • Version strings prove nothing on their own — a kernel check, a curl returning 200, and a help search for the container feature together prove the upgrade is real.