Renaming WSL Distributions

Source: Dev.to

Why Renaming Is Not Straightforward

• WSL has no --rename command.
• The distribution name is stored in the Windows Registry.
• The same name is referenced by:
  • Windows Terminal profiles
  • Start‑Menu shortcuts

So renaming touches several places, not just one.

1. Locate the Registry Entries

Each WSL distribution is registered under:

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\

Inside that key each distribution has its own sub‑key identified by a GUID:

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

The DistributionName value is what wsl --list shows and what you use with wsl -d <name>.

List All Distributions and Their GUIDs (PowerShell)

Get-ChildItem "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss" |
  ForEach-Object {
    $name = (Get-ItemProperty $_.PSPath).DistributionName
    [PSCustomObject]@{ GUID = $_.PSChildName; Name = $name }
  } | Format-Table -AutoSize

Sample output

2. Stop the Distribution Before Renaming

wsl --terminate Ubuntu-24.04   # replace with your current name

3. Rename in the Registry

Option A – Using Registry Editor (regedit)

1. Open regedit.
2. Navigate to HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss\{your‑guid}.
3. Double‑click DistributionName and change it to the new name (e.g. DevBox).

Option B – Using PowerShell

$guid = "{12345678-abcd-1234-abcd-123456789012}"   # replace with your GUID
Set-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss\$guid" `
                 -Name "DistributionName" -Value "DevBox"

Note: Run as the normal user (no admin rights required).

4. Update Windows Terminal Profiles

Windows Terminal auto‑generates a profile fragment for each WSL distro. After a registry rename the Terminal UI still shows the old name.

Where the profile files live

A. Update the auto‑generated fragment

Open the JSON fragment in the above folder, locate the entry whose "guid" matches your distro’s GUID, and change the "name" field.

B. Update settings.json (if you have a custom entry)

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

The GUID in the Terminal profile must match the GUID in the registry.

5. Rename the Start‑Menu Shortcut

Distributions installed from the Store get a Start‑Menu shortcut. After renaming the registry entry the shortcut still bears the old name.

1. Open %APPDATA%\Microsoft\Windows\Start Menu\Programs\.
2. Find the .lnk file with the old name (e.g., Ubuntu-24.04.lnk).
3. Rename the file to the new name (e.g., DevBox.lnk).

If the registry contains a ShortcutPath value, update it as well:

Set-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss\$guid" `
                 -Name "ShortcutPath" -Value "%APPDATA%\Microsoft\Windows\Start Menu\Programs\DevBox.lnk"

6. Verify the Rename

wsl -d DevBox          # should start the distro
wsl --list -v          # shows the new name

If you get “distribution not found” → run wsl --shutdown and try again.
If Terminal still shows the old name → double‑check the fragment JSON and settings.json.
If the Start‑Menu shortcut is still wrong → ensure the .lnk file and ShortcutPath value are updated.

7. Naming Rules & Good Practices

Naming patterns that work well

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

8. 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 become inconsistent.

WSL UI bundles everything into a single rename dialog:

• Updates the Registry (DistributionName)
• Optionally updates Windows Terminal (both fragment and settings.json, for Store & Preview)
• Renames the Start‑Menu shortcut and fixes ShortcutPath
• Performs all changes atomically – failures in optional steps (e.g., Terminal not installed) don’t abort the rename.

Real‑time validation checks for invalid characters, duplicates, and length limits before you can submit.

9. Quick Reference Table

TL;DR Steps

1. Terminate the distro: wsl --terminate <old‑name>
2. Rename DistributionName in the registry (regedit or PowerShell).
3. Update Windows Terminal profile fragment & settings.json.
4. Rename the Start‑Menu shortcut and fix ShortcutPath if present.
5. Start the distro with the new name: wsl -d <new‑name>

Now your WSL distributions have clear, meaningful names everywhere—from the command line to Windows Terminal and the Start Menu. Happy coding!