WSL에서 Docker가 연결되지 않을 때: Docker Desktop Integration 설정법

WSL에서 docker ps, docker version 명령을 실행했는데 Docker가 연결되지 않는다면 가장 먼저 볼 곳은 Docker Desktop의 WSL Integration 설정입니다. Docker Desktop은 Windows에서 실행 중이어도, Ubuntu 같은 WSL 배포판과 연결되지 않으면 WSL 터미널에서는 Docker 명령어가 실패할 수 있습니다.

특히 VSCode Remote WSL에서 Dev Container를 열기 전에 이 문제가 자주 보입니다. Windows 터미널에서는 Docker가 되는데 WSL Ubuntu 터미널에서는 안 되거나, 반대로 VSCode 안에서만 Docker가 잡히지 않는 경우라면 아래 순서대로 확인하면 됩니다.

WSL에서 Docker 명령어가 실패할 때는 Docker Desktop과 사용하는 Linux 배포판이 연결되어 있는지 먼저 확인합니다.

결론: WSL Docker 연결 오류는 Integration 설정부터 확인한다

WSL에서 Docker가 연결되지 않을 때는 Docker를 다시 설치하기보다 연결 지점을 먼저 확인하는 것이 안전합니다. 핵심은 Docker Desktop이 실행 중인지, WSL2 배포판이 맞는지, Docker Desktop의 Settings → Resources → WSL Integration에서 사용하는 Ubuntu 배포판 토글이 켜져 있는지입니다.

자주 보이는 오류 메시지

같은 WSL Docker 연결 문제라도 화면에 나오는 문구는 조금씩 다릅니다. 아래 메시지가 보이면 Docker Desktop과 WSL 사이의 연결 상태를 먼저 확인합니다.

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

docker: command not found

The command 'docker' could not be found in this WSL 2 distro.

Cannot connect to the Docker daemon

Is the docker daemon running?

오류 메시지	가능성이 큰 원인	먼저 볼 곳
docker: command not found	WSL 배포판에 Docker CLI 연결이 안 됨	WSL Integration 토글
Cannot connect to the Docker daemon	Docker Desktop이 꺼졌거나 daemon 연결 실패	Docker Desktop 실행 상태
Is the docker daemon running?	Docker engine 또는 context 연결 문제	Docker context, Linux containers 모드

언제 발생하는 오류인가

이 오류는 Docker 자체가 완전히 고장 났을 때만 생기는 문제가 아닙니다. Windows, WSL, VSCode가 서로 다른 실행 환경을 쓰기 때문에 어느 터미널에서 실행했는지에 따라 결과가 달라질 수 있습니다.

Windows 터미널에서 실행한 경우

PowerShell이나 Windows Terminal의 기본 탭에서 docker 명령을 실행하면 Windows 쪽 Docker CLI가 Docker Desktop과 통신합니다. Docker Desktop이 정상 실행 중이라면 WSL 배포판 설정과 무관하게 동작할 수 있습니다.

WSL Ubuntu 터미널에서 실행한 경우

Ubuntu, Debian 같은 WSL 배포판 안에서 docker 명령을 실행하려면 해당 배포판이 Docker Desktop과 연결되어 있어야 합니다. Docker Desktop 공식 문서에서도 WSL 배포판에서 직접 Docker 명령을 쓰려면 WSL Integration을 활성화해야 한다고 안내합니다.

VSCode Remote WSL에서 실행한 경우

VSCode 왼쪽 아래에 WSL: Ubuntu처럼 표시된 상태라면 터미널은 Windows가 아니라 WSL 안에서 실행됩니다. 이때 Docker 명령이 실패하면 VSCode 문제가 아니라 WSL 배포판과 Docker Desktop 연결 문제일 수 있습니다. Dev Container 실행 중 Is Docker running?이 뜬다면 먼저 WSL 터미널에서 docker version과 docker ps를 확인해 원인을 좁히는 것이 좋습니다.

원인 3가지

1. Docker Desktop에서 WSL Integration이 꺼져 있음

가장 흔한 원인은 Docker Desktop의 WSL Integration 설정이 꺼져 있는 경우입니다. Docker Desktop은 Windows에서 실행 중이어도, 특정 WSL 배포판에 Integration이 켜져 있지 않으면 그 배포판 터미널에서는 Docker CLI가 잡히지 않을 수 있습니다.

2. 사용하는 WSL 배포판이 연결되지 않음

Ubuntu가 여러 개 설치되어 있거나, 배포판 이름이 Ubuntu-22.04, Ubuntu-24.04처럼 나뉘어 있으면 실제로 사용하는 배포판과 Docker Desktop에서 켠 배포판이 다를 수 있습니다. 이 경우 토글이 켜져 있어도 다른 배포판에서 명령을 실행하면 오류가 납니다.

3. WSL 또는 Docker Desktop 재시작이 필요한 상태

설정을 바꾼 직후에는 WSL 세션이 이전 상태를 잡고 있을 수 있습니다. 이때는 WSL을 종료하고 Docker Desktop을 다시 시작한 뒤 확인하는 것이 좋습니다.

빠른 해결 순서

아래 순서대로 진행하면 불필요한 재설치나 초기화를 줄일 수 있습니다. 삭제, reset, factory reset 같은 작업은 마지막 단계에서만 검토합니다.

1. Docker Desktop 실행 확인

Windows에서 Docker Desktop을 먼저 실행합니다. 작업 표시줄 오른쪽 아래 Docker 아이콘이 보이고, Docker Desktop 화면에서 engine이 실행 중인지 확인합니다.

2. Docker Desktop 설정 경로로 이동

Docker Desktop을 열고 아래 경로로 이동합니다.

Docker Desktop
→ Settings
→ Resources
→ WSL Integration

3. 사용하는 WSL 배포판 토글 켜기

Enable integration with my default WSL distro 항목과 아래 배포판 목록을 확인합니다. 실제로 사용하는 Ubuntu 배포판의 토글을 켠 뒤 Apply & Restart 또는 Apply를 누릅니다.

4. WSL 재시작

Windows PowerShell에서 WSL을 종료한 뒤 다시 엽니다.

wsl --shutdown

그 다음 Ubuntu 또는 VSCode Remote WSL 터미널을 다시 열고 Docker 명령을 확인합니다.

5. docker version과 docker ps 확인

docker version
docker ps

docker version에서 Client와 Server 정보가 함께 보이고, docker ps에서 컨테이너 목록 표가 나오면 WSL과 Docker Desktop 연결은 정상입니다.

확인 명령어 정리

어느 지점에서 막혔는지 확인하려면 명령어를 순서대로 실행해 보는 것이 좋습니다. Windows 명령과 WSL 내부 명령을 구분해서 실행해야 결과를 정확히 볼 수 있습니다.

명령어	실행 위치	확인할 내용
wsl -l -v	PowerShell	사용 중인 배포판 이름과 WSL 버전
docker version	WSL 터미널	Client와 Server 연결 여부
docker context ls	WSL 터미널	현재 Docker context
docker ps	WSL 터미널	daemon 연결 최종 확인

wsl -l -v

결과에서 사용하는 배포판의 VERSION이 2인지 확인합니다.

  NAME              STATE           VERSION
* Ubuntu-24.04      Running         2
  docker-desktop    Running         2

만약 사용하는 배포판이 VERSION 1이라면 WSL2로 바꿔야 합니다. 배포판 이름은 실제 화면에 표시된 이름으로 바꿔 입력합니다.

wsl --set-version Ubuntu-24.04 2

새로 설치하는 WSL 배포판을 기본적으로 WSL2로 만들고 싶다면 아래 명령도 확인합니다.

wsl --set-default-version 2

VSCode Remote WSL에서 확인할 것

VSCode에서만 Docker가 안 된다면 먼저 현재 창이 Windows 폴더를 연 상태인지, WSL 배포판에 연결된 상태인지 확인합니다. 왼쪽 아래에 WSL: Ubuntu처럼 표시되어 있어야 Remote WSL 환경입니다.

권장 흐름은 WSL 터미널에서 프로젝트 폴더로 이동한 뒤 VSCode를 여는 방식입니다.

wsl
cd ~/projects/my-app
code .

Docker 공식 문서에서도 WSL2 기반 개발에서는 코드를 기본 Linux 배포판 안에 두고 VSCode로 여는 흐름을 안내합니다. Windows의 C:\ 경로 아래 프로젝트를 WSL에서 무리하게 다루면 파일 접근 속도와 경로 문제가 함께 생길 수 있습니다.

그래도 안 될 때 점검할 것

WSL Integration 메뉴가 보이지 않을 때

Docker Desktop의 Settings → Resources 아래에 WSL Integration이 보이지 않는다면 Docker Desktop이 Windows containers 모드로 되어 있을 수 있습니다. 작업 표시줄의 Docker 메뉴에서 Linux containers 모드로 전환한 뒤 다시 확인합니다.

WSL2가 아닌 배포판일 때

Docker Desktop의 WSL 연동은 WSL2 기준으로 확인하는 것이 좋습니다. wsl -l -v 결과에서 사용하는 배포판이 VERSION 1이라면 WSL2로 변경한 뒤 Docker Desktop을 다시 시작합니다.

Docker Desktop 업데이트가 필요한 경우

오래된 Docker Desktop이나 WSL 버전에서는 연동 문제가 반복될 수 있습니다. Docker Desktop의 업데이트 메뉴와 Windows의 WSL 업데이트 상태를 확인합니다.

wsl --update

Reset은 마지막에 검토하기

Docker Desktop의 Reset, Factory reset은 이미지, 컨테이너, 볼륨, 설정에 영향을 줄 수 있습니다. 단순한 WSL Integration 문제라면 reset보다 설정 토글, WSL 종료, Docker Desktop 재시작을 먼저 진행하는 것이 안전합니다.

재발 방지 설정

WSL Docker 연결 오류는 처음 한 번만 해결하면 끝나는 문제가 아니라, 새 배포판을 설치하거나 Docker Desktop을 업데이트한 뒤 다시 생길 수 있습니다. 아래 기준을 정해두면 같은 문제를 빠르게 구분할 수 있습니다.

상황	확인할 것	권장 대응
새 Ubuntu 배포판 설치	배포판 이름과 WSL Integration 토글	해당 배포판 토글 켜기
Docker Desktop 업데이트 후 오류	Docker Desktop 실행 상태와 Linux containers 모드	Docker Desktop 재시작
VSCode에서만 오류	Remote WSL 연결 여부	WSL 터미널에서 code .로 다시 열기

출처: Docker Docs, Docker Desktop WSL 2 backend on Windows

공식 자료로 더 확인하기

WSL과 Docker Desktop 연결 문제는 Docker Desktop 버전, WSL2 요구 사항, Windows 전용 Integration 설정에 따라 화면과 동작이 달라질 수 있습니다. 설정 경로가 바뀌었거나 오류가 반복된다면 개인 블로그 글보다 Docker와 Microsoft의 공식 문서를 기준으로 현재 요구 사항과 권장 설정을 확인하는 것이 안전합니다.

함께 보면 좋은 글

FAQ

WSL Docker 연결 오류는 재설치보다 Docker Desktop 실행 상태, WSL2 여부, WSL Integration 토글, 재시작 순서로 차분히 좁혀가는 것이 가장 안전합니다.