How to Rename a WSL Distribution

Note#160

notes
Published

2024-06-21

To rename a WSL distribution, you need to edit a registry key.

Manually Edit the registry Key

  1. Press Win + r and run regedit.exe
  2. Search HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\
  3. Locate the folder for the distribution you want to rename.
  4. Edit the DistributionName key.

Using a PowerShell Script

You may not have the permissions to execute a script in PowerShell. To verify your permissions, run the command Get-ExecutionPolicy.

If necessary, allow local script execution:

Set-ExecutionPolicy RemoteSigned

This allows the execution of local scripts without signatures while still requiring signatures for downloaded scripts.

Script Description

The PowerShell script below automates the WSL distribution renaming. It first lists the current distributions with wsl --list. Then it prompts for the old and new names, and modifies the registry key. Finally, it displays the updated distribution list.

The Script

# Ensure you run this script as an administrator

function Show-WSLDistributions {
    Write-Host "`nCurrent WSL Distributions:"
    wsl --list
}

function Rename-WSLDistribution {
    param (
        [string]$oldName,
        [string]$newName
    )

    $lxssKey = "HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss"
    $distroKey = Get-ChildItem $lxssKey | 
        Where-Object { $_.GetValue("DistributionName") -eq $oldName } |
        Select-Object -First 1

    if ($distroKey) {
        Set-ItemProperty -Path $distroKey.PSPath -Name "DistributionName" -Value $newName
        Write-Host "`nWSL distribution renamed from $oldName to $newName"
        
        Write-Host "`nChecking if the change is visible..."
        Show-WSLDistributions
        
        Write-Host "`nIf you don't see the change reflected above, you may need to restart the WSL service or reboot your computer."
    } else {
        Write-Host "`nWSL distribution '$oldName' not found."
    }
}

# Main script
Write-Host "WSL Distribution Renaming Tool"
Write-Host "==============================`n"

Show-WSLDistributions

$oldName = Read-Host "`nEnter the name of the WSL distribution you want to rename"
$newName = Read-Host "Enter the new name for the distribution"

Rename-WSLDistribution -oldName $oldName -newName $newName