Docker 설치 문제 해결 가이드 2025: permission denied부터 정상 실행까지

Docker를 세 번째 설치하면서 첫 번째에는 WSL 2 오류가 났고, 두 번째에는 데몬이 아무리 해도 시작되지 않았습니다. 겨우 설치를 끝냈더니 이번에는 docker ps에서 permission denied가 발생했습니다.

Docker 설치는 원래 간단해야 합니다. 설치 파일을 내려받고 두 번 클릭한 뒤 다음 단계로 넘어가면 끝이어야 하죠. 하지만 실제로는 Windows에서 WSL 2와 Hyper-V를 설정해야 하고, Mac에서는 Intel과 Apple 칩 버전을 구분해야 하며, Linux에서는 온갖 의존성 패키지와 사용자 그룹 권한 문제를 마주칩니다. 플랫폼마다 저마다의 함정이 있습니다.

이 글은 제가 직접 겪은 문제를 돌아보며 정리한 기록입니다. Windows, Mac, Linux 세 플랫폼에서 가장 자주 발생하는 문제 10여 가지와 2025년 기준 해결 방법을 모두 모았습니다. 2020~2022년에 작성된 튜토리얼 중 상당수는 이미 낡았습니다. 어떤 플랫폼에서 어떤 오류를 겪고 있든 아래에서 자신에게 맞는 해결책을 찾을 수 있을 겁니다.

Windows에서 자주 발생하는 문제

Windows에서 Docker를 설치하는 과정은 대부분 WSL 2 및 Hyper-V와 씨름하는 일입니다. 현재 Docker Desktop은 WSL 2 백엔드를 필수로 요구합니다. 운영체제 버전이 맞지 않거나 가상화가 꺼져 있으면 이해하기 어려운 오류 메시지를 계속 보게 됩니다.

문제 1: WSL 2 설치 미완료

Windows 사용자가 가장 자주 겪는 문제입니다. Docker Desktop 설치를 누르면 “WSL 2 installation is incomplete”라는 팝업만 나타나고, 별다른 설명도 없이 사용자를 당황하게 합니다.

오류 예시:

Docker Desktop requires WSL 2 backend
WSL 2 installation is incomplete

원인은 세 가지입니다. Windows 버전이 너무 오래됐거나(10.0.19041 미만), WSL 기능이 아예 켜져 있지 않거나, BIOS에서 가상화가 비활성화된 경우입니다.

해결 방법:

첫째, Windows 버전을 확인합니다. Win+R을 누르고 winver를 입력한 뒤 Enter를 누릅니다. 적어도 Windows 10 22H2(build 19045) 또는 Windows 11 23H2(build 22631 이상)여야 합니다. 이보다 낮다면 먼저 운영체제를 업그레이드해야 합니다.

둘째, WSL 기능을 켭니다. 제어판 → 프로그램 및 기능 → Windows 기능 켜기/끄기로 이동해 “Linux용 Windows 하위 시스템”과 “가상 머신 플랫폼”을 모두 선택합니다. 이 단계가 끝나면 반드시 재부팅해야 합니다.

셋째, WSL 버전을 업데이트합니다. 재부팅 후 PowerShell을 관리자 권한으로 열고 다음 명령을 실행합니다.

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

첫 번째 명령은 WSL을 최신 버전으로 업데이트하고(2.1.5 이상 필요), 두 번째 명령은 WSL 2를 기본값으로 설정합니다.

그래도 해결되지 않으면 BIOS를 확인해야 합니다. 컴퓨터를 재부팅하고 Del 또는 F2 키를 눌러(메인보드 제조사에 따라 다름) Virtualization Technology나 Intel VT-x/AMD-V 옵션을 찾은 다음 Enabled로 변경합니다. Intel에서는 VT-x, AMD에서는 AMD-V라고 부르지만 의미는 같습니다.

문제 2: Hyper-V 충돌

때로는 다음과 같은 이상한 오류가 나타납니다.

HCS_E_HYPERV_NOT_INSTALLED
Docker Desktop - Unexpected WSL error

Hyper-V가 설치되지 않았거나 다른 가상화 소프트웨어와 충돌한 경우입니다. Docker Desktop의 하위 계층은 Hyper-V 또는 WSL 2에 의존하므로 VMware나 VirtualBox를 함께 설치하면 충돌할 수 있습니다.

해결 방법:

Hyper-V가 꺼져 있다면 Windows 기능에서 “Hyper-V”를 찾아 모든 하위 항목을 선택하고 재부팅합니다. Windows Home 에디션은 Hyper-V를 지원하지 않으므로 WSL 2 백엔드만 사용할 수 있습니다.

VMware나 VirtualBox도 함께 사용한다면 하나를 선택해야 할 수 있습니다. Docker Desktop 4.x부터는 상대적으로 호환성이 나은 WSL 2 백엔드를 주로 권장합니다. 이론상 VMware Workstation 15.5 이상은 Hyper-V와 공존할 수 있지만, 직접 써 보니 여전히 사소한 문제가 계속 생겼습니다.

솔직히 가장 간단한 방법은 개발 환경에서는 Docker Desktop(WSL 2)을 사용하고, 운영 환경 또는 테스트 VM에서는 VMware/VirtualBox를 사용해 서로 분리하는 것입니다.

문제 3: 설치 권한 부족

이 오류는 보통 설치 단계에서 바로 표시됩니다.

Installation Failed
Component CommunityInstaller.EnableFeaturesAction failed

원인은 단순합니다. 설치 프로그램을 관리자 권한으로 실행하지 않았거나 백신 프로그램이 차단한 것입니다.

해결 방법:

Docker Desktop 설치 프로그램을 마우스 오른쪽 버튼으로 클릭하고 “관리자 권한으로 실행”을 선택합니다. 설치 중 방화벽이나 백신 프로그램의 알림이 나타나면 허용합니다.

쉽게 놓치는 부분이 하나 더 있습니다. C 드라이브의 여유 공간을 확인하세요. Docker Desktop에는 최소 10GB의 여유 공간이 필요하고 이미지가 늘어나면 더 많은 공간을 차지합니다. C 드라이브가 부족하면 설치 후 Docker 데이터 저장 위치를 바꿀 수 있지만, 이는 별도의 주제입니다.

회사 컴퓨터에 그룹 정책 제한이 걸려 있다면 설치 자체가 불가능할 수 있습니다. 이 경우 IT 부서에 권한을 요청하거나 Linux 하위 시스템에 Docker Engine을 설치하는 방법을 쓸 수 있습니다. 다만 후자는 그래픽 인터페이스가 없습니다.

Mac에서 자주 발생하는 문제

Mac의 Docker 설치는 비교적 수월하지만 Apple이 M1/M2 칩을 출시한 뒤 새로운 문제가 생겼습니다. 가장 흔한 실수는 Intel 버전을 Apple 칩 Mac에 설치하거나 그 반대로 설치하는 것입니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

문제 1: M1/M2 칩 호환성

증상은 아주 뚜렷합니다. Docker Desktop 아이콘이 메뉴 막대에 전혀 나타나지 않거나, 나타나더라도 “Docker Desktop is starting…” 상태에서 영원히 끝나지 않습니다. Terminal에서 docker 명령을 실행하면 다음 오류가 반환됩니다.

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

대부분 잘못된 설치 파일을 내려받았기 때문입니다. Docker 공식 사이트에는 “Mac with Apple chip”과 “Mac with Intel chip” 두 버전이 있으며, 칩에 맞지 않는 버전은 제대로 시작되지 않습니다.

해결 방법:

먼저 Mac의 칩을 확인합니다. 왼쪽 위 Apple 메뉴 → 이 Mac에 관하여에서 “칩” 항목을 봅니다. “Apple M1” 또는 “Apple M2”라면 Apple Silicon 버전이 필요하고, “Intel Core”라면 Intel 버전이 필요합니다.

잘못된 버전을 설치했다면 완전히 제거한 뒤 다시 설치해야 합니다. Terminal을 열고 다음 명령을 실행합니다.

# Docker Desktop 제거
/Applications/Docker.app/Contents/MacOS/uninstall

# 남아 있는 설정 파일 삭제
rm -rf ~/Library/Group\ Containers/group.com.docker
rm -rf ~/Library/Containers/com.docker.docker
rm -rf ~/.docker

이 명령은 Docker와 캐시 데이터를 모두 삭제합니다. 공식 사이트에서 칩에 맞는 버전을 다시 내려받아 설치하세요.

한 가지 더 알아둘 점은 M1/M2 Mac에서 일부 x86 이미지를 실행하려면 Rosetta 2가 필요하다는 것입니다. 설치되어 있지 않다면 다음 명령을 실행합니다.

softwareupdate --install-rosetta

설치 후 Docker Desktop을 재시작하면 정상적으로 시작될 것입니다.

문제 2: 데몬 시작 중 멈춤

Docker Desktop이 시작되고 아이콘도 나타났지만 “Starting…” 상태에서 멈춰 사용할 수 없는 경우가 있습니다. Activity Monitor(활성 상태 보기)에는 Docker 프로세스가 실행 중이라고 나오지만 실제로는 사용할 수 없습니다.

대부분 설정 파일이 손상됐거나 충돌하는 프로세스가 Docker 포트를 점유한 경우입니다.

해결 방법:

첫 번째 방법은 Docker Desktop 초기화입니다. 메뉴 막대의 Docker 아이콘을 누르고 Troubleshoot를 선택한 다음 “Reset to factory defaults”를 클릭합니다. 모든 컨테이너, 이미지, 설정이 삭제되어 출고 상태로 돌아갑니다. 중요한 이미지가 있다면 먼저 백업하세요.

초기화해도 해결되지 않으면 포트 충돌을 확인합니다. Docker가 기본으로 사용하는 2375와 2376 포트를 다른 프로그램이 점유했을 수 있습니다.

# 포트 사용 현황 확인
lsof -i :2375
lsof -i :2376

# 출력이 있으면 PID를 기록하고 프로세스 종료
kill -9 <PID>

충돌하는 프로세스를 종료한 뒤 Docker Desktop을 재시작합니다.

더 강력한 방법은 Docker 가상 머신 파일을 삭제하는 것입니다.

rm -rf ~/Library/Containers/com.docker.docker/Data/vms

이 명령은 Docker가 가상 머신 환경을 강제로 다시 만들게 합니다. 삭제 후 Docker Desktop을 재시작하면 새 VM이 자동으로 생성됩니다.

문제 3: 파일 마운트 권한 거부

컨테이너를 실행하면서 로컬 디렉터리를 마운트할 때 다음 오류가 발생할 수 있습니다.

Error response from daemon: Mounts denied:
The path /Users/yourname/project is not shared from the host and is not known to Docker.

Docker에 마운트할 디렉터리에 접근할 권한이 없기 때문입니다. macOS는 개인정보 보호와 보안을 중요하게 다루므로 Docker는 기본적으로 특정 경로에만 접근할 수 있습니다.

해결 방법:

Docker Desktop 설정 → Resources → File Sharing을 열고 더하기 버튼을 눌러 마운트할 디렉터리를 추가합니다. 일반적으로 /Users, /Volumes, /private, /tmp는 기본 허용되지만 하위 디렉터리는 별도로 추가해야 할 수 있습니다.

그래도 해결되지 않으면 시스템 설정 → 개인정보 보호 및 보안 → 개인정보 보호 → 전체 디스크 접근 권한에서 Docker Desktop이 선택되어 있는지 확인합니다. macOS 14.3 이상은 권한 관리가 더 엄격하므로 이 단계를 놓치지 마세요.

외장 하드 디스크나 네트워크 공유 디렉터리를 마운트할 때도 별도 설정이 필요할 수 있습니다. 외장 하드 디스크의 경로는 일반적으로 /Volumes 아래에 있으므로 이 경로를 추가합니다.

Linux에서 자주 발생하는 문제

Docker는 원래 Linux를 위해 만들어졌으므로 이론상 Linux에서 설치가 가장 간단해야 합니다. 하지만 실제로는 문제도 적지 않으며 특히 권한과 의존성 패키지에서 자주 막힙니다.

문제 1: Permission Denied(가장 자주 발생)

거의 모든 Linux 초보자가 겪는 오류입니다. Docker를 설치하고 기대에 차서 docker ps를 실행하면 다음 메시지가 나타납니다.

docker: Got permission denied while trying to connect to the Docker daemon socket
at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/...":
dial unix /var/run/docker.sock: connect: permission denied.

긴 오류 메시지를 보면 당황하기 쉽습니다. 원인은 Docker 데몬이 root 권한으로 실행되는데 현재 사용자에게 /var/run/docker.sock 소켓 파일에 접근할 권한이 없기 때문입니다.

해결 방법:

사용자를 docker 사용자 그룹에 추가합니다.

sudo usermod -aG docker $USER

이 명령은 현재 사용자($USER)를 docker 그룹(-aG docker)에 추가합니다. 하지만 여기서 끝이 아닙니다.

사용자 그룹 변경은 즉시 적용되지 않으므로 다시 로그인하거나 그룹 정보를 갱신해야 합니다.

newgrp docker

또는 로그아웃한 뒤 다시 로그인합니다. 많은 사람이 그룹만 바꾸고 재로그인하지 않은 채 오류가 계속되자 해결 방법이 틀렸다고 생각합니다.

적용 여부를 확인합니다.

groups

출력에 docker가 있으면 설정이 완료된 것입니다. 다시 docker ps를 실행하면 더 이상 오류가 발생하지 않아야 합니다.

다만, 보안상 주의해야 할 점이 있습니다. 사용자를 docker 그룹에 넣는 것은 사실상 root 권한을 주는 것과 같습니다. Docker가 전체 파일 시스템에 접근할 수 있기 때문입니다. 개인 개발용 컴퓨터에서는 큰 문제가 없지만 운영 서버에서는 신중해야 합니다.

그래도 해결되지 않으면 소켓 파일 권한을 확인합니다.

ls -l /var/run/docker.sock

정상이라면 srw-rw---- 1 root docker가 표시됩니다. 그렇지 않다면 수동으로 변경할 수 있습니다.

sudo chmod 666 /var/run/docker.sock

하지만 이는 임시 해결책이며 재부팅하면 사라집니다. 올바른 방법은 사용자를 그룹에 추가하는 것입니다.

문제 2: 의존성 패키지 누락(Ubuntu/Debian 계열)

이 오류는 일반적으로 설치 단계에서 발생합니다.

docker-desktop : Depends: docker-ce-cli but it is not installable
The following packages have unmet dependencies:
 docker-desktop : Depends: pass but it is not installable
                  Depends: uidmap but it is not installable
                  Depends: gnome-terminal but it is not installable

여러 패키지가 빠진 것처럼 보이지만 근본 원인은 Docker 공식 저장소를 추가하지 않은 것입니다. 시스템 기본 apt 저장소에 Docker가 없거나 버전이 너무 오래됐습니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

해결 방법(Ubuntu 기준):

먼저 기존 버전이 있다면 제거합니다.

sudo apt-get remove docker docker-engine docker.io containerd runc

그다음 Docker 공식 저장소를 설정합니다. 많은 튜토리얼이 빠뜨리거나 지나치게 간단히 설명하는 중요한 단계입니다.

# apt 패키지 인덱스 업데이트
sudo apt-get update

# 필수 의존성 패키지 설치
sudo apt-get install ca-certificates curl gnupg lsb-release

# Docker 공식 GPG 키 추가
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Docker 저장소 설정
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

마지막 줄의 $(lsb_release -cs)는 Ubuntu 버전 코드명(예: jammy, focal)을 자동으로 감지합니다. Linux Mint를 사용한다면 주의가 필요합니다. Mint는 Ubuntu 기반이지만 버전 번호가 다릅니다. /etc/os-release 파일에서 UBUNTU_CODENAME 값을 확인하고 Mint 자체 버전 번호 대신 사용하세요.

저장소를 추가한 뒤 다시 업데이트하고 설치합니다.

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

이제 Docker 공식 저장소에서 내려받으므로 의존성 패키지도 해결됩니다. 설치 후 docker --version으로 확인합니다.

문제 3: 데몬 시작 실패

Docker 설치 후 명령을 실행했을 때 다음 메시지가 표시될 수 있습니다.

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

Mac의 문제와 비슷하지만 Linux에서는 데몬을 systemd로 관리하므로 확인 방법이 다릅니다.

해결 방법:

먼저 Docker 서비스 상태를 확인합니다.

sudo systemctl status docker

inactive (dead) 또는 failed가 표시되면 서비스가 시작되지 않았거나 시작에 실패한 것입니다. 수동으로 시작합니다.

sudo systemctl start docker
sudo systemctl enable docker  # 부팅 시 자동 시작 설정

시작에 실패하면 상세 로그를 확인합니다.

sudo journalctl -u docker.service -n 50

최근 로그 50줄이 표시되며, 일반적으로 구체적인 오류 원인을 찾을 수 있습니다.

흔한 하위 문제는 다음과 같습니다.

SELinux 충돌(CentOS/RHEL):
로그에 SELinux 관련 오류가 있다면 임시로 비활성화해 봅니다.

sudo setenforce Permissive

이 설정은 임시이므로 재부팅 후 원래대로 돌아옵니다. 영구적으로 끄려면 /etc/selinux/config를 수정해야 하지만, 운영 환경에서는 SELinux를 끄기보다 정책을 올바르게 설정하는 편이 좋습니다.

설정 파일 문법 오류:
/etc/docker/daemon.json을 수정했다면 JSON 문법이 올바른지 확인합니다. 쉼표 하나가 빠지거나 따옴표가 하나 더 들어가도 시작에 실패합니다. jsonlint 또는 온라인 도구로 검증하세요.

방화벽 차단:
일부 Linux 배포판의 엄격한 방화벽 규칙이 Docker를 차단할 수 있습니다. 테스트를 위해 임시로 방화벽을 끕니다.

sudo systemctl stop firewalld  # CentOS/RHEL
sudo ufw disable              # Ubuntu

방화벽을 끈 뒤 시작할 수 있다면 방화벽이 원인이므로 Docker를 허용하도록 규칙을 설정해야 합니다.

문제 4: 포트 충돌

비교적 드문 문제지만 발생하면 해결하기 까다롭습니다.

Error starting daemon: error initializing graphdriver: driver not supported
bind: address already in use

일반적으로 Docker의 기본 포트(2375 또는 2376)를 다른 프로그램이 사용 중이거나 원격 접근을 설정하는 과정에서 포트가 충돌한 경우입니다.

해결 방법:

포트 사용 현황을 확인합니다.

sudo netstat -tulnp | grep 2375
sudo netstat -tulnp | grep 2376

출력이 있다면 PID를 기록하고 해당 프로세스를 종료합니다.

sudo kill -9 <PID>

Docker에 원격으로 접근해야 한다면(보안 위험 때문에 권장하지 않음) 수신 포트를 바꿀 수 있습니다. /etc/docker/daemon.json을 수정합니다.

{
  "hosts": ["unix:///var/run/docker.sock", "tcp://127.0.0.1:2376"]
}

여기서는 상대적으로 안전한 로컬 루프백 주소 127.0.0.1에서만 수신합니다. 모든 인터페이스(0.0.0.0)에서 수신하려면 반드시 TLS 암호화를 설정하고 보호되지 않은 상태로 두지 마세요.

설정을 변경한 뒤 Docker를 재시작합니다.

sudo systemctl daemon-reload
sudo systemctl restart docker

주의할 점이 있습니다. daemon.json과 systemd 서비스 파일 양쪽에 hosts를 동시에 설정하면 충돌합니다. /lib/systemd/system/docker.service를 확인하고 ExecStart 줄에 -H 매개변수가 있다면 주석 처리한 뒤 daemon.json에만 설정하세요.

공통 문제와 모범 사례

어떤 플랫폼을 사용하든 Docker 설치 후 몇 가지 공통 검증과 설정 단계를 거치면 나중에 생길 문제를 크게 줄일 수 있습니다.

설치 성공 여부 검증

바로 사용하기 전에 Docker가 제대로 설치됐는지 확인하세요. 다음 명령을 실행합니다.

# Docker 버전 확인
docker --version

# Docker Compose 버전 확인(신규 버전은 Docker에 통합됨)
docker compose version

# 테스트 컨테이너 실행(공식 Hello World)
docker run hello-world

# 시스템 정보 확인
docker info

docker run hello-world는 작은 이미지를 내려받아 실행합니다. “Hello from Docker!”가 보이면 정상입니다. docker info에서는 스토리지 드라이버, 로그 드라이버, 컨테이너 수 등 자세한 정보를 확인할 수 있어 문제가 생겼을 때 유용합니다.

이미지 미러 설정(중국 내 사용자는 필수)

중국에서 이미지 미러를 설정하지 않으면 이미지를 가져오는 속도가 매우 느릴 수 있습니다. 중국 내에서는 Docker Hub 공식 소스 연결이 불안정하고 자주 시간 초과가 발생합니다.

Docker 설정 파일을 수정합니다. Linux에서는 /etc/docker/daemon.json, Windows/Mac에서는 Docker Desktop 설정의 Docker Engine 탭입니다.

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://registry.docker-cn.com"
  ]
}

저장한 뒤 Docker를 재시작합니다.

# Linux
sudo systemctl restart docker

# Mac/Windows: Docker 아이콘을 마우스 오른쪽 버튼으로 클릭 → Restart

적용 여부를 확인합니다.

docker info | grep -A 5 "Registry Mirrors"

설정한 미러 주소가 표시되어야 합니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

중국 내 공개 미러도 때때로 불안정하므로 예비 주소를 여러 개 설정하는 것이 좋습니다. Alibaba Cloud Container Registry처럼 계정 등록이 필요한 미러도 있지만 속도는 확실히 더 빠릅니다.

로그 크기 제한(디스크가 가득 차는 문제 방지)

Docker 컨테이너 로그는 기본적으로 크기 제한이 없습니다. 장시간 실행하는 컨테이너가 수십 GB의 로그를 만들어 디스크를 가득 채울 수 있습니다. 저도 서버 디스크가 가득 차 모든 컨테이너가 중단된 일을 겪었습니다.

daemon.json에 다음 로그 설정을 추가합니다.

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

각 컨테이너의 로그 파일을 최대 10MB로 제한하고 최근 파일 3개를 보관한다는 의미입니다. 10MB를 넘으면 자동으로 순환하고 오래된 로그는 삭제됩니다.

로그를 장기간 보관해야 한다면 로컬에 직접 저장하기보다 ELK나 Loki 같은 로그 시스템을 사용하는 것이 좋습니다.

스토리지 드라이버 설정

스토리지 드라이버에 따라 성능 차이가 큽니다. Linux에서는 현재 가장 빠른 overlay2를 권장합니다. 대부분의 최신 시스템은 기본으로 사용하지만 오래된 버전은 성능이 훨씬 낮은 devicemapper나 aufs를 사용할 수 있습니다.

현재 스토리지 드라이버를 확인합니다.

docker info | grep "Storage Driver"

overlay2가 아니라면 daemon.json에 추가합니다.

{
  "storage-driver": "overlay2"
}

스토리지 드라이버를 바꾸려면 Docker를 재시작해야 하며 모든 컨테이너와 이미지 데이터가 삭제됩니다. 중요한 내용은 먼저 백업하세요.

문제를 피하는 몇 가지 원칙

직접 문제를 겪으며 정리한 경험은 다음과 같습니다.

1. 공식 문서를 먼저 확인하세요. Docker 공식 문서(docs.docker.com)는 설명이 명확합니다. 검색 결과의 많은 튜토리얼은 다른 글을 베끼다가 오류까지 옮긴 경우가 있습니다. 문제가 생기면 먼저 공식 문서를 찾아보는 편이 시간을 아낍니다.

2. 튜토리얼 작성 시점을 확인하세요. Docker는 빠르게 업데이트되므로 20202022년 튜토리얼 중 상당수는 이미 낡았습니다. 게시 날짜를 먼저 보고 최근 12년 안에 작성된 내용을 우선하세요.

3. docker info와 로그를 적극 활용하세요. docker info에서는 시스템 설정을, docker logs <컨테이너ID>에서는 컨테이너 출력을, journalctl -u docker.service(Linux)에서는 데몬 로그를 볼 수 있습니다. 문제의 90%는 로그에 단서가 있습니다.

4. 가상 머신 안에 Docker Desktop을 설치하지 마세요. Docker Desktop 자체가 가상 머신에서 동작합니다. 가상 머신 안에 다시 설치하면 중첩 가상화 때문에 성능이 매우 낮고 예상치 못한 오류도 쉽게 발생합니다. 가상 머신에는 Docker Engine을 직접 설치하는 것을 권장합니다.

5. root로 컨테이너를 실행하지 마세요. 일반 사용자로 실행할 수 있는 컨테이너를 root로 실행하지 않는 것이 보안 모범 사례입니다. 편의상 root를 쓰는 사람이 많지만 운영 환경에서는 절대 피해야 합니다.

빠른 점검 체크리스트

Docker 문제를 어디서부터 확인해야 할지 모르겠다면 다음 순서대로 점검하세요. 일반적인 문제의 90%는 원인을 찾을 수 있습니다.

1단계: 기본 환경 확인

• Docker 버전이 충분히 최신인가요? docker --version을 실행하고 최신 안정 버전 사용을 권장합니다.
• 운영체제 버전이 요구 사항을 충족하나요? Windows 10 19045 이상/Windows 11 22631 이상, macOS 13 이상, Ubuntu 20.04 이상이어야 합니다.
• 디스크 공간이 충분한가요? 최소 10GB를 남겨 두고 df -h(Linux/Mac) 또는 파일 탐색기(Windows)로 확인합니다.

2단계: 권한과 사용자 그룹 확인(Linux/Mac)

• 현재 사용자가 docker 그룹에 있나요? groups를 실행하면 docker가 보여야 합니다.
• 그룹을 변경한 뒤 다시 로그인했나요? 많은 사람이 놓치는 단계입니다. newgrp docker를 실행하거나 로그아웃 후 다시 로그인하세요.
• 소켓 파일 권한이 올바른가요? ls -l /var/run/docker.sock을 실행했을 때 srw-rw---- 1 root docker가 표시되어야 합니다.

3단계: 서비스와 프로세스 확인

• Docker 데몬이 실행 중인가요?
  • Linux: sudo systemctl status docker
  • Mac: Activity Monitor에서 Docker 검색
  • Windows: 작업 관리자에서 Docker Desktop 검색
• 포트 충돌이 있나요? netstat -tulnp | grep docker(Linux) 또는 lsof -i :2375(Mac)를 실행합니다.
• 방화벽이 차단했나요? 테스트를 위해 임시로 방화벽을 끕니다(sudo systemctl stop firewalld 또는 sudo ufw disable).

4단계: 설정 파일 확인

• daemon.json 문법이 올바른가요? JSON 검증 도구로 확인하거나 파일을 백업한 뒤 삭제하고 Docker를 재시작해 봅니다.
• hosts 설정이 중복되지 않았나요? daemon.json과 systemd 서비스 파일에 동시에 설정하지 마세요.
• 이미지 미러에 접근할 수 있나요? ping registry.docker-cn.com 또는 curl https://docker.m.daocloud.io로 확인합니다.

5단계: 상세 로그 확인

가장 중요한 단계입니다. 로그에는 대개 정확한 오류 정보가 있습니다.

• Linux: sudo journalctl -u docker.service -n 50
• Mac: ~/Library/Containers/com.docker.docker/Data/log/ 디렉터리의 로그 파일
• Windows: 이벤트 뷰어 → 응용 프로그램 및 서비스 로그 → Docker Desktop

로그를 이해하기 어렵다면 전체 오류 메시지를 복사해 Google에서 검색하세요. 같은 문제를 겪은 사람이 있을 가능성이 큽니다. 영어로 검색하면 더 정확한 결과를 얻을 수 있습니다.

6단계: 최종 조치(다른 방법으로 해결되지 않을 때)

다음과 같은 강력한 조치를 순서대로 시도합니다.

1. Docker Desktop을 출고 상태로 초기화(Docker Desktop 설정 → Troubleshoot → Reset to factory defaults)
2. 완전히 제거한 뒤 다시 설치(설정 파일과 캐시 디렉터리도 삭제)
3. 백신 프로그램이 차단했는지 확인(임시로 끈 뒤 테스트)
4. 다른 버전 사용(최신 버전이 안 되면 조금 이전의 안정 버전 시도)

그래도 해결되지 않으면 시스템 정보, Docker 버전, 전체 오류 로그를 Docker 공식 포럼이나 Stack Overflow에 올리세요. 커뮤니티의 도움을 받을 수 있습니다.

결론

Docker 설치는 어렵기도 하고 단순하기도 합니다. Windows는 WSL 2와 가상화, Mac은 칩 버전, Linux는 권한과 의존성 패키지라는 저마다의 함정이 있어 어렵습니다. 반면 오류의 원인만 알면 정해진 해결 방법을 따라 고칠 수 있다는 점에서는 단순합니다.

이 글에서 다룬 permission denied, 데몬 시작 실패, 의존성 패키지 누락 문제는 Docker 설치 오류의 약 80%를 차지합니다. 나머지 20%는 특수한 환경 문제일 수 있지만 로그를 읽고 문서를 확인하며 Google에서 영어로 검색하는 방법을 익히면 하나씩 해결할 수 있습니다.

마지막으로 몇 가지를 권합니다.

Docker를 설치하자마자 사용하기보다 먼저 docker run hello-world로 검증하세요. 중국 내 사용자는 이미지 미러를 설정해야 이미지를 가져오는 속도가 지나치게 느려지는 일을 피할 수 있습니다. 나중에 디스크가 가득 찬 원인을 찾아 헤매지 않도록 로그 크기 제한도 설정하는 것이 좋습니다.

문제가 생겨도 당황하지 말고 이 글의 빠른 점검 체크리스트를 한 번 따라가 보세요. 대부분은 스스로 해결할 수 있습니다. 그래도 해결되지 않으면 Docker 공식 포럼이나 Stack Overflow에서 도움을 요청하되, “Docker가 설치되지 않아요”라고만 묻지 말고 전체 오류 정보와 운영체제 버전을 함께 올리세요.

이제 직접 시도해 보세요. 이 글이 문제 해결에 도움이 됐다면 Docker 설치 때문에 고생하는 다른 사람에게도 공유해 주세요. 모두가 시행착오를 조금씩 줄이면 개발 효율도 함께 높아질 것입니다.