Cannot connect to the Docker daemon 해결: Docker Desktop·context·서비스 점검

AI로 직접 제작한 개념 일러스트입니다. 엔진 실행 상태와 클라이언트의 연결 대상을 나누어 점검하는 순서를 설명합니다.

터미널에서 docker ps를 실행했는데 “Cannot connect to the Docker daemon” 오류가 나오나요? Docker 명령이 설치되어 있다는 사실만으로 컨테이너 엔진이 실행 중인 것은 아닙니다. 엔진이 멈췄거나, 명령줄 클라이언트가 다른 엔진 주소를 바라보는 경우부터 구분해야 합니다. 이 글은 Docker Desktop을 사용하는 macOS·Windows와 Docker Engine을 사용하는 Linux의 점검 순서를 나누어 설명합니다. 처음부터 재설치하거나 데이터를 초기화하기 전에 연결 대상과 서비스 상태를 확인하세요.

1. 오류 메시지에서 연결 대상부터 읽기

Docker 데몬 문제 해결 문서는 엔진이 실행 중인지와 클라이언트가 올바른 주소로 연결하는지를 나누어 확인하도록 안내합니다. 오류에 unix 소켓이나 tcp 주소가 표시된다면 그 주소를 기록하세요. 원격 엔진을 사용하는 환경에서는 로컬 Docker Desktop의 실행 여부만 확인해서는 원인을 찾을 수 없습니다. 반대로 로컬 개발 환경인데 오래된 원격 주소가 남아 있다면 엔진이 정상이어도 연결에 실패할 수 있습니다.

“permission denied”는 소켓 접근 권한을 확인할 문제이므로 Docker 소켓 권한 오류 점검 글을 함께 보세요. 이미지 실행 단계의 “exec format error”는 다른 진단 경로가 필요하며 amd64·arm64 실행 형식 오류 글에서 다룹니다. 오류가 발생한 명령, 표시된 주소, 운영체제와 Docker 사용 방식을 함께 남기면 같은 증상처럼 보이는 문제를 구분하기 쉽습니다.

관찰한 상황	먼저 확인할 곳	다음 판단
클라이언트 버전만 표시되고 Server 연결 실패	엔진 실행 상태와 context	CLI 설치와 엔진 실행을 분리
Docker Desktop은 실행 중인데 연결 실패	현재 context·환경 변수·오류 주소	실제 Desktop 엔진을 바라보는지 확인
Linux 시스템 서비스가 inactive	서비스 로그·중지 이유	의도된 중지인지 확인 후 시작 검토
Rootless 설치 환경	사용자 서비스·Rootless context	시스템 서비스와 별도 점검
permission denied가 명시됨	소켓 권한과 실행 사용자	연결 불가만 보고 재설치하지 않기
CI 작업 안에서만 실패	러너의 엔진 연결 방식	호스트·작업 컨테이너의 경계 확인

2. 모든 환경에서 연결 대상 확인하기

먼저 다음 조회 명령으로 클라이언트와 서버 정보를 나누어 확인합니다. docker version은 엔진에 연결할 수 없으면 Server 정보를 얻지 못할 수 있습니다. docker context ls에서 선택 표시와 엔드포인트를 확인하고, Docker context 공식 문서에 따라 의도한 엔진과 일치하는지 비교하세요. 아래 명령은 설정을 바꾸지 않습니다.

docker version
docker context ls
docker context show

셸에 설정된 DOCKER_HOST나 DOCKER_CONTEXT도 확인합니다. 현재 context 이름만 보고 결론을 내리지 말고 환경 변수와 명령 옵션을 함께 보세요. 아래 두 블록은 셸이 다르므로 자신의 환경에 맞는 하나를 사용합니다. macOS·Linux의 Bash 또는 zsh에서는 변수가 없으면 값이 출력되지 않을 수 있습니다.

printenv DOCKER_HOST
printenv DOCKER_CONTEXT

Windows PowerShell에서는 다음처럼 조회합니다.

$env:DOCKER_HOST
$env:DOCKER_CONTEXT

설정 충돌이 의심될 때는 Docker CLI 옵션 문서를 기준으로 실제 목록에 있는 context를 명시해 한 번 조회할 수 있습니다. 예를 들어 목록에 desktop-linux가 있고 그것이 원하는 Desktop 엔진을 가리킨다면 “docker --context desktop-linux info”로 비교합니다. 이름이 없거나 다른 엔진을 가리키면 이 예시를 그대로 쓰지 마세요. 연결된 서버의 운영체제와 엔진 정보까지 확인한 뒤 기본 설정 변경 여부를 판단하는 것이 안전합니다.

3. macOS·Windows Docker Desktop 점검

Docker Desktop 앱을 열고 엔진이 실행 상태에 도달했는지 확인하세요. 설치 파일이나 메뉴 아이콘이 보인다는 것만으로 준비가 끝난 것은 아닙니다. 앱의 오류 안내가 있으면 해당 안내와 진단 정보를 확인하고, 같은 터미널에서 docker version을 다시 조회해 Server 정보가 표시되는지 봅니다. 정상 실행 중인데도 연결이 안 되면 앞 절의 context와 환경 변수를 대조합니다.

Windows에서 WSL 터미널을 사용하는 경우에는 Docker Desktop WSL 안내에 따라 WSL 엔진 설정과 사용 중인 배포판의 연동 여부를 확인합니다. Windows 터미널과 특정 WSL 배포판에서 결과가 다르다면 둘의 context·환경 변수·연동 상태를 나누어 기록하세요. WSL 안에 별도로 설치한 Engine과 Desktop 연동이 섞여 있는지도 구분해야 합니다. 앱에서 보는 엔진과 터미널이 연결하는 엔진이 같은지가 핵심입니다.

Docker Desktop 문제 해결 안내에는 진단과 초기화 메뉴가 구분되어 있습니다. 공장 초기화는 컨테이너와 설정에 영향을 줄 수 있으므로 연결 오류의 첫 조치로 선택하지 마세요. 기존 데이터가 중요하면 보존 범위와 복구 방법을 확인한 뒤 별도 변경 계획을 세워야 합니다. 이 글의 점검은 초기화를 요구하지 않습니다.

4. Linux 시스템 서비스와 Rootless를 구분하기

아래 명령은 systemd로 Docker Engine을 관리하는 Linux 설치를 가정합니다. 다른 서비스 관리자를 쓰는 환경에는 그대로 적용하지 않습니다. 상태와 최근 로그를 먼저 확인하고, 접근 권한이 부족한 조회는 해당 운영 환경의 권한 절차에 따라 수행하세요.

systemctl status docker --no-pager
journalctl -u docker -n 50 --no-pager

서비스가 의도치 않게 중지되어 있고 시작해도 되는 상황이면 Docker 데몬 시작 안내의 “sudo systemctl start docker”를 검토할 수 있습니다. 이는 조회가 아니라 서비스 상태를 바꾸는 작업입니다. 자동 시작 정책이 있는 기존 컨테이너에도 영향이 있을 수 있으므로 운영 서버에서는 중지 이유와 작업 권한을 먼저 확인하세요. 시작에 실패하면 반복 재시작보다 로그에 나타난 저장소·설정·서비스 오류를 좁히는 편이 좋습니다.

Rootless 모드 안내에 따라 설치한 환경에서는 시스템 수준의 docker 서비스와 사용자 서비스를 혼동하지 마세요. “systemctl --user status docker --no-pager”로 해당 사용자의 서비스를 조회하고, 실제 설치된 Rootless context와 엔드포인트를 확인합니다. 시스템 서비스가 없다는 이유만으로 Rootless 설치가 고장 났다고 판단할 수 없습니다. 사용자 ID에 따른 소켓 경로를 임의로 하드코딩하지 않는 것도 중요합니다.

5. 가상 사례: 앱은 정상인데 오래된 연결 주소가 남은 경우

예를 들어 개발자가 예전에 원격 테스트 엔진에 연결한 뒤 로컬 작업으로 돌아왔다고 가정해 보겠습니다. Docker Desktop은 실행 중인데 오류에는 예전 tcp 주소가 표시됩니다. 이때 앱을 재설치하면 원격 주소가 남은 셸 설정을 놓칠 수 있습니다. docker context ls와 환경 변수 조회 결과를 비교하고, 목록에서 확인한 로컬 context를 명시한 조회가 성공하는지 확인합니다. 서버 정보까지 원하는 엔진과 일치하면 셸 프로필이나 프로젝트 도구가 설정한 주소를 찾아 필요한 범위만 수정합니다.

CI에서는 “작업 이미지에 Docker CLI가 있다”와 “작업에서 엔진에 접근할 수 있다”가 별개입니다. 러너가 제공하는 원격 엔진, 별도 데몬 또는 호스트 연결 방식 중 무엇을 쓰는지 문서를 확인해야 합니다. 연결을 만들기 위해 인증 없는 TCP 포트를 열거나 호스트 소켓을 무작정 노출하면 권한 범위가 커질 수 있습니다. 러너의 승인된 연결 방식을 먼저 정하고, 그 대상의 상태와 인증·네트워크 경로를 점검하세요.

6. 자주 묻는 질문

docker --version이 나오면 Docker가 정상인가요?
클라이언트 버전을 보여 주는 결과입니다. 엔진 연결까지 확인하려면 docker version의 Server 정보와 원하는 엔진의 상태를 확인하세요.

sudo를 붙이면 항상 해결되나요?
권한 문제와 엔진 중지·잘못된 엔드포인트는 다릅니다. 특히 Desktop이나 Rootless 환경에서 무조건 실행 사용자를 바꾸면 연결 대상을 더 혼동할 수 있습니다.

context를 바꾸기 전에 무엇을 확인해야 하나요?
목록의 엔드포인트가 원하는 엔진인지, 환경 변수와 명령 옵션이 무엇인지 확인하세요. 가능하면 명시한 context로 먼저 조회하고 서버 정보가 맞는지 검증합니다.

자료 확인: 2026년 10월 4일. 명령과 사례는 진단 방법을 설명하는 예시이며 독자의 장치나 CI에서 실행한 결과가 아닙니다. 엔진 시작과 설정 변경은 조회 결과를 확인한 뒤 해당 환경의 운영 절차에 맞게 수행하세요.