WSL Dashboardhttps://www.wslui.com

한국어

English
简体中文
繁體中文
Español
Français
Русский
Português
Deutsch
日本語
हिन्दी
বাংলা
Bahasa Indonesia
Türkçe
Italiano
Nederlands
Svenska
Čeština
Ελληνικά
Magyar
Norsk
Dansk
Suomi
Slovenčina
Slovenščina
Íslenska
Tiếng Việt
తెలుగు
Jawa
ภาษาไทย
தமிழ்
Filipino
Polski
Українська
ಕನ್ನಡ
मराठी
Hausa
မြန်မာ
O'zbek
Azərbaycan
Bisaya
മലയാളം
አማርኛ
ਪੰਜਾਬੀ

한국어

English
简体中文
繁體中文
Español
Français
Русский
Português
Deutsch
日本語
हिन्दी
বাংলা
Bahasa Indonesia
Türkçe
Italiano
Nederlands
Svenska
Čeština
Ελληνικά
Magyar
Norsk
Dansk
Suomi
Slovenčina
Slovenščina
Íslenska
Tiếng Việt
తెలుగు
Jawa
ภาษาไทย
தமிழ்
Filipino
Polski
Українська
ಕನ್ನಡ
मराठी
Hausa
မြန်မာ
O'zbek
Azərbaycan
Bisaya
മലയാളം
አማርኛ
ਪੰਜਾਬੀ

Appearance

Setup & Config 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 Update"를 통해 시스템을 업그레이드하세요.

1.2 하드웨어 가상화 활성화 ​

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

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

1.3 Windows 관련 기능 활성화 ​

Windows의 "Windows Subsystem for Linux" 및 "가상 머신 플랫폼" 기능을 활성화해야 합니다.

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

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

방법 B: 명령줄 사용 (관리자 권한) ​

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

powershell
# WSL 사용
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

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

실행이 완료되면 수동으로컴퓨터를 다시 시작하세요.

1.4 WSL 커널 설치/업데이트 ​

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

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

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

powershell
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에는 커널과 버전에 대한 요구 사항이 있으며, 홈 에디션이나 너무 오래된 엔터프라이즈 이미지는 기능이 부족할 수 있습니다 (확인 방법은 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을 실행하고 다음 명령을 순서대로 실행하세요:

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 기능이 활성화되어 있는지 확인:
    powershell
    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 / 가상화 비활성화실패할 수 있음시스템 관리자에게 문의
구형 홈 에디션 시스템수동 설치 필요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 홈 에디션에는 전체 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를 순서대로 실행하여 시스템 구성 요소를 복구한 후 다시 시도하세요:

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

TIP

타사 가상 머신 (VirtualBox, VMware) 또는 보안 소프트웨어의 샌드박스/보안 강화 기능 (예: 360, 화룽)이 가상 디스크 작업을 방해할 수 있으므로, 문제 해결 시 임시로 끄고 다시 시도해 보세요.