도커 데스크톱 실행 안됨·설치 안됨 해결
Docker Desktop - Unexpected WSL error / WSL 2 installation is incomplete / Docker Desktop stopped
이런 증상일 때
도커 데스크톱을 설치·실행하면 "Docker Desktop - Unexpected WSL error" 또는 "WSL 2 installation is incomplete" 팝업이 뜨거나, 고래 아이콘이 "Docker Desktop is starting…" 에서 몇 분째 멈춰 영원히 안 켜집니다. 윈도우에서 가장 흔하고, 맥은 OS 대규모 업데이트 직후 갑자기 "Docker Desktop is unable to start" 로 안 뜨는 경우가 많습니다.
원인
- CPU 가상화(인텔 VT-x / AMD SVM)가 BIOS·UEFI 에서 꺼져 있음 — 작업관리자 성능 탭에 "가상화: 사용 안 함" 으로 표시
- 윈도우 선택적 기능 "가상 머신 플랫폼"·"Linux용 Windows 하위 시스템(WSL)" 미설치 또는 WSL 커널이 구버전
- WSL2 가 기본 버전이 아니거나 docker-desktop 배포판이 깨짐(WSL distribution docker-desktop is missing)
- 맥: 큰 macOS 업데이트 후 ~/Library 하위 도커 설정·소켓 파일이 꼬여 엔진 기동 실패
- 디스크 여유 공간 부족(10GB 미만)·RAM 부족(4GB 미만)으로 가상 머신 자체가 못 뜸
해결 방법
작업관리자(Ctrl+Shift+Esc) → 성능 → CPU 에서 "가상화: 사용 함" 인지 봅니다. "사용 안 함" 이면 부팅 시 BIOS/UEFI 에 들어가 인텔 VT-x 또는 AMD SVM Mode 를 켜야 합니다. 윈도우 쪽 하이퍼바이저 시작 여부는 아래 명령으로 확인·강제합니다(관리자 PowerShell).
bcdedit /enum | findstr -i hypervisorlaunchtype
bcdedit /set hypervisorlaunchtype auto # Off 로 나오면 실행 후 재부팅도커 데스크톱이 WSL2 백엔드를 쓰려면 이 두 선택적 기능이 켜져 있어야 합니다. 관리자 PowerShell 에서 한 번에 켠 뒤 반드시 재부팅합니다.
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
# 재부팅 후 적용"WSL 2 installation is incomplete" 또는 "Unexpected WSL error" 의 다수는 WSL 커널이 옛버전이라 생깁니다. 커널을 최신화하고 WSL2 를 기본으로 박은 뒤 도커를 재시작하면 잡힙니다.
wsl --update
wsl --set-default-version 2
wsl --shutdown # WSL 완전 종료 후 도커 데스크톱 재시작엔진이 "starting" 에서 멈추면 settings 파일을 지워 초기화합니다(도커가 다음 실행 때 새로 생성). 권한 오류면 현재 계정을 docker-users 그룹에 넣고 재로그인합니다.
del "%APPDATA%\Docker\settings-store.json"
# 관리자 권한:
net localgroup docker-users "%USERNAME%" /add윈도우 사용자명이 한글(예: C:\Users\홍길동)이면 WSL·도커가 한글 경로를 못 읽어 "Unexpected WSL error" 가 반복됩니다. 사용자 계정을 새로 만들기 어렵다면 도커 데이터·WSL 배포판을 영문 경로 드라이브로 옮기고, 프로젝트도 영문 경로(예: D:\dev\app)에 두는 것이 가장 안전합니다. 국내 사내망·도메인 PC 는 절전모드 복귀 후 권한이 풀려 같은 에러가 나므로 WSL 재시작이 필요합니다.
wsl --shutdown
wsl --export docker-desktop-data D:\wsl\ddata.tar # 영문 경로로 백업/이전
# 새 프로젝트는 한글 없는 경로에 생성: mkdir D:\dev\app맥은 OS 업데이트 직후 자주 깨집니다. 먼저 메뉴의 Troubleshoot → "Reset to factory defaults" 를 시도하고, 앱이 아예 안 뜨면 도커 관련 설정 폴더를 직접 지운 뒤(데이터 손실 주의) 재설치합니다. 진단 로그는 com.docker.diagnose 로 수집합니다.
/Applications/Docker.app/Contents/MacOS/com.docker.diagnose gather -upload
# 앱이 안 뜰 때 (컨테이너/이미지 삭제됨, 주의):
rm -rf ~/Library/Group\ Containers/group.com.docker
rm -rf ~/Library/Application\ Support/Docker\ Desktop