WSL 설치 방법: 빌드 19041 확인과 오류 해결 7가지
WSL 설치는 명령 한 줄과 재부팅이면 끝난다
WSL 설치는 Windows 10 버전 2004(빌드 19041) 이상이나 Windows 11이면 끝까지 명령 한 줄로 됩니다. 관리자 권한 PowerShell에서 wsl --install을 실행하고 컴퓨터를 다시 시작하면 됩니다(Microsoft Learn, 2025). 따로 고르지 않으면 Ubuntu가 WSL 2로 설치됩니다. 설치가 0x80370102 오류로 멈추면 BIOS(바이오스) 가상화와 Virtual Machine Platform 기능이 켜져 있는지 먼저 확인합니다.
WSL(Linux용 Windows 하위 시스템)은 가상 머신이나 이중 부팅 없이 Windows 위에서 Linux 배포판과 Bash 명령줄 도구를 직접 쓰게 해 주는 Windows 기능입니다(Microsoft Learn, 2025). WSL 2는 가벼운 관리형 가상 머신 안에서 진짜 Linux 커널을 돌리는 방식이고, WSL 1은 번역 계층으로 Linux 시스템 호출을 처리하는 방식입니다(Microsoft Learn, 2025). 지금은 WSL 2가 기본값입니다.
이 가이드는 네 단계를 차례로 다룹니다. 설치 전에 빌드 번호로 설치 방법을 정하고, 명령을 실행하고, 오류 코드를 대조하고, 설치 뒤 상태를 점검합니다. 터미널 개발 환경을 다룬 다른 글은 AI·개발 도구 가이드 목록에 모여 있습니다.
내 윈도우 빌드 번호로 설치 방법을 판정한다
설치 방법은 Windows 빌드 번호 하나로 정해집니다. Windows 키 + R을 누르고 winver를 입력하면 버전과 빌드가 보입니다. 명령 프롬프트에서 ver를 입력해도 됩니다(Microsoft Learn, 2025). 설정 → 시스템 → 정보의 "OS 빌드" 항목에서도 같은 번호를 볼 수 있습니다(Microsoft Learn, 2026).
아래 표는 빌드 번호 구간별로 쓸 수 있는 WSL 버전과 설치 방법을 보여 줍니다.
| Windows 빌드 번호(구간) | WSL 1 | WSL 2 | wsl --install 한 줄 설치 |
판정 |
|---|---|---|---|---|
| 14393 미만 | 불가 | 불가 | 불가 | WSL을 전혀 지원하지 않음. Windows 업데이트가 먼저 |
| 14393 ~ 18361 | 가능 | 불가 | 불가 | 수동 설치 문서를 따라 WSL 1만 사용 |
| 18362(버전 1903) ~ 19040 | 가능 | 가능 | 불가 | 수동 설치 문서를 따라 WSL 2 사용 |
| 19041(버전 2004) ~ 19043 | 가능 | 가능 | 가능 | 관리자 PowerShell에서 한 줄 설치 |
| 19044 이상, Windows 11 | 가능 | 가능 | 가능 | 한 줄 설치 시 Microsoft Store 버전 WSL이 설치됨 |
표의 기준은 Microsoft 공식 문서 세 곳에서 가져왔습니다. 14393 미만은 미지원이고, WSL 2는 18362 이상, wsl --install은 19041 이상에서 쓸 수 있습니다(Microsoft Learn, 2025). 빌드 19044 이상에서는 wsl.exe --install이 Microsoft Store 버전 WSL을 설치합니다(Microsoft Learn, 2025). Store 버전은 Windows 업데이트를 기다리지 않고 Store 패키지로 따로 업데이트됩니다.
빌드 번호가 맞아도 CPU가 오래됐으면 WSL 2를 쓸 수 없습니다. WSL 2에는 SLAT(2단계 주소 변환)를 지원하는 CPU가 필요합니다. SLAT는 Intel Nehalem(Core 1세대)과 AMD Opteron부터 들어갔고, Intel Core 2 Duo 같은 이전 CPU에서는 WSL 2가 돌지 않습니다(Microsoft Learn, 2026). Windows 10을 계속 쓸 계획이라면 Windows 10 ESU 등록 가이드에서 보안 업데이트를 연장하는 방법도 함께 확인하세요.
wsl --install은 이 순서로 실행한다
wsl --install은 WSL에 필요한 Windows 기능을 켜고 Ubuntu 배포판까지 한 번에 설치하는 명령입니다(Microsoft Learn, 2025). 아래 체크리스트를 위에서부터 순서대로 따라 하면 됩니다.
- 시작 메뉴에서 PowerShell을 마우스 오른쪽 단추로 클릭하고 관리자 권한으로 실행을 고릅니다.
wsl --install을 입력합니다.- 명령이 끝나면 컴퓨터를 다시 시작합니다.
- 시작 메뉴에서 "Ubuntu"를 실행합니다. 처음 한 번은 파일 압축이 풀릴 때까지 기다리라는 메시지가 뜹니다. 그다음부터는 1초도 안 걸려 열립니다(Microsoft Learn, 2025).
- Linux 사용자 이름과 암호를 만듭니다. 이 계정은 Windows 계정과 별개이고, 설치 직후 꼭 만들어야 합니다(Microsoft Learn, 2025).
wsl --install은 WSL이 전혀 설치되지 않은 PC에서만 위처럼 동작합니다(Microsoft Learn, 2025). 명령을 넣었는데 도움말만 나온다면 WSL 자체는 이미 깔려 있는 상태입니다. 이때는 wsl --list --online으로 배포판 목록을 보고 wsl --install -d Ubuntu처럼 배포판 이름을 지정해 설치합니다.
배포판·설치 위치를 바꾸는 옵션
wsl --install에 옵션을 붙이면 기본 동작을 바꿀 수 있습니다. 아래 표는 Microsoft 기본 명령 문서에 나온 옵션과 쓰임새를 정리한 것입니다.
| 옵션(명령 인자) | 하는 일 | 쓸 수 있는 조건 |
|---|---|---|
-d 또는 --distribution |
Ubuntu 대신 다른 배포판 설치 | 항상 |
--no-launch |
설치만 하고 배포판을 자동 실행하지 않음 | 항상 |
--web-download |
Microsoft Store 대신 온라인 원본에서 내려받음 | 항상 |
--location |
배포판을 설치할 폴더 지정 | 항상 |
--inbox |
Store 대신 Windows 구성 요소로 WSL 설치. 업데이트는 Windows 업데이트로 받음 | WSL이 설치되지 않았을 때 |
--enable-wsl1 |
Store 버전을 설치하면서 WSL 1도 함께 켬 | WSL이 설치되지 않았을 때 |
--no-distribution |
WSL만 설치하고 배포판은 설치하지 않음 | WSL이 설치되지 않았을 때 |
설치 진행률이 0.0%에서 멈추면 배포판을 먼저 내려받게 해야 합니다. wsl --install --web-download -d Ubuntu를 실행합니다(Microsoft Learn, 2025). Windows 10에서는 배포판을 지정할 때 -d를 반드시 붙여야 할 수도 있습니다(Microsoft Learn, 2025).
오류 코드별 원인과 해결 순서
WSL 설치 오류는 대부분 Windows 기능이 꺼져 있거나, 가상화가 꺼져 있거나, 저장 위치가 C: 드라이브가 아닐 때 납니다. 아래 표는 화면에 뜬 오류 코드를 Microsoft 문제 해결 문서(2026년 4월 15일 개정)의 원인·해결 방법과 1:1로 짝지은 것입니다.
| 오류 코드 | 공식 문서에 적힌 원인 | 해결 순서 |
|---|---|---|
0x80370102 |
Virtual Machine Platform이 꺼져 있거나 BIOS 가상화가 꺼짐 | 아래 7단계 점검표를 따름 |
0x80070003 |
배포판이 시스템 드라이브(보통 C:) 밖에 저장됨, 또는 BIOS 가상화가 꺼짐 | 새 콘텐츠 저장 위치를 C:로 바꾸고, 그래도 나면 BIOS 가상화 확인 |
0x8007019e |
"Linux용 Windows 하위 시스템" 선택적 구성 요소가 꺼짐 | 제어판 → 프로그램 및 기능 → Windows 기능 켜기/끄기에서 켬 |
0x1bc |
wsl --set-default-version 2 실행 때 표시 언어·시스템 로캘이 영어가 아니면 나올 수 있음. 실제로는 WSL 2 커널 구성 요소 업데이트가 필요하다는 뜻 |
수동 설치 문서 4단계의 Linux 커널 업데이트 패키지 설치 |
0x80040154 |
Windows 업데이트 중에 WSL 기능이 꺼짐 | "Linux용 Windows 하위 시스템" 기능을 다시 켬 |
0x8000FFFF |
설치·사용 중 예기치 않은 시스템 오류 | 관리자 권한 → wsl --update → wsl --shutdown 후 재시작 → SFC /SCANNOW → DISM /Online /Cleanup-Image /RestoreHealth |
0x80040306 |
레거시 콘솔을 지원하지 않음 | cmd.exe 제목 표시줄 → 속성 → "레거시 콘솔 사용" 해제 |
0x80070003을 고칠 때는 Windows 버전마다 메뉴 경로가 조금 다릅니다. Windows 10은 설정 → 시스템 → 저장소 → 추가 저장소 설정 → 새 콘텐츠가 저장되는 위치 변경입니다. Windows 11은 설정 → 시스템 → 저장소 → 고급 저장소 설정 → 새 콘텐츠가 저장되는 위치입니다(Microsoft Learn, 2026). WSL은 시스템 드라이브에서만 실행되므로 앱 저장 위치를 C:로 맞춥니다.
0x8007019e와 0x80040154는 둘 다 WSL 기능을 켜면 해결됩니다. 제어판 화면 대신 관리자 PowerShell에서 아래 명령으로 켜도 되고, 켠 뒤에는 컴퓨터를 다시 시작해야 적용됩니다(Microsoft Learn, 2026).
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
0x80370102는 7단계로 점검한다
0x80370102는 "필요한 기능이 설치되지 않아 가상 머신을 시작할 수 없다"는 오류입니다. Microsoft 문제 해결 문서는 아래 순서로 점검하라고 안내합니다(Microsoft Learn, 2026).
- Hyper-V 시스템 요구 사항을 확인합니다. SLAT를 지원하는 CPU여야 합니다.
- 지금 쓰는 PC 자체가 가상 머신이면 호스트에서 중첩 가상화를 켭니다. 관리자 PowerShell에서
Set-VMProcessor -VMName 가상머신이름 -ExposeVirtualizationExtensions $true를 실행합니다. - PC 제조사 안내에 따라 BIOS에서 CPU 가상화를 켭니다. 메뉴 이름과 위치는 PC마다 다릅니다.
- Windows 선택적 기능에서 Virtual Machine Platform을 켜고 다시 시작합니다.
- 부팅 구성에서 하이퍼바이저 실행이 켜져 있는지 확인합니다(아래 명령).
- VMware나 VirtualBox를 함께 쓴다면 Hyper-V를 지원하는 VMware 15.5.5 이상, VirtualBox 6 이상인지 확인합니다. 아니면 그 하이퍼바이저를 끕니다.
- Azure 가상 머신이라면 신뢰할 수 있는 시작(Trusted Launch)을 끕니다. Trusted Launch가 켜진 Azure VM에서는 중첩 가상화가 지원되지 않습니다.
5단계는 관리자 PowerShell에서 아래 명령으로 확인합니다. 결과가 hypervisorlaunchtype Off이면 하이퍼바이저가 꺼진 상태이므로 두 번째 명령으로 켜고 다시 시작합니다.
bcdedit /enum | findstr -i hypervisorlaunchtype
bcdedit /set hypervisorlaunchtype Auto
설치 후 4가지 명령으로 상태를 확인한다
설치가 끝나면 PowerShell에서 명령 네 개로 WSL이 제대로 잡혔는지 확인합니다. 각 명령이 보여 주는 내용은 Microsoft 기본 명령 문서(2025)를 따랐습니다.
| 순서 | 명령 | 확인할 것 |
|---|---|---|
| 1 | wsl -l -v |
배포판 이름, 실행 상태, VERSION 열이 2인지 |
| 2 | wsl --status |
기본 배포판, 기본 버전, 커널 버전 |
| 3 | wsl --version |
WSL과 구성 요소의 버전 정보 |
| 4 | wsl --update |
WSL을 최신 버전으로 올림 |
VERSION 열이 1로 나오면 wsl --set-version Ubuntu 2로 바꿉니다(Microsoft Learn, 2025). 앞으로 설치할 배포판의 기본값까지 WSL 2로 정하려면 wsl --set-default-version 2를 실행합니다. 두 명령 모두 빌드 18362 이상에서만 WSL 2로 바꿀 수 있습니다(Microsoft Learn, 2025).
회사 PC처럼 Microsoft Store가 막혀 있으면 wsl --update --web-download로 GitHub에서 업데이트를 받습니다(Microsoft Learn, 2025). 이 방식은 자동으로 업데이트되지 않습니다. 새 릴리스가 나올 때마다 직접 다시 실행해야 합니다.
.wslconfig를 고쳐 메모리 제한을 바꿨다면 wsl --shutdown으로 WSL 2 가상 머신을 다시 시작해야 합니다. wsl --shutdown은 실행 중인 모든 배포판과 WSL 2 가상 머신을 바로 끕니다(Microsoft Learn, 2025). 저장하지 않은 작업이 배포판 안에 있으면 먼저 저장하세요.
WSL 1이 나은 경우는 따로 있다
Microsoft는 WSL 2를 권장하지만, WSL 1을 권하는 예외 상황도 공식 문서에 적어 두었습니다. 아래 표는 두 버전이 갈리는 항목만 골라 정리한 것입니다(Microsoft Learn, 2025).
| 기능(지원 여부) | WSL 1 | WSL 2 |
|---|---|---|
| 현재 버전 VMware·VirtualBox와 함께 실행 | 지원 | 미지원 |
| 관리되는 VM | 미지원 | 지원 |
| 전체 Linux 커널 | 미지원 | 지원 |
| 전체 시스템 호출 호환성 | 미지원 | 지원 |
| Windows↔Linux 파일 시스템 사이 성능 | 지원 | 미지원 |
| systemd 지원 | 미지원 | 지원 |
WSL 2는 Linux 파일 시스템 안에서 파일을 많이 다루는 작업이 빠릅니다. 초기 WSL 2는 압축 타볼을 풀 때 WSL 1보다 최대 20배, git clone·npm install·cmake는 약 2~5배 빨랐습니다(Microsoft Learn, 2025). 전체 시스템 호출 호환성 덕분에 Docker 같은 앱도 WSL 안에서 돌아갑니다.
아래 상황 가운데 하나라도 해당하면 WSL 1을 고려합니다(Microsoft Learn, 2025).
- 프로젝트 파일을 Windows 파일 시스템에 둬야 하고 Linux 쪽으로 옮길 수 없다.
- 같은 파일을 Windows 도구와 Linux 도구로 번갈아 다루며 교차 컴파일한다.
- 직렬 포트에 접근해야 한다. WSL 2는 직렬 포트를 지원하지 않는다. USB 장치는
USBIPD-WIN프로젝트로 WSL 2에서도 쓸 수 있다. - 메모리 제약이 엄격하다. WSL 2는 캐시된 메모리 페이지를 인스턴스가 끝날 때까지 Windows에 돌려주지 않는다.
버전을 바꾸기 전에는 백업부터 합니다. WSL 1과 WSL 2를 오가는 전환은 오래 걸리고, 두 구조가 달라 오류가 날 수 있습니다. Microsoft는 큰 프로젝트가 있는 배포판이라면 변환 전에 파일을 백업하라고 권합니다(Microsoft Learn, 2025).
프로젝트 폴더는 /home 아래에 둔다
Linux 명령줄에서 작업한다면 프로젝트는 /home/사용자이름/Project처럼 Linux 파일 시스템 안에 둡니다. C:\Users\사용자이름\Project나 /mnt/c/Users/사용자이름/Project에 두는 것보다 빠릅니다(Microsoft Learn, 2025). 반대로 PowerShell·명령 프롬프트에서 작업할 파일은 Windows 파일 시스템에 둡니다.
경로에 /mnt/가 보이면 Windows 드라이브를 마운트해서 쓰고 있다는 뜻입니다. /mnt/c/는 Windows의 C: 드라이브입니다(Microsoft Learn, 2025). 아래 표에서 작업 도구에 따라 어디에 둘지 고릅니다.
| 주로 쓰는 도구 | 저장 위치(경로) | 이유 |
|---|---|---|
| Ubuntu 등 Linux 명령줄 | /home/사용자이름/Project |
WSL 파일 시스템에서 가장 빠름 |
| PowerShell·명령 프롬프트 | C:\Users\사용자이름\Project |
Windows 파일 시스템에서 가장 빠름 |
| Windows와 Linux 도구를 같은 파일에 번갈아 사용 | Windows 쪽 + WSL 1 검토 | 두 OS 사이 파일 성능은 WSL 1이 빠름 |
Linux 쪽 파일은 Windows 탐색기로도 열 수 있습니다. WSL 터미널에서 explorer.exe .를 입력하면 현재 폴더가 탐색기에서 열립니다. 탐색기 주소창에 \\wsl$를 입력하면 설치한 모든 배포판의 루트 파일 시스템이 보입니다(Microsoft Learn, 2025).
파일 이름의 대소문자 처리 방식도 다릅니다. Windows는 FOO.txt와 foo.txt를 같은 파일로 보지만 Linux는 다른 파일로 봅니다(Microsoft Learn, 2025). 두 쪽을 오가는 프로젝트라면 파일 이름의 대소문자를 하나로 통일합니다. 크롬북에서 비슷한 Linux 개발 환경을 꾸린다면 크롬북 Linux 개발 환경 가이드를 참고하세요.
배포판을 지우기 전에 tar로 백업한다
wsl --unregister는 되돌릴 수 없는 명령입니다. wsl --unregister Ubuntu를 실행하면 그 배포판의 데이터·설정·설치한 소프트웨어가 모두 영구 삭제됩니다(Microsoft Learn, 2025). 다시 설치하면 아무것도 없는 새 배포판이 깔립니다.
배포판을 지우거나 다시 설치하기 전에는 아래 순서로 백업합니다. 경로는 예시이니 자기 환경에 맞게 바꿉니다.
wsl -l -v로 정확한 배포판 이름을 확인합니다.wsl --shutdown으로 실행 중인 배포판을 모두 끕니다.wsl --export Ubuntu D:\backup\ubuntu.tar로 스냅숏을 tar 파일로 내보냅니다. 기본 형식이 tar입니다(Microsoft Learn, 2025).- tar 파일이 만들어졌는지 탐색기에서 확인한 뒤에만
wsl --unregister Ubuntu를 실행합니다. - 복원할 때는
wsl --import Ubuntu D:\wsl\ubuntu D:\backup\ubuntu.tar로 가져옵니다.--version 2를 붙이면 WSL 2 배포판으로 가져옵니다(Microsoft Learn, 2025).
WSL 2를 쓴다면 wsl --export에 --vhd를 붙여 tar 대신 .vhdx 파일로 내보낼 수도 있습니다(Microsoft Learn, 2025). 설치를 마쳤다면 지금 wsl -l -v를 실행해 VERSION 열이 2인지부터 확인하세요. 막히는 오류는 개발 도구 커뮤니티 탭에 오류 코드와 wsl --version 결과를 같이 올려 물어보면 됩니다.
자주 묻는 질문
wsl --install을 입력했는데 도움말만 나오면 어떻게 하나요?
WSL이 이미 설치된 PC에서는 wsl --install이 도움말을 보여 줄 수 있습니다. wsl --install은 WSL이 전혀 없을 때만 전체 설치를 진행합니다(Microsoft Learn, 2025). wsl --list --online으로 배포판 목록을 확인한 뒤 wsl --install -d Ubuntu처럼 이름을 지정해 설치하세요.
회사 PC라 Microsoft Store를 쓸 수 없는데 설치할 수 있나요?
Store가 막혀 있어도 설치할 수 있습니다. 설치는 wsl --install --web-download -d Ubuntu로, 업데이트는 wsl --update --web-download로 온라인 원본에서 받습니다(Microsoft Learn, 2025). 이 방식은 자동 업데이트가 되지 않아 새 릴리스가 나올 때마다 직접 업데이트해야 합니다.
이미 설치한 WSL 1 배포판을 WSL 2로 바꿀 수 있나요?
빌드 18362 이상이면 바꿀 수 있습니다. wsl --set-version Ubuntu 2를 실행합니다(Microsoft Learn, 2025). 전환은 오래 걸리고 오류가 날 수 있으니 먼저 wsl --export로 tar 백업을 만들어 두세요.
VMware나 VirtualBox와 WSL 2를 같이 쓸 수 있나요?
Microsoft 비교표는 현재 버전 VMware·VirtualBox와 함께 실행하기를 WSL 1에서만 지원한다고 표시합니다(Microsoft Learn, 2025). 같은 문서는 WSL 2가 VMware 15.5.5 이상, VirtualBox 6 이상에서 동작하지만 아직 중요한 미지원 문제가 남아 있다고 적고 있습니다. 두 도구를 함께 써야 하면 해당 배포판을 WSL 1로 두는 방법도 검토하세요.
WSL 2가 설치되지 않는 CPU도 있나요?
있습니다. WSL 2는 SLAT를 지원하는 CPU가 필요하고, SLAT는 Intel Nehalem(Core 1세대)과 AMD Opteron부터 들어갔습니다(Microsoft Learn, 2026). Intel Core 2 Duo 같은 이전 CPU에서는 Virtual Machine Platform이 설치되더라도 WSL 2가 실행되지 않습니다.
출처
- Microsoft Learn, WSL 설치 (2025): https://learn.microsoft.com/ko-kr/windows/wsl/install
- Microsoft Learn, WSL에 대한 기본 명령 (2025): https://learn.microsoft.com/ko-kr/windows/wsl/basic-commands
- Microsoft Learn, WSL 버전 비교 (2025): https://learn.microsoft.com/ko-kr/windows/wsl/compare-versions
- Microsoft Learn, Linux용 Windows 하위 시스템 문제 해결 (2026): https://learn.microsoft.com/ko-kr/windows/wsl/troubleshooting
- Microsoft Learn, 파일 시스템 간 작업 (2025): https://learn.microsoft.com/ko-kr/windows/wsl/filesystems