Wsl-Manager is a Powershell cmdlet to quickly create a minimal WSL distribution. Currently, it can create a WSL distribution based on the following Linux distros:
- Archlinux (2024.04.01)
- Alpine (3.19)
- Ubuntu (24.04)
- Debian (bookworm)
- Any Incus available distribution (list)
It is available in PowerShell Gallery as the
Wsl-Manager
module.
Extended information is available in the project documentation.
Windows is a great development platform for Linux based backend services through Visual Studio Code and WSL.
However, using a single Linux distrbution is unpratictal as it tends to get bloated and becomes difficult to recreate if configured manually.
It is much better to use a distribution per development envinronment given that the performance overhead is low.
Creating a WSL distribution from a Linux distro Root filesystem (Ubuntu, Arch, Alpine) is relatively easy but can rapidely become a tedious task.
The Wsl-Manager
module streamlines that.
This module provides a cmdlet called Install-Wsl
that will install a
lightweight Windows Subsystem for Linux (WSL) distribution.
The installed distribution is configured as follows:
- A user named after the type of distribution (
arch
,alpine
orubuntu
) is set as the default user. The user assudo
(doas
on Alpine) privileges. - zsh with oh-my-zsh is used as shell.
- powerlevel10k is set as the default oh-my-zsh theme.
- zsh-autosuggestions plugin is installed.
- The wsl2-ssh-pageant plugin is installed in order to use the GPG private keys available at the Windows level both for SSH and GPG (I personally use a Yubikey).
You can install an already configured distribution (-Configured
flag) or start
from the official root filesystem and perform the configuration locally on the
newly created distrbution.
The root filesystems from which the WSL distributions are created are cached in
the %LOCALAPPDATA%\Wsl\RootFS
directory when downloaded and reused for further
creations.
By default, each created WSL distribution home folder (where the ext4.vhdx
virtual filesystem file is located) is located in %LOCALAPPDATA%\Wsl
WSL 2 needs to be installed and working. If you are on Windows 11, a simple
wsl --install
should get you going.
To install this module, you need to be started with the PowerShell Gallery.
The WSL distribution uses a fancy zsh theme called
powerlevel10k. To work properly in
the default configuration, you need a Nerd Font.
My personal advice is to use Ubuntu Mono NF
available via scoop in
the nerds font bucket:
❯ scoop bucket add nerd-fonts
❯ scoop install UbuntuMono-NF-Mono
The font name is then 'UbuntuMono NF'
(for vscode, Windows Terminal...).
Install the module with:
❯ Install-Module -Name Wsl-Manager
And then create a WSL distribution with:
❯ Install-Wsl Arch -Distribution Arch
####> Creating directory [C:\Users\AntoineMartin\AppData\Local\Wsl\dev]...
####> Downloading https://github.com/antoinemartin/PowerShell-Wsl-Manager/releases/download/2022.11.01/archlinux.rootfs.tar.gz → C:\Users\AntoineMartin\AppData\Local\Wsl\RootFS\arch.rootfs.tar.gz...
####> Creating distribution [dev]...
####> Running initialization script [configure.sh] on distribution [dev]...
####> Done. Command to enter distribution: wsl -d dev
❯
To uninstall the distribution, just type:
❯ Uninstall-Wsl dev
❯
It will remove the distrbution and wipe the directory completely.
Configuration implies installing some packages. To avoid the time taken to download and install such packages, Already configured root filesystems files are made available on github.
You can install an already configured distrbution by adding the -Configured
switch:
❯ install-wsl test2 -Distribution Alpine -Configured
####> Creating directory [C:\Users\AntoineMartin\AppData\Local\Wsl\test2]...
####> Downloading https://github.com/antoinemartin/PowerShell-Wsl-Manager/releases/download/latest/miniwsl.alpine.rootfs.tar.gz => C:\Users\AntoineMartin\AppData\Local\Wsl\RootFS\miniwsl.alpine.rootfs.tar.gz...
####> Creating distribution [test2]...
####> Done. Command to enter distribution: wsl -d test2
❯
More documentation and examples are available in the project documentation.