PWSL

PowerShell Windows Subsystem for Linux

---

A wrapper for wsl.exe. It parses WSL output into standard PowerShell objects, provides safety checks for destructive operations, and automates the migration of distributions between drives.

🚨 Requirement: Windows 10/11 with WSL enabled.

Function Reference ♾️ PSGallery ♾️ Chocolatey ♾️ GitHub

Installation

Installing pwsl is available via the package repositories: PSGallery, Chocolatey and GitLab.

▓▓▓▓▒▒▒▒░░░	▓▓▓▓▒▒▒▒░░░	▓▓▓▓▒▒▒▒░░░
📦 PSGallery
📦 Chocolatey

Additinonal Installation Options:

▓▓▓▓▒▒▒▒░░░	▓▓▓▓▒▒▒▒░░░	▓▓▓▓▒▒▒▒░░░
💼 Releases/Tags

GitLab Packages

Using nuget: See the packages page for installation instructions.

For instructions on adding nuget sources packages from GitLab see Releases artifacts or via the Packages page.

Generic Package Registry

The latest release artifacts can be downloaded from the Generic Assets Artifacts page.

Git

# Clone the repository
git clone https://gitlab.com/phellams/pwsl.git
cd pwsl
import-module .\

Core Features

🔸 Object-Oriented Output

Standard wsl --list returns raw text (often with encoding issues). PWSL returns PowerShell objects.

$distros = Get-PwslList
$distros | Where-Object { $_.State -eq 'Running' }

🔸 Moving Distributions

Move-PwslDistro automates the manual Export -> Unregister -> Import workflow.

Logic Handled:

1. Stops the running distro.
2. Exports to a temporary location (with file size safety checks).
3. Unregisters (deletes) the original only if the backup is valid.
4. Imports to the new destination.
5. Restores Default User: Injects /etc/wsl.conf so you don't log in as root by default.

# Move Ubuntu to D: drive and set as default
Move-PwslDistro -Name "Ubuntu-24.04" -NewLocation "D:\WSL\Ubuntu" -SetAsDefault

🔸⚠️ Important: Moving & Users

When a distro is imported, WSL defaults the user to root. This script attempts to ask for your username and write it to /etc/wsl.conf automatically. If this fails, you will log in as root.

To fix manually inside the distro:

# Inside WSL
echo -e "[user]\ndefault=your_username" >> /etc/wsl.conf

🔸 Argument Completion

The module registers a tab-completer. You can press [TAB] to cycle through installed distro names for commands like Stop-, Move-, or Enter-.

Command Reference

General

Command	Description
Get-PwslList	Returns object list of installed distros (Name, State, Version).
Get-PwslRunning	Returns only running distros.
Get-PwslAvailable	Lists distros available for download (wsl --list --online).
Enter-PwslDistro	Enters the shell of a specific distro (wsl -d).

Lifecycle

Command	Description
Install-PwslDistro	Installs a new distro from the online list.
Stop-PwslDistro	Terminates a running instance immediately.
Register-PwslDistro	Alias for Import. Registers a custom rootfs.
Unregister-PwslDistro	⚠️ Destructive. Deletes the distro and virtual disk.

Migration / Backup

Command	Description
Move-PwslDistro	Safely moves a distro to a new path.
Export-PwslDistro	Exports rootfs to a .tar file.
Import-PwslDistro	Imports a .tar file as a new distro.

Examples

Install and Setup

# Check what is available
Get-PwslAvailable

# Install
Install-PwslDistro -Name "Debian"

# install in a specific location
# Note: Move-Pwsldistro will be called to perform move steps and will take addtional time
# Note: Default user must be the same as the one you specify during intereactive installation
Install-PwslDistro -Name "Debian" -InstallLocation "C:\WSL\Debian"

Backup and res

# Create a snapshot
Export-PwslDistro -Name "Debian" -Path "C:\Backups\debian-snap.tar"

# Restore as a separate instance for testing
Import-PwslDistro -Name "Debian-Test" -InstallLocation "C:\WSL\Test" -SourceTar "C:\Backups\debian-snap.tar"

Relocation

# Move to a different drive
Get-PwslList

# Default temp location is C:\Users\gsnow\AppData\Local\Temp
Move-PwslDistro -Name "Debian" -NewLocation "G:\WSL\Debian" -defaultUser "username"

# custom temp location
Move-PwslDistro -Name "Debian" -NewLocation "G:\WSL\Debian" -TempLocation "G:\Backups" -defaultUser "username"

Roadmap

• The ability to enable and disble wsl via powershell
• The ability to list distro versions and perhaps install previous version if the need is there
• complete phwriter help metadata for accurate help output

Contributing

Contributions are welcome! Please fork the repository and submit a Merge Request (MR) targeting the develop branch.

1. Fork the Project Click the "Fork" button in the top right corner of the repository page.

2. Clone your Fork

   git clone [https://gitlab.com/YOUR_USERNAME/pwsl.git](https://gitlab.com/YOUR_USERNAME/pwsl.git)
   cd pwslmerge_requests/new)

3. Create a Feature Branch Ensure you base your work on the develop branch:

   git switch develop
   git switch -c feature/AmazingFeature

4. Commit your Changes

   git commit -m 'feat: Add some AmazingFeature'

5. Push to the Branch

   git push origin feature/AmazingFeature

6. Open a Merge Request

   

   https://gitlab.com/phellams/pwsl/-/merge_requests/new

Acknowledgments

• @wsl - Windows Subsystem for Linux (WSL) lets developers run a GNU/Linux environment inside a Windows environment.
• @shields.io - Shields.io provides a service to generate badges and other visual elements for your projects.

License

This module is released under the MIT License.