A Safe WSL 1 to WSL 2 Conversion and Migration Runbook

Changing a distribution from WSL 1 to WSL 2 is an architecture migration, not a cosmetic setting. wsl --set-version targets one registered distribution and can take time or fail; Microsoft explicitly recommends backing up distributions with large projects before conversion. The safe operational question is therefore not just whether WSL 2 is the default, but whether this workload benefits from a real Linux kernel and virtualized filesystem enough to justify its different compatibility and file-placement behavior.

This runbook treats conversion as a controlled change: establish the current state, choose a target per workload, create a recoverable backup, convert a non-critical distribution first, validate the actual application path, and retain the old export until a restore has been demonstrated.

Decide by workload, not by machine-wide preference

WSL 1 uses a compatibility layer that translates Linux system calls. WSL 2 runs a Linux kernel in a managed utility virtual machine and provides broader system-call compatibility. That makes WSL 2 a strong fit for workloads that need kernel behavior, but not an automatic performance win for every access pattern. Microsoft documents faster access to files stored on the same operating system as the tools using them; cross-filesystem work can favor WSL 1 in specific workflows.

Workload constraint	Starting point	What to verify
Linux-native build tree, containers, kernel-dependent software, or Linux services	Evaluate WSL 2	Keep source and build output in the Linux filesystem; test required kernel features and integrations.
Linux tools must repeatedly traverse files under `/mnt/c`, or Windows and Linux tools edit the same tree	Compare WSL 1 and WSL 2 with the real workload	Measure the same commands and file tree. Avoid extrapolating from synthetic disk benchmarks.
Existing automation relies on a specific network or device behavior	Preserve current mode until tested	Check the exact networking, serial, USB, and filesystem requirements against Microsoft’s comparison guide.

Do not conflate choosing a default with converting installed distros. wsl --set-default-version 2 changes the default version for future installations; it does not migrate distributions already listed by WSL. Conversely, wsl --set-version Ubuntu 2 targets the named registered distribution. Keeping those scopes separate prevents an administrator from believing that existing environments have changed when only the future-install default moved.

Record the baseline and identify the exact registration

Run these commands in an elevated or ordinary PowerShell session as appropriate for your environment. Use the registered name exactly as wsl --list --verbose prints it; do not assume a Store display name, a folder name, or a Terminal profile is the registration name.

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

Record the Windows edition/build (winver), WSL package/version output, distro name, current WSL version, running state, Linux release, kernel version, default user, and any workload-specific integrations. Windows 10 support for WSL 2 has a minimum build documented by Microsoft; if the feature is unavailable, check the exact host build and current installation channel rather than repeatedly retrying conversion.

Inside the target distro, save a short inventory with its normal user:

cat /etc/os-release
uname -r
id
findmnt
df -h /

Add the application-specific checks that matter: package database status, service health, database recovery state, container image/volume inventory, mounted data, network endpoints, scheduled jobs, and required kernel interfaces. A successful conversion command alone is not a workload acceptance test.

Make a recoverable backup before changing architecture

Stop write-heavy applications cleanly first. A database directory copied while the database is live may not represent a consistent recovery point. Then terminate the target distro and export it to a protected location with sufficient free space:

wsl.exe --terminate Ubuntu-Dev
New-Item -ItemType Directory -Force -Path D:\WSL-Backups | Out-Null
wsl.exe --export Ubuntu-Dev D:\WSL-Backups\Ubuntu-Dev-before-wsl2.tar
Get-FileHash D:\WSL-Backups\Ubuntu-Dev-before-wsl2.tar -Algorithm SHA256

Protect the archive as an image of the Linux account: it can contain credentials, private keys, tokens, shell history, and application data. Store it with access controls and encryption appropriate to that material. A hash checks that the archive you later read matches the file you produced; it does not prove that the distro can be restored. For a consequential environment, import the archive under a temporary, unique name on a test host and validate it before the production conversion window.

Inventory data outside the distribution as well. Windows-mounted files, separately attached VHDs, network shares, Windows Terminal profiles, host-side integrations, and credentials managed by Windows may not be represented by the distro export. Back them up or document their reconstruction independently.

Convert one distribution and capture the result

Schedule a window in which the target distro can be unavailable. Make sure package managers and services are stopped, close shells and editors connected to the distro, and verify that the backup is complete. Convert only the named distribution:

wsl.exe --set-version Ubuntu-Dev 2
wsl.exe --list --verbose

For a very large filesystem the conversion may take a long time. Do not terminate PowerShell or reboot merely because progress is not visible. If the command reports failure, preserve its complete error text, inspect available disk space and host prerequisites, and do not unregister the source as a cleanup attempt. Microsoft warns that conversion can fail because WSL 1 and WSL 2 have architectural differences, which is why the independent backup and restore path matter.

Changing an existing registration does not mean every integration has moved with it. Recheck scripts that name the distro, filesystem assumptions, service startup, host-to-guest networking, and any Windows tools that access its files. Keep the distro name stable unless renaming is an intentional, separately tested change.

Validate behavior, not just the version column

Confirm the registration is now WSL 2, then run the original workload checks under the original Linux user:

wsl.exe --list --verbose
wsl.exe --distribution Ubuntu-Dev --user dev --exec sh -lc "id && uname -r && findmnt && df -h /"

The quoted command runs a short Linux shell for inspection; replace dev with a user that exists in the distribution. Validate package operations, required system calls, systemd behavior if used, container runtime, mounted data, DNS and network paths, Windows interop, GUI or GPU paths when relevant, and representative build/test jobs. Test files where the tools actually keep them. A benchmark against /mnt/c does not characterize a project moved to the Linux filesystem, and a smoke test that touches only /home does not validate a Windows-shared tree.

Define acceptance before conversion. Useful gates include: all expected services become healthy; a representative build completes; test suites pass; database integrity/recovery checks succeed; expected ports are reachable from their intended side; and Windows/Linux clients can read and write only the paths they are supposed to share. Compare timings on the same host with repeatable inputs, but do not let a faster benchmark override a broken functional requirement.

Rollback without destroying evidence

If the workload fails acceptance, collect logs and preserve the converted distro for diagnosis. The conversion command accepts version 1 or 2, so a supported rollback attempt can target the same named registration:

wsl.exe --set-version Ubuntu-Dev 1
wsl.exe --list --verbose

Treat reconversion as another architecture migration, not a guaranteed undo button. It can also take time or fail. If the distro has changed materially since the export, restore the backup under a new registration and test it before deciding which copy to retain. Never run wsl --unregister on the only known-good copy; Microsoft documents that unregistering permanently removes that distribution’s data, settings, and software.

Close the change with a reproducible record

Save the before/after WSL version output, Windows build, backup path and hash, command transcript, conversion duration, application acceptance results, known exceptions, and final rollback decision. Update provisioning automation only after the converted workload passes its tests. If a fleet needs WSL 2 for new installations, changing the default is a separate policy decision with its own rollout plan; it does not substitute for migrating the existing registrations.

The practical success criterion is not “the distro says version 2.” It is “the named workload runs correctly on the intended filesystem and integration paths, its recovery point is verified, and an operator can explain exactly how to restore or roll back without deleting the only copy.”

Related:

Sources: