Windows에 Docker Desktop을 설치했더라도 WSL Ubuntu에서 docker 명령이 바로 실행되지 않을 수 있다. 볼륨 실습을 시작하려고 docker version을 실행했을 때 다음 오류가 표시됐다.
The command 'docker' could not be found in this WSL 2 distro.
We recommend to activate the WSL integration in Docker Desktop settings.
이 글은 Windows의 Docker Desktop과 WSL 2를 연동하는 구성을 기준으로 한다. Ubuntu에 Docker Engine을 직접 설치해 운영하는 구성과는 점검 방법이 다르다. 설치부터 필요한 경우에는 Docker Desktop 설치와 WSL 연동을 참고한다.
1. Docker Desktop 실행 상태 확인#
먼저 Windows 시작 메뉴에서 Docker Desktop을 실행한다. 창을 열었다는 것만으로 엔진이 준비된 것은 아니므로, 하단에 Engine running이 표시될 때까지 기다린다.
Docker Desktop이 실행되지 않았거나 WSL 배포판 연동이 비활성화되어 있으면, WSL에서 docker 명령을 찾지 못하거나 엔진 연결 오류가 발생할 수 있다. 단, 위 오류 메시지만으로 Desktop 미실행이 유일한 원인이라고 단정할 수는 없다. 실행 상태와 배포판 연동 설정을 함께 확인한다.
엔진이 실행 중이면 WSL Ubuntu에서 다시 확인한다.
docker versionClient와 Server 정보가 모두 표시되면 정상이다. 같은 오류가 계속되면 다음 단계에서 현재 사용하는 배포판의 연동 설정을 확인한다.
2. Ubuntu의 WSL integration 활성화#
Docker Desktop에서 Settings → Resources → WSL integration으로 이동한다. 사용할 Ubuntu 배포판을 활성화하고 Apply & restart를 클릭한다. 버전에 따라 적용 버튼의 이름은 다를 수 있다.
위 설정처럼 Enable integration with my default WSL distro를 선택하지 않아도, 아래 배포판 목록에서 Ubuntu를 개별적으로 활성화할 수 있다. Ubuntu를 여러 버전 설치했다면 현재 터미널에서 사용하는 배포판이 활성화되어 있는지 확인한다.
설정 적용이 끝나면 Ubuntu 터미널을 닫았다가 다시 열고 docker version을 실행한다. Docker 공식 문서도 배포판의 WSL 연동을 활성화해야 해당 배포판 터미널에서 Docker 명령을 사용할 수 있다고 안내한다. Docker WSL 2 연동 문서
WSL integration 메뉴가 보이지 않는 경우#
Docker Desktop이 Linux 컨테이너 모드인지 확인한다. Windows 컨테이너 모드를 사용 중이라면 Docker 메뉴에서 Switch to Linux containers로 전환한다.
General에 Use WSL 2 based engine 옵션이 표시되면 활성화 여부를 확인한다. WSL 2 사용 환경에서는 기본 적용되어 옵션이 보이지 않을 수도 있다.
배포판의 WSL 버전은 Windows PowerShell에서 확인할 수 있다.
wsl --list --verbose사용할 Ubuntu 행의 VERSION이 2인지 확인한다. 배포판 이름과 WSL 버전은 구분해서 확인해야 한다.
3. Client와 Server 정보로 정상 연결 확인#
WSL Ubuntu에서 실행한다.
docker version
이번 환경에서는 이후 실행에서 Client와 Server 정보가 모두 출력됐다. Client 버전은 29.8.2, Server는 Docker Desktop 4.94.0으로 표시됐다.
이 결과는 WSL에서 Docker CLI를 실행할 수 있고, Docker 엔진에도 연결됐다는 뜻이다.
4. 오류 메시지에 따라 점검 대상 구분#
docker 명령을 찾지 못하는 경우#
이 글의 could not be found in this WSL 2 distro 메시지나 docker: command not found는 WSL에서 Docker CLI를 정상적으로 사용할 수 없는 상태를 의미한다. 먼저 Desktop 실행 상태, 해당 배포판의 WSL integration, 설정 적용 후 터미널 재실행을 확인한다.
곧바로 Ubuntu에 docker.io를 추가 설치하는 것은 피한다. Desktop 연동을 사용할 계획인데 별도 Engine·CLI를 설치하면 구성과 데이터 위치가 혼재할 수 있다. 이미 직접 설치한 Docker가 있다면 기존 서비스와 데이터부터 확인한다. Docker 설치 방식 충돌 주의사항
Client는 나오지만 Server 연결이 실패하는 경우#
이 경우에는 CLI 자체는 실행되고 있다. 다음과 같은 메시지는 엔진 연결 문제로 구분한다.
Cannot connect to the Docker daemon위 메시지는 구분을 위한 예시이며, 이번 오류 캡처에 나온 메시지는 아니다. Docker Desktop이 Engine running 상태인지 확인하고, 계속 실패하면 WSL에서 연결 대상을 확인한다.
docker context ls
printenv DOCKER_HOST DOCKER_CONTEXT이전에 다른 Docker 엔진을 사용했다면 컨텍스트나 환경변수가 그 엔진을 가리킬 수 있다. 원격 연결용 설정을 무조건 지우거나 기본값으로 변경하지 말고 기존 용도를 먼저 확인한다. 설치 글의 Server 연결 오류 점검도 참고할 수 있다.
마무리#
Docker Desktop 연동 구성에서는 Windows의 엔진 실행 상태와 WSL 배포판 연동 상태를 모두 확인해야 한다. Windows에 설치되어 있다는 사실만으로 현재 Ubuntu 터미널에서도 사용할 수 있다고 판단하지 않는다.
docker version에서 Client와 Server가 모두 출력되면 연결 확인은 끝난다. 이번에는 정상 출력을 확인한 뒤 컨테이너와 볼륨의 데이터 유지 실습을 진행했다.