Source: Dev.to

重命名 WSL 发行版

在 Windows Subsystem for Linux (WSL) 中，默认的发行版名称（例如 Ubuntu, Debian）有时并不能很好地表达它们的用途或版本。本文将向你展示如何安全地重命名已安装的 WSL 发行版，而不会丢失任何数据。

为什么要重命名？

• 区分不同的实例：你可能在同一台机器上运行多个相同发行版的实例（例如 Ubuntu-20.04 与 Ubuntu-22.04），使用自定义名称可以避免混淆。
• 更好地组织：如果你为特定项目创建了专用的 WSL 环境，使用项目名称作为发行版名会更直观。
• 兼容脚本：某些自动化脚本可能依赖于特定的发行版名称，重命名后可以让脚本继续工作。

重命名的基本思路

WSL 本身并不提供直接的 “rename” 命令。我们需要通过以下步骤实现相同的效果：

1. 导出 当前发行版的文件系统为一个 .tar 包。
2. 注销（unregister）原来的发行版，使其从 WSL 列表中移除。
3. 导入 同一个 .tar 包，并在导入时指定新的发行版名称。

整个过程是 无缝的，只要在第 2 步之前完成第 1 步的导出，就不会丢失任何数据。

步骤详解

注意：下面的示例假设你要把名为 Ubuntu-20.04 的发行版重命名为 my-ubuntu-dev。请根据自己的实际情况替换相应的名称。

1. 列出已安装的发行版

wsl -l -v

输出示例：

  NAME            STATE           VERSION
* Ubuntu-20.04    Running         2
  Debian          Stopped         2

确认要重命名的发行版名称（这里是 Ubuntu-20.04）。

2. 导出发行版

wsl --export Ubuntu-20.04 C:\WSL\ubuntu-20.04.tar

• C:\WSL\ubuntu-20.04.tar 是导出文件的保存路径。请确保磁盘空间足够（导出文件大小大约等于发行版的实际占用空间）。

3. 注销原发行版

wsl --unregister Ubuntu-20.04

此命令会从 WSL 列表中移除 Ubuntu-20.04，但 不会 删除我们刚才导出的 .tar 包。

4. 导入为新名称

wsl --import my-ubuntu-dev C:\WSL\my-ubuntu-dev C:\WSL\ubuntu-20.04.tar --version 2

• 第一个参数 my-ubuntu-dev 是新发行版的名称。
• 第二个参数 C:\WSL\my-ubuntu-dev 是新发行版的根文件系统目录（WSL 会在此创建一个文件夹）。
• 第三个参数是我们在第 2 步导出的 .tar 包路径。
• --version 2 指定使用 WSL 2（如果你之前使用的是 WSL 1，请改为 --version 1）。

5. 验证重命名是否成功

wsl -l -v

预期输出：

  NAME            STATE           VERSION
* my-ubuntu-dev   Running         2
  Debian          Stopped         2

现在，你已经成功地把 Ubuntu-20.04 重命名为 my-ubuntu-dev。

常见问题

小技巧

• 批量重命名：如果你有多个发行版需要统一命名，可以编写一个 PowerShell 脚本循环执行上述步骤。
• 使用自定义根目录：将根目录放在项目工作空间（例如 D:\Projects\WSL\my-ubuntu-dev），可以更方便地备份或同步。
• 保持备份：即使已经成功导入，建议保留导出的 .tar 包一段时间，以防出现意外情况。

结论

虽然 WSL 没有直接的 “rename” 命令，但通过 导出 → 注销 → 导入 的方式，你可以轻松地为发行版赋予更具描述性的名称。这样不仅有助于组织多个 Linux 环境，还能让日常的开发工作更加流畅。

祝你玩得开心，Happy WSL!

为什么重命名并不简单

• WSL 没有 --rename 命令。
• 发行版名称存储在 Windows 注册表中。
• 相同的名称被以下位置引用：
  • Windows Terminal 配置文件
  • 开始菜单快捷方式

Source: …

1. 定位注册表项

每个 WSL 发行版都注册在：

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

在该键下，每个发行版都有一个由 GUID 标识的子键：

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

DistributionName 值就是 wsl --list 显示的内容，也是使用 wsl -d <name> 时需要的名称。

列出所有发行版及其 GUID（PowerShell）

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

示例输出

2. 在重命名前停止发行版

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

3. 在注册表中重命名

选项 A – 使用注册表编辑器 (regedit)

1. 打开 regedit。
2. 导航至 HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss\{your‑guid}。
3. 双击 DistributionName 并将其更改为新名称（例如 DevBox）。

选项 B – 使用 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"

注意： 以普通用户身份运行（无需管理员权限）。

4. 更新 Windows Terminal 配置文件

Windows Terminal 会为每个 WSL 发行版自动生成一个配置片段。重命名注册表后，Terminal 界面仍会显示旧名称。

配置文件所在位置

A. 更新 自动生成的片段

打开上述文件夹中的 JSON 片段，找到 "guid" 与你的发行版 GUID 相匹配的条目，并修改 "name" 字段。

B. 更新 settings.json（如果你有自定义条目）

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

Terminal 配置文件中的 GUID 必须 与注册表中的 GUID 相匹配。

5. 重命名开始菜单快捷方式

从商店安装的发行版会在开始菜单中生成快捷方式。重命名注册表项后，快捷方式仍显示旧名称。

1. 打开 %APPDATA%\Microsoft\Windows\Start Menu\Programs\。
2. 找到旧名称的 .lnk 文件（例如 Ubuntu-24.04.lnk）。
3. 将文件重命名为新名称（例如 DevBox.lnk）。

如果注册表中包含 ShortcutPath 值，也需要同步更新：

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

6. 验证重命名

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

如果出现 “distribution not found” → 运行 wsl --shutdown 并重试。
如果终端仍显示旧名称 → 再次检查片段 JSON 和 settings.json。
如果开始菜单快捷方式仍有误 → 确保 .lnk 文件和 ShortcutPath 值已更新。

7. 命名规则与最佳实践

常用的命名模式

• 按用途 – DevBox、WebServer、MLWorkspace
• 按项目 – ProjectAlpha、ClientSite、Staging
• 按发行版+用途 – Ubuntu-Dev、Debian-Build、Alpine-Tools

8. 简单方法 – WSL UI

手动过程虽然可行，但繁琐——需要在注册表、终端和文件系统中完成五个独立步骤。漏掉任何一步都会导致不一致。

WSL UI 将所有操作整合到一个重命名对话框中：

• 更新注册表 (DistributionName)
• 可选地更新 Windows Terminal（包括片段和 settings.json，适用于 Store 版和预览版）
• 重命名开始菜单快捷方式 并修复 ShortcutPath
• 原子执行所有更改——可选步骤（例如未安装 Terminal）失败时不会中止重命名。

实时验证会在提交前检查无效字符、重复项和长度限制。

9. 快速参考表

TL;DR 步骤

1. 终止 the distro: wsl --terminate <old‑name>
2. 重命名 DistributionName in the registry (regedit or PowerShell).
3. 更新 Windows Terminal profile fragment & settings.json.
4. 重命名 开始菜单快捷方式并在存在时修复 ShortcutPath。
5. 启动 the distro with the new name: wsl -d <new‑name>

现在，您的 WSL 发行版在各处都有清晰且有意义的名称——从命令行到 Windows Terminal 再到开始菜单。祝编码愉快！