{"id":17671617,"url":"https://github.com/antoinemartin/powershell-wsl-manager","last_synced_at":"2026-01-02T14:11:00.520Z","repository":{"id":64080438,"uuid":"573173851","full_name":"antoinemartin/PowerShell-Wsl-Manager","owner":"antoinemartin","description":"Powershell cmdlet to quickly create a minimal WSL distribution based on Arch Linux, Alpine or Ubuntu.","archived":false,"fork":false,"pushed_at":"2024-07-30T19:20:14.000Z","size":413,"stargazers_count":1,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-13T10:46:51.537Z","etag":null,"topics":["alpine","alpine-linux","archlinux","powershell","ubuntu","windows","wsl2"],"latest_commit_sha":null,"homepage":"https://mrtn.me/PowerShell-Wsl-Manager/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antoinemartin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-01T21:27:40.000Z","updated_at":"2024-12-08T17:05:38.000Z","dependencies_parsed_at":"2024-10-24T06:17:25.597Z","dependency_job_id":"97d9a72a-b47c-4b78-82e7-b08a522548e0","html_url":"https://github.com/antoinemartin/PowerShell-Wsl-Manager","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoinemartin%2FPowerShell-Wsl-Manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoinemartin%2FPowerShell-Wsl-Manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoinemartin%2FPowerShell-Wsl-Manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoinemartin%2FPowerShell-Wsl-Manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antoinemartin","download_url":"https://codeload.github.com/antoinemartin/PowerShell-Wsl-Manager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247607739,"owners_count":20965945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alpine","alpine-linux","archlinux","powershell","ubuntu","windows","wsl2"],"created_at":"2024-10-24T03:43:00.660Z","updated_at":"2026-01-02T14:11:00.514Z","avatar_url":"https://github.com/antoinemartin.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PowerShell WSL Manager\r\n\r\n[![codecov](https://codecov.io/github/antoinemartin/PowerShell-Wsl-Manager/graph/badge.svg?token=GGSLVWO0QG)](https://codecov.io/github/antoinemartin/PowerShell-Wsl-Manager)\r\n\r\nA PowerShell module for easily managing WSL _images_ (root filesystems) and\r\n_instances_ (distributions) with pre-configured, lightweight Linux environments.\r\nLike the `Hyper-V` PowerShell module, but focused on WSL.\r\n\r\n\u003e **Note**: We use the term \"instances\" instead of \"distributions\" because you\r\n\u003e can have multiple instances of the same Linux distribution. We also use\r\n\u003e \"images\" to refer to root filesystems for consistency with container\r\n\u003e terminology.\r\n\r\n## 🚀 Quick Start\r\n\r\nInstall from PowerShell Gallery and create your first WSL instance:\r\n\r\n```powershell\r\n# Install the module\r\nInstall-Module -Name Wsl-Manager\r\n\r\n# Create a new Arch Linux instance\r\nNew-WslInstance arch -From arch\r\n\r\n# Enter your new instance\r\nInvoke-WslInstance -In arch\r\n```\r\n\r\n## 📦 What's Included\r\n\r\n**Wsl-Manager** supports creating WSL instances from these Linux distributions:\r\n\r\n- **Archlinux** (2025.08.01)\r\n- **Alpine** (3.22)\r\n- **Ubuntu** (25.10 questing)\r\n- **Debian** (13 trixie)\r\n- **Any Incus distribution**\r\n  ([browse available images](https://images.linuxcontainers.org/images/))\r\n\r\n📚 **[Complete Documentation](https://mrtn.me/PowerShell-Wsl-Manager/)**\r\n\r\n## ✨ Features\r\n\r\n### Pre-Configured Development Environment\r\n\r\nEach WSL instance comes with a complete development setup:\r\n\r\n- **User Account**: Distribution-specific user (`arch`, `alpine`, `ubuntu`,\r\n  `debian`, `opensuse`) with sudo/doas privileges\r\n- **Shell**: zsh with [oh-my-zsh](https://ohmyz.sh/) framework\r\n- **Theme**: [powerlevel10k](https://github.com/romkatv/powerlevel10k) for\r\n  enhanced terminal experience\r\n- **Plugins**:\r\n  - [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions) for\r\n    command completion\r\n  - [wsl2-ssh-pageant](https://github.com/antoinemartin/wsl2-ssh-pageant-oh-my-zsh-plugin)\r\n    for Windows GPG/SSH integration\r\n\r\n### Smart Caching System\r\n\r\n- Downloaded images are cached in `%LOCALAPPDATA%\\Wsl\\RootFS`\r\n- Instance data stored in `%LOCALAPPDATA%\\Wsl\\\u003cInstanceName\u003e`\r\n- Images are pulled from the Github container registry where they are stored as\r\n  single-layer containers.\r\n\r\n## 🎯 Why Use WSL Manager?\r\n\r\nWindows is excellent for Linux backend development through\r\n[Visual Studio Code and WSL](https://code.visualstudio.com/docs/remote/wsl), but\r\nmanaging multiple development environments can be challenging.\r\n\r\n### The Problem with Single WSL Instances\r\n\r\n- **Bloat**: Single instances become cluttered over time\r\n- **Difficult to recreate**: Manual configurations are hard to reproduce\r\n- **Environment conflicts**: Different projects may have conflicting\r\n  requirements\r\n\r\n### The WSL Manager Solution\r\n\r\n- **Multiple lightweight instances**: Each project gets its own clean\r\n  environment\r\n- **Low performance overhead**: All instances share the same virtual machine\r\n  (the WSL 2 VM)\r\n- **Easy management**: Simple commands to create, manage, and destroy instances\r\n- **Consistent setup**: Pre-configured environments ensure repeatability\r\n- **Image management**: Easily sync, update, and remove images\r\n- **Extensibility**: Customize and extend your WSL instances with additional\r\n  tools and configurations\r\n\r\n## 🛠 How It Works\r\n\r\nWSL Manager provides cmdlets organized into two main categories:\r\n\r\n- **`*-WslImageSource`**: Manage root filesystems (similar to Docker images)\r\n  sources.\r\n- **`*-WslImage`**: Manage root filesystems (downloaded images)\r\n- **`*-WslInstance`**: Manage WSL distributions (running environments)\r\n\r\nComplete list of cmdlets: `Get-Command -Module Wsl-Manager`.\r\n\r\n### Image Types\r\n\r\n- **Configured Images**: Pre-setup with zsh, oh-my-zsh, and development tools\r\n- **Base Images**: Minimal upstream distributions for custom configurations\r\n- **Docker Integration**: Images distributed as single-layer containers via\r\n  GitHub Registry\r\n- **Incus Support**: Create instances from any Incus-compatible distribution\r\n\r\n## 📋 Prerequisites\r\n\r\n### System Requirements\r\n\r\n- **Windows 11** with WSL 2 installed and working\r\n  - Run `wsl --install` in terminal if not already set up\r\n- **PowerShell Gallery** access for module installation\r\n\r\n### Recommended Font Setup\r\n\r\nThe pre-configured instances use\r\n[powerlevel10k](https://github.com/romkatv/powerlevel10k) theme with\r\n[Nerd Fonts](https://www.nerdfonts.com/) for optimal display.\r\n\r\n**Quick font installation with Scoop:**\r\n\r\n```powershell\r\nscoop bucket add nerd-fonts\r\nscoop install UbuntuMono-NF-Mono\r\n```\r\n\r\nThen set your terminal font to `'UbuntuMono NF'` in VS Code, Windows Terminal,\r\netc.\r\n\r\n## 🏁 Getting Started\r\n\r\n### Installation\r\n\r\n```powershell\r\nInstall-Module -Name Wsl-Manager\r\n```\r\n\r\n### Create Your First Instance\r\n\r\n```powershell\r\nNew-WslInstance arch -From arch\r\n```\r\n\r\n**Expected output:**\r\n\r\n```powershell\r\n⌛ Creating directory [C:\\Users\\AntoineMartin\\AppData\\Local\\Wsl\\arch]...\r\n⌛ Downloading Docker image layer from ghcr.io/antoinemartin/powershell-wsl-manager/arch:latest...\r\n⌛ Retrieving docker image manifest for antoinemartin/powershell-wsl-manager/arch:latest from registry ghcr.io...\r\n👀 Root filesystem size: 378,7 MB. Digest sha256:b3e7f861649971544e8737803e7f4ad139e97fcf6af34e00db61c4a15df766e2. Downloading...\r\nsha256:b3e7f861649971544e8737803e7f4ad139e97fcf6af34e00db61c4a15df766e2 (378,7 MB) [=======================================================================================================================================] 100%\r\n🎉 Successfully downloaded Docker image layer to C:\\Users\\AntoineMartin\\AppData\\Local\\Wsl\\RootFS\\B0716C8EC7F926370A8E83278207995FDFB212412542634B5345162064965D22.rootfs.tar.gz.tmp. File size: 378,7 MB\r\n🎉 [Arch:2025.12.01] Synced at [C:\\Users\\AntoineMartin\\AppData\\Local\\Wsl\\RootFS\\B0716C8EC7F926370A8E83278207995FDFB212412542634B5345162064965D22.rootfs.tar.gz].\r\n⌛ Creating instance [arch] from [C:\\Users\\AntoineMartin\\AppData\\Local\\Wsl\\RootFS\\B0716C8EC7F926370A8E83278207995FDFB212412542634B5345162064965D22.rootfs.tar.gz]...\r\n🎉 Done. Command to enter instance: Invoke-WslInstance -In arch or wsl -d arch\r\n\r\nName                                        State Version Default\r\n----                                        ----- ------- -------\r\narch                                      Stopped       2   False\r\n```\r\n\r\n### Enter Your Instance\r\n\r\n```powershell\r\n# Method 1: Using WSL Manager\r\nInvoke-WslInstance -In arch\r\n\r\n# Method 2: Using native WSL\r\nwsl -d arch\r\n```\r\n\r\n### Basic Instance Management\r\n\r\n```powershell\r\n# List all instances\r\nGet-WslInstance\r\n\r\n# Remove an instance\r\nRemove-WslInstance arch\r\n\r\n# List available images\r\nGet-WslImageSource -Source Builtin\r\n\r\n# Download specific images\r\nSync-WslImage alpine,alpine-base\r\n\r\n# Create instance from base image (minimal configuration)\r\nNew-WslInstance test -From alpine-base\r\n```\r\n\r\n## 💡 Quick Tips\r\n\r\n- **Caching**: Downloaded images are cached locally for faster subsequent\r\n  deployments\r\n- **Cleanup**: Removing instances deletes their directories but keeps cached\r\n  images\r\n- **Multiple versions**: Run multiple instances of the same distribution\r\n  simultaneously\r\n- **Custom configs**: Use base images to create your own development\r\n  environments\r\n\r\n## 🛠 Command Aliases\r\n\r\nWSL Manager provides convenient aliases for easier usage:\r\n\r\n```powershell\r\n# Create and immediately enter a new instance\r\nnwsl test -From alpine | iwsl\r\n\r\n# List and remove running instances\r\ngwsl -State Running | rmwsl\r\n```\r\n\r\n**Common aliases:**\r\n\r\n\u003c!-- cSpell:ignore nwsl iwsl gwsl rmwsl --\u003e\r\n\r\n- `nwsl` → `New-WslInstance`\r\n- `iwsl` → `Invoke-WslInstance`\r\n- `gwsl` → `Get-WslInstance`\r\n- `rmwsl` → `Remove-WslInstance`\r\n\r\nView all aliases: `Get-Command -Module Wsl-Manager -CommandType Alias`\r\n\r\n## 📚 More Information\r\n\r\n**Complete documentation and examples:**\r\n[https://mrtn.me/PowerShell-Wsl-Manager/](https://mrtn.me/PowerShell-Wsl-Manager/)\r\n\r\n**PowerShell Gallery:**\r\n[`Wsl-Manager`](https://www.powershellgallery.com/packages/Wsl-Manager)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantoinemartin%2Fpowershell-wsl-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantoinemartin%2Fpowershell-wsl-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantoinemartin%2Fpowershell-wsl-manager/lists"}