pxlrbt/move-wsl: Moving WSL Distro Storage with PowerShell

What move-wsl Changes in WSL Storage

move-wsl addresses a specific storage problem in Windows Subsystem for Linux: a distribution's VHDX file is stored in a location that the user wants to change. The repository describes the script as a way to move WSL 1 and WSL 2 distribution VHDX files to a different location. That target is commonly presented as a folder on another Windows drive, although the project does not prescribe a particular drive or filesystem.

The intended users are people who manage WSL themselves and already understand the distribution name and intended destination. The CLI mode is suitable for repeatable administration, while the interactive mode asks the operator to choose a distribution, enter a target path, and confirm the operation. The README does not describe a Windows Store installation package, module, or supported deployment image. The repository is a single PowerShell script, `move-wsl.ps1`, supported by release notes and workflow files at the top level.

move-wsl Interactive and CLI Workflows

The documented workflow has two entry paths. Running the script without parameters opens the interactive process. According to the README, the operator selects a distribution, enters a destination such as `D:\wsl\ubuntu`, and confirms the move. The destination is a folder path, not a VHDX filename supplied by the user.

The script also exposes `-Distro`, `-Target`, `-Force`, and `-NoShutdown`. `-Force` skips confirmation prompts and the NTFS compression warning, while `-NoShutdown` disables automatic WSL shutdown. The README explicitly marks the latter as not recommended because WSL processes can keep files locked. Automatic shutdown is therefore part of the normal path rather than an optional preparation step.

Based on the repository description, the script works with official `wsl` commands and registers the distribution again after its image is relocated. The README says that imported distributions retain their original WSL version and that version 1.4.0 added preservation of the default distro setting. The repository entry list exposes only `move-wsl.ps1`, so the article does not assume additional internal modules or a background service.

Running move-wsl and Moving an Ubuntu Distribution

The README does not provide installation through a package manager or PowerShell Gallery. It directs users to the repository script, so run `move-wsl.ps1` from a local checkout. The basic command asks the script to move the named distribution to the specified directory. The operator should see a confirmation prompt unless `-Force` is used.

./move-wsl.ps1 -Distro "Ubuntu" -Target "D:\wsl\ubuntu"

For a non-confirmed administrative invocation, the documented `-Force` option skips confirmation prompts and the NTFS compression warning. That warning exists because the README says compressed folders can corrupt WSL images, so using `-Force` removes a safety signal rather than fixing the filesystem condition.

./move-wsl.ps1 -Distro "Ubuntu" -Target "D:\wsl\ubuntu" -Force

Before either command, back up important distro data, close applications that use WSL, and stop Docker Desktop when its WSL distribution is involved. The destination parent may need to exist, but the README does not state whether the script creates it.

Execution Policy and WSL Command-Line Recovery

A PowerShell download or policy configuration can prevent local scripts from loading. The README gives a process-scoped bypass followed by execution. This changes the execution policy only for the current PowerShell process according to the command's documented scope.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
./move-wsl.ps1

The README also documents commands for repairing state after a move. If the default user changes to root, users can add a `[user]` section with `default=YOUR_USERNAME` to `/etc/wsl.conf`, exit the distribution, terminate it, and start it again. Some distributions expose the distribution-specific command shown in the project documentation.

[user]
default=YOUR_USERNAME

ubuntu config --default-user johndoe

For version drift, the documented recovery command sets a named distribution to a selected WSL version. The angle-bracket values in the README are placeholders, not literal command arguments.

wsl --set-version <Distro> <Version>

NTFS Compression, File Locks, and Docker Constraints

The destination filesystem is a hard boundary for this project. move-wsl checks whether the target folder has NTFS compression enabled because the README warns that compressed folders can corrupt WSL images. The documented remedy is to open the target folder's properties, select Advanced, and clear `Compress contents to save disk space`. The script does not document an automatic compression change, so the operator must inspect the destination before relying on the move.

File locking is the other operational constraint. Automatic WSL shutdown is enabled in the normal path to prevent locks, while `-NoShutdown` bypasses that protection. Close all applications that use WSL first. For Docker-backed WSL distributions, the README requires Docker Desktop to be stopped completely and gives an additional instruction to wait a few seconds for its processes to terminate. It does not claim that moving every Docker WSL layout is supported without additional steps.

The project also asks for a backup but does not publish a rollback command or document how to recover automatically from a failed import. A failure between image movement and registration could therefore require operator intervention. The lack of documented rollback is a meaningful limitation for infrastructure changes.

move-wsl Versus Leaving WSL Storage Unchanged

The practical alternative is to leave the distribution in its existing WSL-managed storage location. That avoids unregistering and importing the distribution, but it does not solve the project's stated goal of placing the VHDX on a chosen Windows path. move-wsl adds value only when the distribution must actually move.

A second alternative is to implement the same relocation manually with official `wsl` commands. The project itself says that it uses official commands, so it is not introducing a separate WSL virtualization layer. Its contribution is packaging distro selection, destination input, shutdown handling, NTFS compression checks, confirmation, and default-distro preservation into `move-wsl.ps1`. An administrator who already has a tested internal procedure may prefer that procedure because it can match local backup and validation requirements, although the repository does not document the exact manual command sequence.

This comparison matters because move-wsl is a focused administrative script, not a general migration system. The README provides no multi-distro transaction, scheduling service, progress API, or rollback documentation.

Maintenance History and GPL-3.0 Implications

The repository is not archived, and its last push was on 2026-09-11. That indicates repository activity, but it does not establish compatibility with every current WSL release. The listed release history is older: version 1.4.0 was released on 2022-04-24, version 1.3.2 on 2020-09-09, and version 1.3.1 on 2020-08-09. This gap makes validation against the intended Windows and WSL environment important, especially because the documentation does not state a current compatibility matrix.

Upgrade cost appears concentrated in a single PowerShell file rather than a documented service deployment. Users still need to review `CHANGELOG.md` and the script before adopting a newer version because the repository gives no automated migration or rollback procedure. The project is licensed under GPL-3.0, and the README directs readers to the `LICENSE` file. Users distributing a modified copy or incorporating the licensed code must review those license obligations separately, without treating this article as legal advice.

Editorial conclusion

move-wsl suits Windows administrators and developers who need a specific WSL distribution on another drive and can first verify the destination, backup its contents, and restore the expected default user and distro settings. It is a poor fit for users who need a guided export and import workflow, live migration, or evidence that this script safely handles a particular Docker-backed distribution. Before adoption, check the destination filesystem for NTFS compression, confirm that relevant WSL and Docker processes are stopped, and verify the default user after the move because the project documents that this setting can otherwise revert to root.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. pxlrbt/move-wsl on GitHub
4. README
5. Releases