Move an Existing WSL Distribution with wsl --manage --move

An installed WSL distribution may need to move from a nearly full system drive to a larger volume. On current WSL implementations, the management command supports wsl --manage <Distribution> --move <Location>, which asks WSL to relocate the distribution instead of manually editing registry paths or copying a live VHDX. The CLI option is visible in Microsoft’s WSL source, though the general Learn command page may lag behind current command additions. Use wsl --help on the target machine to confirm availability, keep an independent backup, and treat the relocation as a storage operation with an outage and acceptance test.

Distinguish moving from changing the default install directory

distributionInstallPath in .wslconfig sets a default location for newly installed distributions. It does not move an existing installation. A move operation changes where a registered distribution’s files are stored while retaining its registration identity. Export/import is an alternate migration path that creates a separate registration at a chosen destination; it has different metadata and default-user considerations. Avoid mixing those workflows or assuming a future-install setting affects already registered distros.

The exact --manage --move syntax is present in the current Microsoft WSL command-line implementation. Before relying on it in production, run wsl.exe --help and inspect the installed WSL version. If the command is unavailable, update WSL through the approved channel or use the documented export/import process with a tested backup and explicit acceptance steps. Do not substitute manual registry edits or move an ext4.vhdx while WSL owns it.

Prepare a safe maintenance window

Inventory the registered distros and versions, confirm the exact distribution name, inspect the destination volume, and create a restorable backup. wsl --export is one supported way to create a distro archive, but it must be treated as a backup only after the archive is readable and a test restore has been considered. If the distro contains databases, stop or quiesce them cleanly before export. An untested archive on the same volume as the source is not sufficient protection against volume failure.

Check the destination path carefully. It should be an absolute Windows path on a fixed volume that remains mounted, has sufficient free capacity, and complies with the device’s backup and encryption policy. Confirm the Windows account that owns the distro can access the destination. Avoid network shares, removable media, cloud-sync folders, and directories controlled by cleanup utilities unless the exact WSL runtime and storage behavior have been validated for that target.

Record the current configuration and application acceptance checks:

wsl.exe --version
wsl.exe --list --verbose
wsl.exe --distribution Ubuntu --exec /bin/sh -lc 'id; cat /etc/os-release'

The distro name in the example is illustrative. Use the exact name reported by wsl --list --verbose. Capture the expected Linux default user, important mount points, service health, local development tools, and a small set of representative files. This provides a comparison after relocation.

Stop writers and move through the WSL manager

Before moving, stop databases, containers, IDE integrations, and other processes that can write into the distro. If the distribution is running as a local service, drain or stop clients first. Then stop all WSL instances cleanly:

wsl.exe --shutdown
wsl.exe --manage Ubuntu --move "D:\\WSL\\Ubuntu"

The command shown is an example; replace the distribution and destination with reviewed values. The --shutdown command affects all running distributions, not just Ubuntu. The move operation is not a substitute for application-aware quiescing or a backup. Ensure there are no active WSL clients holding files open before it begins.

Use only the WSL management command for the relocation. Do not manually copy the VHDX and change registry values based on a forum recipe. WSL registration includes metadata beyond a single visible disk file, and manually editing the backing path can leave the registration inconsistent or the original and copy ambiguous. Do not run the move concurrently with another WSL manage, export, import, repair, compact, or resize operation on that distro.

If the command returns an error, preserve the exact output and WSL version. Do not repeatedly retry while unsure whether the operation is still active. Check wsl --list --verbose, inspect source and destination paths using read-only host tools, and confirm which registration can start. Keep the source backup and avoid deleting either copy until acceptance is complete.

Verify more than the command’s exit status

After the move completes, list distributions, launch the selected distro, and rerun the baseline checks. Validate:

The same distro name and WSL version are registered.
The expected Linux default user and /etc/os-release remain intact.
Important files, ownership, executable bits, symlinks, and case-sensitive paths remain usable.
/etc/fstab, automount behavior, systemd units, DNS, networking, and Windows interop behave as before.
Required containers and databases start and pass their own health checks.
The destination volume has adequate free space and the source location is not mistakenly treated as the active copy.

Use a small checksum set for important files rather than relying on directory listing alone. For a data service, perform an application-level read/write test on disposable or approved test data. A successful Linux shell only proves that the distro launches; it does not prove every workload’s state or performance survived.

From Windows, confirm the destination folder has a WSL-managed backing file and that its size changes as expected after a controlled guest write, if that is part of the validation plan. Do not edit or rename that VHDX. A move changes file placement, not the VHD’s logical capacity or the dynamic allocation policy. If the reason for moving was lack of space inside the guest, use the documented resize or cleanup procedure separately.

Handle fallback migration without risking the source

If --manage --move is not recognized by the installed version, first verify whether an approved WSL update makes the command available. Otherwise, use Microsoft’s documented export/import workflow under a new temporary distro name and path. Keep the original registered distro until the import passes all tests. Export/import can require re-establishing default user and integrations, so validate those explicitly. Only after a tested backup and a successful acceptance of the replacement should an operator consider unregistering the old distro; unregistering deletes its registered data and is not a rollback button.

Do not use --unregister as a shortcut to free the source storage until the new distro is independently verified and backed up. A move that fails halfway, a filesystem issue, or an unexpected default-user change can turn a routine capacity task into data loss if the only copy is removed prematurely.

Change record and acceptance gate

Record the source and destination paths, distro name, host volume identifiers, WSL package version, backup path/hash, shutdown window, exact command, exit status, and the post-move checks. Monitor free host storage at the destination because the VHD can grow dynamically. Document which team owns future backups and volume monitoring.

The relocation is complete only when the target registration starts from the intended location, user data and ownership match the baseline, critical services pass application-level checks, the destination volume has a sustainable capacity margin, and a usable backup exists. Keep the source copy until those conditions are met. This operational gate is what makes a supported move command safer than an undocumented file copy.

Performance and durability considerations

Moving a distro to another volume changes its storage placement, so performance may also change. A slower USB device, encrypted volume, heavily contended disk, or endpoint-scanned directory can make package operations and database I/O behave differently even when every file is intact. Measure representative file and application operations before and after the move if latency is a requirement. Do not infer storage quality from the volume’s advertised interface speed alone; Windows policy, filesystem, encryption, and concurrent host workloads affect the path.

The destination also becomes part of the distribution’s availability design. If the volume is disconnected, assigned a different mount point, or unavailable during Windows startup, WSL may be unable to launch that distro. For portable devices or multi-user machines, document that dependency and test the expected failure state. Keep independent backups on a different failure domain rather than treating a second folder on the same destination volume as disaster recovery.

Keep automation idempotent and guarded

If a team automates relocation, require an explicit distro name and destination, verify that the command exists before proceeding, and refuse to run if a WSL workload is active or the backup is missing. Log the WSL version, command result, and post-move checks without storing secrets. Avoid scripts that discover a VHDX by recursive search and relocate it directly; multiple matching disks can belong to Docker Desktop, another distro, or a backup, and filename alone is not identity.

After a successful move, re-run the move procedure only when the next target is clearly different and the current distribution has a fresh backup. Do not make cleanup automation delete the source folder based only on a zero exit code. Require an independent start-and-health acceptance result and an explicit retention period before removing stale copies. This makes the storage change reversible even when a user or orchestration layer reports completion too early.

Related:

Sources: