윈도우에 Docker를 올리기 전에 WSL부터 정리해야 하는 이유
윈도우에서 Docker Desktop을 설치하려다 보면 "WSL 2 installation is incomplete" 같은 메시지에서 막히는 경우가 많습니다. Docker Desktop은 리눅스 컨테이너를 돌리기 위해 내부적으로 WSL 2 백엔드를 사용하기 때문에, 윈도우에 리눅스 개발 환경이 먼저 준비되어 있어야 합니다. 즉 Docker 설치 자체보다 WSL 2 활성화와 커널 업데이트가 먼저 끝나 있어야 한다는 뜻입니다. 이 글에서는 WSL 설치 상태를 점검하는 방법부터 Docker가 요구하는 조건, 설치 후 흔히 마주치는 오류 코드까지 순서대로 정리합니다.
Docker로 넘어가기 전에 확인해야 할 최소 조건은 다음과 같습니다.
- Windows 10 버전 2004(빌드 19041) 이상 또는 Windows 11
wsl --install명령 실행 가능 여부- WSL 2 커널 업데이트 적용 여부
- BIOS에서 가상화 기능 활성화 여부
- Virtual Machine Platform 기능 활성화 여부
WSL 2가 제대로 깔려 있는지 먼저 확인하기
Docker Desktop의 WSL 2 백엔드는 이름 그대로 WSL 2 위에서 동작합니다. 그래서 WSL 1로 설정된 배포판이 있거나 커널 업데이트가 빠져 있으면 Docker 설치 단계에서 바로 걸립니다. PowerShell을 열고 wsl --set-default-version 2를 실행했을 때 Error: 0x1bc가 뜬다면, 이는 WSL 2에서 커널 구성 요소 업데이트가 필요하다는 신호입니다. 이 경우 https://aka.ms/wsl2kernel 안내에 따라 커널을 수동으로 설치해야 합니다.
설치 자체는 PowerShell(또는 Windows 명령 프롬프트)에서 wsl --install 한 줄로 시작됩니다. 이 명령은 필요한 구성 요소를 켜고 기본 배포판(일반적으로 Ubuntu)까지 받아옵니다. 설치 과정에서 컴퓨터를 다시 시작해야 하고, 재부팅 후 시작 메뉴에서 배포판을 열어 리눅스 사용자 이름과 암호를 만들게 됩니다. 이 계정은 Windows 계정과 별개이며, sudo 관리 명령을 실행할 수 있는 권한을 가집니다.
배포판 설치가 끝났다면 다음 항목을 점검해 두는 편이 좋습니다.
| 점검 항목 | 확인 방법 |
|---|---|
| 기본 WSL 버전 | wsl --set-default-version 2 |
| 배포판 버전 전환 | wsl --set-version Ubuntu 2 |
| 커널 업데이트 필요 | 오류 0x1bc 발생 여부 |
| 가상화 활성화 | BIOS 설정 확인 |
표에서 보듯 배포판별로 버전을 따로 지정할 수 있습니다. 기본이 아닌 배포판에서 문제가 생기면 wsl -d <DistroName> -u root 형태로 루트 디렉터리에 접속해 점검할 수 있습니다.
Docker 설치 전에 챙겨야 할 윈도우 기능
WSL 2가 정상 동작해도 Virtual Machine Platform 기능이 꺼져 있으면 Docker는 실행되지 않습니다. 이 기능은 Windows 기능 켜기/끄기에서 활성화하며, BIOS 단계에서 CPU 가상화가 켜져 있어야 합니다. PC 제조사마다 BIOS 진입 키와 메뉴 이름이 다르므로, 가상화 설정은 해당 제조사 안내를 따르는 것이 안전합니다.
가상 머신 위에서 윈도우를 쓰는 환경이라면 중첩 가상화를 수동으로 켜야 합니다. Hyper-V 관리자에서 가상 머신 이름을 확인한 뒤, 관리자 권한 PowerShell에서 해당 이름을 지정해 중첩 가상화를 활성화하는 절차가 필요합니다. 이 단계를 건너뛰면 WSL 2 자체가 올라오지 않아 Docker 설치도 진행되지 않습니다.
WSL 관련 문제는 GitHub의 WSL 제품 리포지토리에 다수 보고되어 있습니다. 검색 창에서 "state:open"을 빼면 이미 해결된 이슈까지 함께 볼 수 있으니, 같은 증상을 겪고 있는지 먼저 검색해 보는 편이 빠릅니다.
설치 후 자주 만나는 오류 코드 정리
Docker를 포함한 WSL 기반 도구를 쓰다 보면 특정 오류 코드에서 멈추는 경우가 있습니다. 참고 자료에서 확인된 대표적인 사례는 다음과 같습니다.
| 오류 코드 | 의미 |
|---|---|
| 0x8007019e | WslRegisterDistribution 실패 |
| 0x80070003 | 설치 실패 |
| 0x80370102 | 설치 실패 |
| 0x1bc | 커널 업데이트 필요 |
0x80070003이나 0x80370102처럼 설치 실패 계열은 대개 WSL 기능이 켜져 있지 않거나 빌드 버전이 18362 미만인 경우에 나타납니다. 이때는 관리자 권한 PowerShell에서 WSL 활성화 명령을 다시 실행하고 재부팅해야 합니다.
업데이트를 시도할 때 오류가 나는 경우도 있습니다. wsl --set-version Ubuntu 2 같은 명령의 옵션이 잘못 입력됐을 때 발생하며, 명령 구문을 다시 확인하면 해결됩니다. 배포판의 LocalState 폴더 경로(C:\Users\<사용자명>\AppData\Local\Packages\...)에 접근해야 하는 상황이라면, 이 문제는 WSL Docs GitHub 스레드 #4103에서 업데이트된 정보를 확인할 수 있습니다.
WSL과 Windows 사이 파일 작업, 어디에 저장할까
Docker 볼륨이나 소스 코드를 다룰 때 파일을 어디에 두느냐에 따라 성능 차이가 납니다. 참고 자료에 따르면 가장 빠른 성능을 위해서는 Linux 명령줄(Ubuntu, openSUSE 등)에서 Linux 도구로 작업할 경우 WSL 파일 시스템에 파일을 저장하는 것이 좋습니다. 반대로 Windows 도구를 쓰면서 PowerShell이나 명령 프롬프트에서 작업한다면 Windows 쪽에 두는 편이 맞습니다.
탐색기에서 WSL 프로젝트 폴더를 열고 싶다면 리눅스 셸에서 explorer.exe .를 입력하면 됩니다. 이때 명령 뒤에 마침표를 반드시 붙여야 현재 디렉터리가 열립니다. 여러 명령줄을 오가며 작업한다면 Windows Terminal에서 WSL을 사용하는 구성이 권장되며, 새 배포판을 설치할 때마다 해당 배포판용 인스턴스가 자동으로 생성됩니다.
Q. Docker 설치 전에 WSL을 꼭 먼저 깔아야 하나요?
Docker Desktop이 WSL 2 백엔드를 사용하기 때문에, WSL 2가 정상 동작하지 않으면 설치 단계에서 막힙니다. 순서를 바꾸기보다 WSL 2 활성화와 커널 업데이트를 먼저 끝내는 편이 시행착오가 적습니다.
Q. wsl --install은 어떤 윈도우에서 실행되나요?
Windows 10 버전 2004(빌드 19041) 이상 또는 Windows 11에서 사용할 수 있습니다. 이보다 낮은 버전이라면 수동 설치 절차를 따라야 합니다.
Q. 리눅스 배포판 암호를 잊어버리면 어떻게 하나요?
PowerShell에서 wsl -u root로 루트 디렉터리에 접속한 뒤 passwd <username> 명령으로 재설정할 수 있습니다. 기본이 아닌 배포판이라면 wsl -d <DistroName> -u root 형태로 대상 배포판을 지정합니다.
Q. WSL에서 윈도우 실행 파일이 안 열릴 때는?
리눅스 셸에서 echo $PATH를 실행해 Win32 경로(예: /mnt/c/Windows)가 포함되어 있는지 확인합니다. 이 경로가 빠져 있으면 interop에서 .exe 파일을 찾지 못합니다.
Docker로 넘어가기 전 마지막 점검
정리하면, 윈도우에 Docker를 올리는 작업은 WSL 2 활성화 → 커널 업데이트 → Virtual Machine Platform 확인 → 배포판 버전 2 지정이라는 순서로 이어집니다. 이 중 하나라도 빠지면 설치 도중 오류 코드로 되돌아오게 됩니다. 배포판을 추가하거나 재설치할 때마다 리눅스 사용자 계정을 새로 만들어야 한다는 점도 기억해 두면 좋습니다. 이 계정은 Windows 사용자 계정과 공유되지 않습니다.
WSL 환경이 안정적으로 자리 잡았다면, 그 위에서 Docker Desktop을 설치하고 컨테이너를 실행하는 단계로 넘어갈 수 있습니다.