WSL 구성

WSL Dashboard를 사용하려면 먼저 Windows 시스템에서 WSL 2 환경이 올바르게 활성화되고 구성되어 있어야 합니다. 이 문서는 다음 세 부분으로 구성됩니다:

1. WSL 활성화 및 구성: WSL 2의 기본 설치와 구성을 완료합니다.
2. 명령이 실행 가능 ≠ 설치 성공: wsl 명령이 실행된다고 해서 Linux를 설치할 수 있는 것은 아님을 설명합니다.
3. 설치 실패 문제 해결: 구성 완료 후에도 설치가 실패하는 경우의 확인 및 복구 방법.

1. WSL 활성화 및 구성

이 장에서는 필요한 기본 설정을 안내합니다. 이 장을 완료한 후 제 2장을 읽어 명령 실행 가능과 설치 성공의 차이를 이해하세요. 그래도 설치에 문제가 있다면 제 3장을 참조하세요.

1.1 시스템 요구 사항 확인

WSL 2에는 Windows 버전에 대한 최소 요구 사항이 있습니다. Win + R을 누르고 winver를 입력하여 버전을 확인하세요:

• Windows 10: 버전 1903 이상이며 빌드 번호가 18362 이상이어야 합니다.
• Windows 11: 모든 버전이 지원됩니다.

IMPORTANT

버전이 너무 낮다면 먼저 "Windows 업데이트"로 시스템을 업그레이드하세요.

1.2 하드웨어 가상화 활성화

WSL 2는 가상화 기술 기반으로 실행되므로 메인보드 BIOS/UEFI에서 **가상화 기술(Virtualization Technology)**을 활성화해야 합니다.

• 확인 방법: "작업 관리자" → "성능" 탭 → "CPU"를 엽니다.
• 상태 확인: 오른쪽 아래의 "가상화" 상태가 **"사용"**으로 표시되는지 확인합니다.
• 활성화 방법: 활성화되어 있지 않다면 PC를 재시작하여 BIOS/UEFI 설정으로 들어가 Intel VT-x 또는 AMD-V와 같은 옵션을 찾아 Enabled로 설정하세요.

1.3 Windows 관련 기능 활성화

Windows의 "Linux용 Windows 하위 시스템" 및 "가상 머신 플랫폼" 기능을 활성화해야 합니다.

방법 A: 그래픽 인터페이스로 (권장)

1. Win + S를 누르고 **"Windows 기능 켜기/끄기"**를 검색하여 엽니다.
2. 다음 두 항목에 체크하세요:
   • Linux용 Windows 하위 시스템(Windows Subsystem for Linux)
   • 가상 머신 플랫폼(Virtual Machine Platform)
3. "확인"을 클릭하고 메시지가 표시되면 PC를 재시작하세요.

방법 B: 명령줄로 (관리자 권한)

관리자 권한으로 PowerShell을 실행하고 다음 명령을 실행하세요:

# WSL 활성화
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 가상 머신 플랫폼 활성화
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

실행 후 수동으로 PC를 재시작하세요.

1.4 WSL 커널 설치/업데이트

최신 버전의 Windows는 Microsoft Store에서 WSL 업데이트를 받을 수 있습니다.

• 다운로드 주소: Microsoft Store - Windows Subsystem for Linux
• 수동 다운로드: 스토어를 사용할 수 없다면 WSL GitHub Releases에서 최신 .msixbundle 또는 .msi 설치 패키지를 다운로드하여 오프라인 설치할 수 있습니다.

1.5 WSL 2를 기본 버전으로 설정

새로 설치하는 배포판이 기본적으로 WSL 2를 사용하도록 터미널에서 다음을 실행하세요:

wsl --set-default-version 2

1.6 자주 묻는 질문

• 오류 0x80370102: 일반적으로 BIOS에서 가상화가 활성화되지 않았거나 Hyper-V와 충돌이 있기 때문입니다.
• WSL 1과 WSL 2 전환: wsl --set-version <배포판 이름> 2를 사용하여 기존 WSL 1 인스턴스를 WSL 2로 업그레이드할 수 있습니다.

2. 명령이 실행 가능 ≠ 설치 성공

wsl --version, wsl -l -v 등의 명령이 정상적으로 실행된다고 해서 Linux를 설치할 수 있는 환경이 갖춰졌다는 의미는 아닙니다. 둘은 서로 다른 단계이며 등호로 연결할 수 없습니다.

명령이 실행 가능하다는 것은 다음만을 의미합니다:

• ✅ Windows에서 WSL 구성 요소가 활성화/설치되었음
• ✅ wsl.exe 명령줄 도구를 사용할 수 있음
• ✅ 시스템이 WSL 관련 명령을 인식할 수 있음

하지만 Linux 배포판 설치를 성공하려면 추가 조건을 충족해야 합니다. 흔히 막히는 부분은 다음과 같습니다:

1. 가상화가 꺼져 있음: BIOS/UEFI에서 VT-x / AMD-V가 활성화되지 않아 WSL 2를 시작할 수 없거나, 배포판 설치 시 가상화 오류가 보고됩니다(확인 방법은 1.2 하드웨어 가상화 활성화 참조).
2. Windows 버전/빌드가 너무 낮음: WSL 2에는 커널과 버전 요구 사항이 있습니다. Home 에디션이나 너무 오래된 엔터프라이즈 이미지에서는 기능이 부족할 수 있습니다(확인 방법은 1.1 시스템 요구 사항 확인 참조).
3. Linux 배포판이 아직 실제로 설치되지 않음: wsl -l -v는 설치된 배포판만 나열합니다. 아무것도 설치하지 않았다면 목록이 비어 있으며, 이것이 Ubuntu를 바로 실행할 수 있다는 의미는 아닙니다.
4. 네트워크 / Microsoft Store 문제: wsl --install -d <배포판>은 스토어나 네트워크에서 이미지를 가져와야 하므로, 사내 네트워크, 프록시, 방화벽이 모두 차단할 수 있습니다.
5. 권한 부족: 배포판 설치나 WSL 설정 변경에는 관리자 권한이 필요합니다.

TIP

간단히 말하면: WSL 명령이 작동 ≠ Linux 준비 완료입니다. "입장권"을 받았을 뿐, 아직 실제로 시스템을 설치하지 않았습니다.

3. 설치 실패 문제 해결

제 1장에 따라 구성을 완료했는데도(또는 구성을 완료했다고 생각하는데도) wsl --install이 계속 실패한다면 다음 순서로 확인하세요.

3.1 먼저 "원클릭 진단" 실행

관리자 권한으로 PowerShell을 실행하고 순서대로 실행하세요:

wsl --install --no-distribution
wsl --set-default-version 2

• ✅ 두 명령이 모두 원활하게 실행된다면 WSL 선택 구성 요소가 활성화되고 가상화 조건이 대체로 충족된 것입니다.
• ❌ 실패하면 무엇이 부족한지(가상 머신 플랫폼, Hyper-V, BIOS 가상화 등) 직접 표시됩니다.

그런 다음 systeminfo를 실행하여 출력에 **Virtualization Enabled In Firmware: Yes**가 표시되는지 확인하세요. 위 항목 모두 오류가 없다면 안심하고 wsl --install로 배포판을 설치할 수 있습니다.

NOTE

wsl --install이 반드시 성공한다는 것을 100% 보장하는 명령은 없지만, 위 진단으로 설치 조건이 충족되었는지 확인할 수 있습니다.

3.2 수동 확인 체크리스트

"원클릭 진단"으로도 문제를 찾을 수 없다면 항목별로 확인하세요:

1. BIOS/펌웨어 가상화가 활성화되었는지: 관리자 PowerShell에서 systeminfo를 실행하여 출력에 Virtualization Enabled In Firmware: Yes가 표시되어야 합니다.
2. Windows 기능이 활성화되었는지:

   Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
   Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

   두 명령의 상태가 모두 Enabled여야 합니다.
3. WSL을 사용할 수 있는지: wsl --version을 실행하여 정상 출력이 있는지 확인하세요. "명령을 찾을 수 없음"이 표시되면 WSL 구성 요소가 설치되지 않은 것이므로 제 1장으로 돌아가세요.
4. WSL 2를 사용할 수 있는지(커널 & 가상 머신 플랫폼): wsl --set-default-version 2가 정상적으로 반환되어야 합니다. 흔한 실패 원인: 가상 머신 플랫폼이 활성화되지 않았거나 BIOS에서 VT-x / AMD-V가 활성화되지 않음.

3.3 흔한 실패 원인 빠른 참조

상황	설명	처리 방법
BIOS에서 가상화 미활성화	반드시 실패	재시작하여 BIOS에서 VT-x / AMD-V 활성화(1.2 참조)
Windows 10이 19041 미만	wsl --install 미지원	시스템 업그레이드(1.1 참조)
기업 환경에서 Hyper-V / 가상화 비활성화	실패할 수 있음	시스템 관리자에게 문의
오래된 Home 에디션	수동 설치 필요	1.4에 따라 WSL 커널 수동 설치

3.4 오류 0xc03a0014: 가상 디스크 지원 공급자를 찾을 수 없음

오류 메시지는 Cannot find a virtual disk support provider for the specified file입니다. 이것은 Linux 배포판 자체의 문제가 아니라 Windows의 VHD/VHDX 가상 디스크 스택이 정상적으로 작동하지 않는 것이며, WSL 2가 배포판 등록, ext4.vhdx 생성/마운트에 실패합니다.

먼저 최소 검증: 관리자 권한으로 PowerShell을 실행하고 New-VHD를 테스트하세요(예: New-VHD -Path C:\test.vhdx -SizeBytes 1GB). 이 명령도 같은 오류를 보고한다면 문제는 100% Windows 쪽에 있으며 배포판과 무관합니다.

다음 순서로 확인하고 복구하세요:

1. Virtual Disk 서비스가 실행되지 않음: services.msc를 열고 Virtual Disk 서비스를 찾아 시작 유형을 "자동"으로 설정하고 시작하세요.

2. WSL / 가상 머신 플랫폼 기능이 활성화되지 않음(또는 반영되지 않음): 1.3 Windows 관련 기능 활성화의 명령을 다시 실행한 후 반드시 재시작하세요. Windows Home 에디션에는 완전한 Hyper-V가 없지만, WSL 2에는 가상 머신 플랫폼만 필요하며 Hyper-V 관리 인터페이스는 아닙니다.

3. 가상 디스크 드라이버/장치 누락: 장치 관리자를 열고 "시스템 장치 / 저장 컨트롤러"에 다음이 존재하는지 확인하세요:

   • Microsoft Virtual Disk Provider
   • Microsoft Virtual Drive Enumerator
   • Microsoft VHD Loopback Controller

   누락된 경우 hdwwiz.exe로 수동 추가할 수 있으며(저장 컨트롤러 → Microsoft → Microsoft VHD 루프백 컨트롤러), FsDepends 서비스가 비활성화되지 않았는지도 확인하세요.

4. 가져온 이미지가 WSL 요구 사항을 충족하지 않음: wsl --import --vhd를 사용할 때 VHDX는 ext4 파일 시스템이어야 합니다. LUKS 암호화 디스크, 일반 raw.img, Live ISO, NTFS/FAT로 포맷된 빈 디스크는 사용할 수 없습니다. .img / .qcow2 / .iso는 wsl --import --vhd에 직접 사용할 수 없습니다.

5. 경로/권한/파일 시스템 문제: 대상 디렉터리는 NTFS 디스크에 있어야 합니다(FAT32/exFAT 불가). 경로에 한글, 공백, 특수 문자를 피하세요. 네트워크 드라이브, OneDrive, 압축 폴더에서 가져오지 마세요. 반드시 진짜 관리자 PowerShell(일반 터미널이 아닌)을 사용하세요.

6. 시스템 구성 요소 손상: DISM과 SFC를 순서대로 실행하여 시스템 구성 요소를 복구한 후 다시 시도하세요:

   DISM.exe /Online /Cleanup-Image /RestoreHealth
   sfc /scannow

TIP

타사 가상 머신(VirtualBox, VMware)이나 보안 소프트웨어의 샌드박스/강화 기능(360, 화웨이 등)이 가상 디스크 작업을 방해할 수 있습니다. 문제 해결 시 잠시 끄고 시도하세요.