WSL 배포판 이름 바꾸기

I’m happy to help translate the article, but I need the full text you’d like translated. Could you please paste the content (excluding the source line you already provided) here? Once I have it, I’ll translate it into Korean while preserving the formatting, markdown, and any code blocks or URLs.

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.

왜 이름 바꾸기가 간단하지 않은가

• WSL에는 --rename 명령이 없습니다.
• 배포판 이름은 Windows 레지스트리에 저장됩니다.
• 동일한 이름이 다음에서 참조됩니다:
  • Windows Terminal 프로필
  • 시작 메뉴 바로가기

따라서 이름을 바꾸면 여러 곳에 영향을 미치며, 하나만 바꾸는 것이 아닙니다.

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 UI에는 여전히 이전 이름이 표시됩니다.

프로필 파일 위치

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          # 배포판이 시작되어야 함
wsl --list -v          # 새 이름이 표시됨

“distribution not found” 오류가 발생하면 → wsl --shutdown을 실행하고 다시 시도합니다.
터미널에 여전히 이전 이름이 표시되면 → fragment JSON과 settings.json을 다시 확인합니다.
시작 메뉴 바로 가기가 여전히 잘못되어 있으면 → .lnk 파일과 ShortcutPath 값이 업데이트되었는지 확인합니다.

7. Naming Rules & Good Practices

잘 작동하는 명명 패턴

• 목적별 – DevBox, WebServer, MLWorkspace
• 프로젝트별 – ProjectAlpha, ClientSite, Staging
• 배포판 + 목적별 – Ubuntu-Dev, Debian-Build, Alpine-Tools

8. 쉬운 방법 – WSL UI

수동 과정도 가능하지만 번거롭습니다 – 레지스트리, 터미널, 파일 시스템에 걸쳐 다섯 단계가 필요합니다. 하나라도 놓치면 일관성이 깨집니다.

WSL UI는 모든 작업을 하나의 이름 바꾸기 대화상자로 묶습니다:

• 레지스트리 업데이트 (DistributionName)
• 선택적으로 Windows Terminal 업데이트 (스토어 및 프리뷰용 fragment와 settings.json 모두)
• 시작‑메뉴 바로 가기 이름 변경 및 ShortcutPath 수정
• 모든 변경을 원자적으로 수행 – 선택 단계에서 실패해도(예: 터미널이 설치되지 않음) 이름 바꾸기가 중단되지 않습니다.

실시간 검증을 통해 잘못된 문자, 중복, 길이 제한 등을 제출 전에 확인합니다.

9. 빠른 참고 표

TL;DR 단계

1. 종료 배포판: wsl --terminate <old‑name>
2. 레지스트리에서 DistributionName을 이름 바꾸기 (regedit 또는 PowerShell).
3. Windows Terminal 프로필 조각 및 settings.json을 업데이트.
4. 시작 메뉴 바로 가기 이름을 바꾸고 ShortcutPath가 있으면 수정합니다.
5. 새 이름으로 배포판을 시작: wsl -d <new‑name>

이제 WSL 배포판은 명령줄, Windows Terminal, 시작 메뉴 등 모든 곳에서 명확하고 의미 있는 이름을 갖게 됩니다. 즐거운 코딩 되세요!