[docker] Docker 설치할 때 자주 만나는 오류와 해결법

Docker는 개발 환경을 손쉽게 통일하고 배포를 단순화해 주는 훌륭한 도구입니다.
하지만 설치 과정에서 벽을 만나는 경우가 많습니다.
특히 Windows 사용자라면 가상화 옵션이나 WSL(Windows Subsystem for Linux) 설정 때문에 애를 먹는 일이 잦습니다.
이 글에서는 실제로 많이 보고된 오류와 그 해결법을 정리해 보겠습니다.

 

 

1. Hyper-V 또는 가상화 옵션 문제

Windows에서 Docker Desktop을 실행할 때 가장 흔히 만나는 메시지는 다음과 같습니다

hcs_e_hyperv_not_installed

이는 Hyper-V 또는 BIOS 가상화 기능이 꺼져 있어서 발생하는 오류입니다. 해결 방법은 두 단계로 나눌 수 있습니다.

1. Windows 기능 활성화
   • 시작 메뉴에서 “Windows 기능 켜기/끄기” 검색 → Hyper-V, Windows 하이퍼바이저 플랫폼, 가상 머신 플랫폼 항목 체크 후 재부팅.
2. BIOS에서 가상화 켜기
   • 재부팅 후 BIOS 설정에 진입 → Intel CPU는 Intel VT-x 또는 VMX, AMD CPU는 SVM 옵션을 찾아 활성화 → 저장 후 재부팅.

 

 

2. “The network name cannot be found” 오류

Docker Desktop 실행 시 다음과 같은 에러가 나올 수 있습니다

The network name cannot be found.

이는 WSL2와 Docker Desktop 간의 통합이 꼬였을 때 발생합니다. 해결 방법은 간단합니다.

wsl --unregister docker-desktop
wsl --unregister docker-desktop-data

위 명령어를 PowerShell(관리자 권한)에서 실행한 후, Docker Desktop을 다시 켜면 WSL 배포본이 새로 등록되면서 정상 작동합니다.

 

 

3. 리소스 부족 문제

Docker Desktop은 백그라운드에서 VM 형태로 작동하기 때문에 메모리와 CPU를 많이 차지합니다.

만약 실행 중 다음과 같은 오류를 본다면 리소스 부족 문제일 수 있습니다.

Not enough memory to start Docker Desktop

 

해결 방법

• 불필요한 프로그램 종료 후 다시 실행.
• Docker Desktop 설정 → Resources 메뉴에서 메모리 제한을 늘리기.
• 가능하다면 램 증설 고려.

 

 

4. WSL 버전 호환성 문제

Docker Desktop은 기본적으로 WSL2를 기반으로 실행됩니다.

만약 WSL1만 설치되어 있다면 다음과 같은 오류가 뜹니다.

Please enable the WSL 2 feature

이때는 WSL을 업데이트해야 합니다.

wsl --update
wsl --set-default-version 2

그리고 Ubuntu와 같은 리눅스 배포판을 WSL2로 전환합니다.

wsl --set-version Ubuntu-22.04 2

 

 

5. 파일 경로와 권한 문제

윈도우 환경에서 Dockerfile을 빌드할 때, 파일 경로나 권한 관련 에러가 날 수 있습니다.

COPY failed: file not found in build context

이는 잘못된 경로나 빌드 컨텍스트 문제입니다. 해결책은 다음과 같습니다.

• Dockerfile과 필요한 소스를 같은 디렉터리에 두고, 해당 위치에서 docker build . 실행.
• 경로에 한글이나 공백이 포함되지 않도록 주의.
• Git이나 OneDrive와 동기화되는 폴더는 피하는 것이 안전.

 

 

6. 정리 및 예방 팁

1. 가상화 관련 오류는 대부분 BIOS와 Hyper-V 설정을 확인하면 해결됩니다.
2. 네트워크/WSL 오류는 wsl --unregister 후 Docker Desktop 재실행으로 고쳐지는 경우가 많습니다.
3. 리소스 문제는 Docker Desktop 설정에서 리소스 제한을 조정하거나 불필요한 프로세스 종료로 해결할 수 있습니다.
4. 파일 경로 문제는 한글, 공백 없는 경로에서 빌드하는 습관을 들이세요.

 

 

Docker 설치는 초보자에게 가장 큰 진입 장벽이 될 수 있습니다.

하지만 대부분의 오류는 가상화 설정, WSL 호환성, 리소스 부족, 파일 경로 문제에서 비롯됩니다.

환경만 제대로 갖추면 Docker는 오히려 개발자의 삶을 크게 단순화해 줍니다.

막히는 오류에 좌절하기보다는, 하나씩 점검하며 안정적인 개발 환경을 구축해 보시길 바랍니다.