Tools: Renaming WSL Distributions

How WSL Stores Distribution Names ## The Manual Approach ## Step 1: Find the Distribution's GUID ## Step 2: Stop the Distribution ## Step 3: Edit the Registry ## Step 4: Update Windows Terminal ## Step 5: Rename the Start Menu Shortcut ## Step 6: Verify ## Naming Rules ## The Easy Way: WSL UI ## Troubleshooting ## Summary You installed Ubuntu from the Microsoft Store and WSL named it Ubuntu-24.04. You installed another one and got Ubuntu. You imported one from a container and now you have three distributions with names that tell you nothing about what they're for. Wouldn't it be nice to rename them to something meaningful — DevBox, WebServer, DataScience? The problem: WSL doesn't have a --rename command. The distribution name is stored in the Windows Registry, and changing it means editing the registry directly. Worse, that name is also referenced by Windows Terminal profiles and Start Menu shortcuts, so renaming isn't just one change — it's several. Each WSL distribution is registered in the Windows Registry under: Inside that path, each distribution has its own subkey identified by a GUID: The DistributionName value is what wsl --list shows you. It's also what you use in commands like wsl -d Ubuntu-24.04. Changing this value is the core of a rename operation. Open PowerShell and find your distribution's registry key: This shows all your distributions and their GUIDs: The distribution must be stopped before renaming: Open Registry Editor (regedit) and navigate to: Double-click DistributionName and change it to your new name. Or from PowerShell (run as your normal user, not admin): If you use Windows Terminal, it generates profile entries for each WSL distribution. After a registry rename, the Terminal profile still shows the old name. Windows Terminal stores WSL distribution profiles in a fragment JSON file. The location depends on how Terminal was installed: Microsoft Store Terminal: You need to update two things: A. The profile fragment (auto-generated by WSL): Find the profile matching your distribution's GUID and update the name field. B. The settings.json file: Open Terminal's settings.json and find your distribution in the profiles.list array. Update the name field to match: The GUID in the Terminal profile matches the GUID in the registry, so you can find the right entry by comparing them (case-insensitive). WSL distributions installed from the Store get a Start Menu shortcut. After renaming, the shortcut still has the old name. The shortcut is typically at: Find the .lnk file with the old name and rename it to match the new distribution name. After renaming the file, update the ShortcutPath value in the registry if it exists: Start the distribution with its new name: Check Windows Terminal — the profile should now show "DevBox" in the dropdown. WSL distribution names have restrictions: Choose names that are meaningful to you. Some patterns that work well: The manual process is doable but tedious — five separate steps across the registry, Terminal, and file system. Miss one and things are inconsistent. WSL UI handles all of this with a single rename dialog. Enter the new name and optionally toggle: All updates happen atomically. If the Terminal or shortcut update fails (maybe Terminal isn't installed, or the shortcut doesn't exist), the rename still succeeds — those are non-fatal side effects. The validation is real-time too. As you type, it checks for invalid characters, duplicate names, and length limits before you can submit. "wsl -d NewName" says distribution not found: Make sure WSL isn't caching the old name. Run wsl --shutdown then try again. Terminal still shows old name: Check both the profile fragment JSON and the main settings.json. If you have both Terminal and Terminal Preview installed, both need updating. Shortcut still shows old name in Start Menu: The Start Menu may cache the old name. Try unpinning and repinning, or sign out and back in. Default distribution changed unexpectedly: If your renamed distro was the default, verify with wsl --list that it's still marked as default. If not, set it again: wsl --set-default DevBox. WSL not having a built-in rename command is one of those gaps that's surprisingly annoying in practice. Giving your distributions meaningful names makes everything clearer — from wsl -d DevBox in the terminal to the dropdown in Windows Terminal. Originally published at https://wsl-ui.octasoft.co.uk/blog/renaming-wsl-distributions Templates let you quickly answer FAQs or store snippets for re-use. Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse CODE_BLOCK: HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\ Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\ CODE_BLOCK: HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\ CODE_BLOCK: Lxss\ {12345678-abcd-...}\ DistributionName = "Ubuntu-24.04" BasePath = "C:\Users\you\AppData\Local\wsl\..." State = 1 Version = 2 Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: Lxss\ {12345678-abcd-...}\ DistributionName = "Ubuntu-24.04" BasePath = "C:\Users\you\AppData\Local\wsl\..." State = 1 Version = 2 CODE_BLOCK: Lxss\ {12345678-abcd-...}\ DistributionName = "Ubuntu-24.04" BasePath = "C:\Users\you\AppData\Local\wsl\..." State = 1 Version = 2 CODE_BLOCK: Get-ChildItem "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss" | ForEach-Object { $name = (Get-ItemProperty $_.PSPath).DistributionName [PSCustomObject]@{ GUID = $_.PSChildName; Name = $name } } Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: Get-ChildItem "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss" | ForEach-Object { $name = (Get-ItemProperty $_.PSPath).DistributionName [PSCustomObject]@{ GUID = $_.PSChildName; Name = $name } } CODE_BLOCK: Get-ChildItem "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss" | ForEach-Object { $name = (Get-ItemProperty $_.PSPath).DistributionName [PSCustomObject]@{ GUID = $_.PSChildName; Name = $name } } CODE_BLOCK: GUID Name ---- ---- {12345678-abcd-1234-abcd-123456789012} Ubuntu-24.04 {87654321-dcba-4321-dcba-210987654321} Alpine Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: GUID Name ---- ---- {12345678-abcd-1234-abcd-123456789012} Ubuntu-24.04 {87654321-dcba-4321-dcba-210987654321} Alpine CODE_BLOCK: GUID Name ---- ---- {12345678-abcd-1234-abcd-123456789012} Ubuntu-24.04 {87654321-dcba-4321-dcba-210987654321} Alpine CODE_BLOCK: wsl --terminate Ubuntu-24.04 Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: wsl --terminate Ubuntu-24.04 CODE_BLOCK: wsl --terminate Ubuntu-24.04 CODE_BLOCK: HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{your-guid} Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{your-guid} CODE_BLOCK: HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{your-guid} CODE_BLOCK: $guid = "{12345678-abcd-1234-abcd-123456789012}" Set-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss\$guid" ` -Name "DistributionName" -Value "DevBox" Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: $guid = "{12345678-abcd-1234-abcd-123456789012}" Set-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss\$guid" ` -Name "DistributionName" -Value "DevBox" CODE_BLOCK: $guid = "{12345678-abcd-1234-abcd-123456789012}" Set-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss\$guid" ` -Name "DistributionName" -Value "DevBox" CODE_BLOCK: %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\ Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\ CODE_BLOCK: %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\ CODE_BLOCK: %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe\LocalState\ Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe\LocalState\ CODE_BLOCK: %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe\LocalState\ CODE_BLOCK: { "profiles": { "list": [ { "guid": "{12345678-abcd-1234-abcd-123456789012}", "name": "DevBox", "source": "Windows.Terminal.Wsl" } ] } } Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: { "profiles": { "list": [ { "guid": "{12345678-abcd-1234-abcd-123456789012}", "name": "DevBox", "source": "Windows.Terminal.Wsl" } ] } } CODE_BLOCK: { "profiles": { "list": [ { "guid": "{12345678-abcd-1234-abcd-123456789012}", "name": "DevBox", "source": "Windows.Terminal.Wsl" } ] } } CODE_BLOCK: %APPDATA%\Microsoft\Windows\Start Menu\Programs\ Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: %APPDATA%\Microsoft\Windows\Start Menu\Programs\ CODE_BLOCK: %APPDATA%\Microsoft\Windows\Start Menu\Programs\ CODE_BLOCK: HKCU\...\Lxss\{GUID}\ShortcutPath Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: HKCU\...\Lxss\{GUID}\ShortcutPath CODE_BLOCK: HKCU\...\Lxss\{GUID}\ShortcutPath CODE_BLOCK: wsl -d DevBox Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: wsl -d DevBox CODE_BLOCK: wsl -d DevBox - Allowed characters: Letters, numbers, hyphens, underscores, periods - Max length: 64 characters - Cannot start with: A hyphen - Must be unique: Case-insensitive (so "Ubuntu" and "ubuntu" conflict) - By purpose: DevBox, WebServer, MLWorkspace - By project: ProjectAlpha, ClientSite, Staging - By distro + purpose: Ubuntu-Dev, Debian-Build, Alpine-Tools - Update Windows Terminal profile — updates both the profile fragment and settings.json (both Store and Preview variants) - Rename Start Menu shortcut — renames the .lnk file and updates the registry path