Docker Desktop을 실행했는데 갑자기 “running wsl distro proxy in Ubuntu distro: running proxy: exit status 1” 오류가 나타나셨나요? Windows 업데이트 후, Docker Desktop 버전 업그레이드 후, 또는 아무 이유 없이 갑자기 발생하는 이 오류 때문에 개발 작업이 중단되어 답답하실 겁니다.

이 글에서는 해당 오류의 정확한 원인을 분석하고, 단계별로 확실하게 해결하는 방법을 알려드립니다. 초보자도 따라할 수 있도록 모든 명령어와 설정 방법을 상세히 설명하니 끝까지 읽어보세요.

오류 메시지 분석: 정확히 무엇이 문제인가?

먼저 발생하는 오류 메시지를 정확히 살펴보겠습니다.

running wsl distro proxy in Ubuntu distro: running proxy: running wslexec: 
An error occurred while running the command. 
DockerDesktop/Wsl/ExecError: c:\windows\system32\wsl.exe -d ubuntu -u root -e 
/mnt/wsl/docker-desktop/docker-desktop-user-distro proxy --distro-name ubuntu 
--docker-desktop-root /mnt/wsl/docker-desktop c:\program files\docker\docker\resources: 
exit status 1

이 오류는 Docker Desktop이 WSL Ubuntu 배포판과 통합을 시도할 때 프록시 프로세스가 실패하면서 발생 합니다. Docker Desktop은 WSL2 환경에서 실행되는데, Windows와 Linux 환경 사이의 통신을 담당하는 프록시 컴포넌트에서 문제가 생긴 것입니다.

Docker Desktop을 시작할 때 이 오류가 발생하면 “Skip Ubuntu WSL distro” 또는 “Restart the WSL integration” 옵션이 표시되지만, 어떤 옵션을 클릭해도 잠시 후 다시 오류가 나타나는 경우가 많습니다.

오류 발생의 주요 원인

이 오류가 발생하는 원인은 여러 가지가 있습니다.

첫째, Windows 업데이트 후 WSL과 Docker Desktop 간의 호환성 문제가 발생할 수 있습니다. Windows 업데이트 설치 후에 이 오류가 발생하는 경우가 자주 보고 됩니다.

둘째, Docker Desktop 버전 업그레이드 과정에서 기존 WSL 설정과 충돌이 생길 수 있습니다. Docker Desktop 4.50.0 버전 업데이트 후 WSL 배포판 통합이 깨지는 현상이 보고되었습니다.

셋째, WSL 배포판의 버전 불일치 문제입니다. Ubuntu 배포판이 WSL 버전 1로 설정되어 있으면 Docker Desktop과 호환되지 않아 오류가 발생합니다.

넷째, .wslconfig 파일의 잘못된 설정이나 메모리 할당 제한으로 인한 문제입니다. WSL2의 메모리 할당을 제한하는 .wslconfig 파일이 있으면 Docker 업데이트 후 실행이 불가능 해질 수 있습니다.

해결 방법 1: Docker 프로세스 완전 종료 후 재시작 (가장 간단한 방법)

가장 먼저 시도해볼 수 있는 간단한 해결책입니다. 작업 관리자에서 모든 Docker 관련 프로세스를 종료한 후 Docker Desktop을 다시 시작하면 문제가 해결되는 경우 가 있습니다.

실행 방법:

1. 작업 관리자(Ctrl + Shift + Esc) 열기
2. “Docker”가 포함된 모든 프로세스 찾기 (Docker Desktop, com.docker.backend 등)
3. 각 프로세스를 우클릭하여 “작업 끝내기” 선택
4. Docker Desktop 다시 실행

이 방법으로 해결되지 않으면 다음 단계로 넘어가세요.

해결 방법 2: WSL 완전 종료 후 재시작

WSL 전체를 종료하고 다시 시작하면 캐시된 문제들이 해결될 수 있습니다.

PowerShell을 관리자 권한으로 실행하고 다음 명령어를 입력하세요:

powershell

wsl --shutdown

이 명령어는 실행 중인 모든 WSL 배포판을 완전히 종료합니다. 그 후 Docker Desktop을 다시 시작해보세요.

해결 방법 3: docker-desktop 배포판 재등록 (핵심 해결책)

많은 사용자들에게 효과적인 해결책입니다. wsl –unregister docker-desktop 명령어로 docker-desktop 배포판을 등록 해제한 후 Docker Desktop을 재시작하면 문제가 해결되고, 기존 이미지와 데이터가 손실되지 않는 것으로 보고되었습니다.

PowerShell을 관리자 권한으로 실행:

powershell

# 현재 WSL 배포판 목록 확인
wsl -l -v

# docker-desktop 배포판 등록 해제
wsl --unregister docker-desktop

# 작업 관리자에서 Docker 관련 프로세스 모두 종료

# Docker Desktop 재시작

Docker Desktop을 다시 시작하면 docker-desktop 배포판이 자동으로 재생성됩니다.

주의사항: docker-desktop-data는 삭제하지 마세요. 이 배포판에는 Docker 이미지와 컨테이너 데이터가 저장되어 있습니다.

해결 방법 4: WSL 버전 확인 및 업그레이드

Ubuntu 배포판이 WSL 버전 1로 실행되고 있다면 Docker Desktop과 호환되지 않습니다.

WSL 버전 확인:

powershell

wsl -l -v

결과에서 Ubuntu의 VERSION이 1로 표시되면 2로 업그레이드해야 합니다.

WSL 버전 2로 업그레이드:

powershell

wsl --set-version Ubuntu 2

Ubuntu 배포판을 WSL 버전 2로 업그레이드한 후 Docker Desktop 설정의 WSL Integration에서 해당 배포판을 활성화하면 문제가 해결 됩니다.

해결 방법 5: WSL 업데이트

WSL 자체를 최신 버전으로 업데이트하면 호환성 문제가 해결될 수 있습니다.

powershell

wsl --update

만약 “이미 설치되어 있습니다”라는 메시지가 나오면 웹에서 직접 다운로드하는 방식을 시도하세요:

powershell

wsl --update --web-download

일반 wsl –update 명령이 작동하지 않을 때 –web-download 옵션을 사용하면 문제가 해결 되는 경우가 있습니다.

해결 방법 6: .wslconfig 파일 확인 및 수정

사용자 폴더에 있는 .wslconfig 파일이 문제를 일으킬 수 있습니다.

파일 위치: C:\Users\[사용자이름]\.wslconfig

이 파일이 존재한다면 내용을 확인하고, 메모리 제한이 너무 낮게 설정되어 있지 않은지 확인하세요. Docker 업데이트 후 기존 .wslconfig의 메모리 할당 설정이 새 버전과 충돌할 수 있으며, 이 파일을 삭제하면 Docker가 정상 실행 될 수 있습니다.

권장 설정 예시:

ini

[wsl2]
memory=8GB
processors=4

문제가 지속되면 .wslconfig 파일을 임시로 삭제하거나 이름을 변경한 후 Docker Desktop을 실행해보세요.

해결 방법 7: Windows 기능 확인

WSL2와 Docker Desktop이 제대로 작동하려면 필요한 Windows 기능이 활성화되어 있어야 합니다.

PowerShell 관리자 권한으로 실행:

powershell

# Hyper-V 기능 활성화
DISM /Online /Enable-Feature /All /FeatureName:Microsoft-Hyper-V

# 하이퍼바이저 자동 시작 설정
bcdedit /set hypervisorlaunchtype auto

Windows 기능 설정에서 이미 활성화했더라도 이 명령어들을 실행하면 Hyper-V 가상화 기능이 완전히 활성화되어 문제가 해결되는 경우가 있습니다.

컴퓨터를 재부팅한 후 Docker Desktop을 다시 실행하세요.

해결 방법 8: Docker Desktop WSL Integration 재설정

Docker Desktop 설정에서 WSL 통합을 다시 구성해보세요.

1. Docker Desktop 실행 (오류가 나도 일단 진행)
2. Settings(설정) → Resources → WSL Integration 이동
3. “Enable integration with my default WSL distro” 체크 해제
4. Apply & Restart 클릭
5. 다시 Settings → Resources → WSL Integration 이동
6. “Enable integration with my default WSL distro” 다시 체크
7. Ubuntu 배포판 토글 활성화
8. Apply & Restart 클릭

Docker Desktop 설정에서 WSL Integration을 비활성화했다가 다시 활성화하면 통합이 재설정 됩니다.

해결 방법 9: 네트워크 설정 초기화

네트워크 관련 문제로 인해 WSL과 Docker 간 통신이 실패할 수 있습니다.

명령 프롬프트를 관리자 권한으로 실행:

cmd

netsh winsock reset

Winsock 카탈로그를 재설정하면 네트워크 프로토콜 정보가 초기화되어 연결 문제가 해결 될 수 있습니다.

재부팅 후 Docker Desktop을 다시 실행하세요.

해결 방법 10: Docker Desktop 완전 재설치 (최후의 수단)

위의 모든 방법이 실패했다면 Docker Desktop을 완전히 제거하고 다시 설치하세요.

완전 제거 순서:

1. Docker Desktop 종료
2. 제어판 → 프로그램 제거에서 Docker Desktop 제거
3. 다음 폴더들 삭제:
   • C:\Users\[사용자]\AppData\Local\Docker
   • C:\Users\[사용자]\AppData\Roaming\Docker
   • C:\ProgramData\Docker
4. WSL 배포판 정리:

powershell

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

5. 컴퓨터 재부팅
6. Docker Desktop 최신 버전 다운로드 및 설치

WSL 관련 파일을 완전히 제거한 후 처음부터 다시 설치하면 문제가 해결 되는 경우가 많습니다.

오류 예방을 위한 팁

앞으로 이 오류가 재발하지 않도록 다음 사항을 기억하세요.

Docker Desktop과 WSL을 항상 최신 버전으로 유지하세요. Windows 업데이트 후에는 Docker Desktop을 먼저 완전히 종료한 상태에서 재부팅하는 것이 좋습니다.

.wslconfig 파일을 수정할 때는 Docker Desktop과의 호환성을 고려하세요. 메모리 제한을 너무 낮게 설정하면 문제가 발생할 수 있습니다.

VPN이나 프록시 소프트웨어를 사용 중이라면 Docker Desktop과 충돌할 수 있습니다. ZScaler와 같은 보안 프록시가 Windows 프록시 설정을 반복적으로 변경하면서 WSL에서 문제가 발생 할 수 있으니 주의하세요.

마무리

Docker Desktop WSL 프록시 오류는 당황스럽지만, 단계별로 해결 방법을 시도하면 대부분 해결됩니다. 가장 효과적인 방법은 wsl --unregister docker-desktop 명령어로 배포판을 재등록하는 것이며, 이 방법으로도 해결되지 않으면 WSL 업데이트나 Windows 기능 확인을 진행하세요.

개발 환경 설정 문제로 시간을 낭비하지 않도록, 이 가이드를 북마크해두고 필요할 때 참고하세요.