DEV Community

Cover image for Renaming WSL Distributions
Octasoft Ltd profile image Ian Packard
Ian Packard for Octasoft Ltd

Posted on • Originally published at wsl-ui.octasoft.co.uk

Renaming WSL Distributions

#wsl #windows #registry #wt

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.

How WSL Stores Distribution Names

Each WSL distribution is registered in the Windows Registry under:

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\
Enter fullscreen mode Exit fullscreen mode

Inside that path, each distribution has its own subkey identified by a GUID:

Lxss\
  {12345678-abcd-...}\
    DistributionName = "Ubuntu-24.04"
    BasePath = "C:\Users\you\AppData\Local\wsl\..."
    State = 1
    Version = 2
Enter fullscreen mode Exit fullscreen mode

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.

The Manual Approach

Step 1: Find the Distribution's GUID

Open PowerShell and find your distribution's registry key:

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

This shows all your distributions and their GUIDs:

GUID                                  Name
----                                  ----
{12345678-abcd-1234-abcd-123456789012} Ubuntu-24.04
{87654321-dcba-4321-dcba-210987654321} Alpine
Enter fullscreen mode Exit fullscreen mode

Step 2: Stop the Distribution

The distribution must be stopped before renaming:

wsl --terminate Ubuntu-24.04
Enter fullscreen mode Exit fullscreen mode

Step 3: Edit the Registry

Open Registry Editor (regedit) and navigate to:

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{your-guid}
Enter fullscreen mode Exit fullscreen mode

Double-click DistributionName and change it to your new name.

Or from PowerShell (run as your normal user, not admin):

$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

Step 4: Update Windows Terminal

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:

%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\
Enter fullscreen mode Exit fullscreen mode

Preview Terminal:

%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe\LocalState\
Enter fullscreen mode Exit fullscreen mode

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:

{
  "profiles": {
    "list": [
      {
        "guid": "{12345678-abcd-1234-abcd-123456789012}",
        "name": "DevBox",
        "source": "Windows.Terminal.Wsl"
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

The GUID in the Terminal profile matches the GUID in the registry, so you can find the right entry by comparing them (case-insensitive).

Step 5: Rename the Start Menu Shortcut

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:

%APPDATA%\Microsoft\Windows\Start Menu\Programs\
Enter fullscreen mode Exit fullscreen mode

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:

HKCU\...\Lxss\{GUID}\ShortcutPath
Enter fullscreen mode Exit fullscreen mode

Step 6: Verify

Start the distribution with its new name:

wsl -d DevBox
Enter fullscreen mode Exit fullscreen mode

Check Windows Terminal — the profile should now show "DevBox" in the dropdown.

renaming-wsl-distributions/rename-workflow

Naming Rules

WSL distribution names have restrictions:

  • 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)

Choose names that are meaningful to you. Some patterns that work well:

  • By purpose: DevBox, WebServer, MLWorkspace
  • By project: ProjectAlpha, ClientSite, Staging
  • By distro + purpose: Ubuntu-Dev, Debian-Build, Alpine-Tools

The Easy Way: WSL UI

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:

  • 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

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.

Troubleshooting

"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.

Summary

Step What to Update Location
Registry DistributionName value HKCU\...\Lxss\{GUID}
Terminal profile name field Fragment JSON in Terminal LocalState
Terminal settings name in profiles list settings.json in Terminal LocalState
Start Menu Shortcut filename %APPDATA%\...\Start Menu\Programs\
Registry (shortcut) ShortcutPath value HKCU\...\Lxss\{GUID}

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

Top comments (0)