Docker Desktop WSL2 자원 제한, 메모리·swap·VHDX를 따로 조정하는 법

AI를 활용하여 생성한 이미지입니다.

컴퓨팅 · 중급 가이드

Docker Desktop을 WSL2 백엔드로 사용할 때 메모리가 부족하다고 해서 Docker의 메모리 값만 올리면 되는 것은 아닙니다. WSL2 유틸리티 VM의 상한, swap, Docker 이미지·볼륨이 쌓이는 가상 디스크, Windows 경로와 Linux 경로 사이의 파일 공유가 서로 다른 병목을 만듭니다. 빌드가 끝났는데 Windows가 계속 버벅이거나 디스크가 줄어든다면 먼저 문제가 메모리인지 저장 공간인지부터 나누세요.

포트 포워딩이나 NAT·mirrored 모드가 문제라면 WSL2 네트워크 모드 글이 더 가깝습니다. 여기서는 Docker Desktop이 이미 설치된 Windows PC에서 이미지 빌드와 여러 컨테이너를 운영하는 분을 대상으로 합니다.

네 가지 자원을 따로 보세요

Microsoft에 따르면 .wslconfig는 사용자 프로필에 두고 모든 WSL2 배포판에 적용하는 전역 설정 파일입니다. 여기서 WSL2 VM의 메모리와 프로세서 같은 항목을 조정할 수 있고, swap은 메모리 부족 시 디스크를 사용하는 완충 공간입니다.[1] Docker Desktop의 WSL2 백엔드는 이 환경 위에서 동작하므로 Docker 컨테이너 하나의 사용량과 WSL 전체 상한을 같은 값으로 보면 안 돼요.

Docker 문서는 WSL2 엔진 데이터를 기본적으로 사용자 프로필 아래 Docker WSL 경로에 저장하며, Resources·Advanced에서 위치를 바꿀 수 있다고 안내합니다.[2] 따라서 Windows 디스크가 부족한 문제는 memory=를 올려도 해결되지 않습니다. Docker 설정 화면에는 메모리·swap·디스크 이미지 위치가 서로 다른 항목으로 나타나므로, 증상과 설정을 대응시켜야 해요.[3]

설정 전에 같은 조건을 기록해요

값을 바꾸기 전에 같은 프로젝트를 같은 명령으로 실행하고 기준을 남기세요. 빌드 시간, 이미지 크기, 실행 중인 컨테이너 수, 작업 직후와 5분 뒤의 Windows 메모리, WSL 안의 free -h, 파일 시스템의 df -h를 함께 기록하면 좋습니다. Docker Desktop에서 보이는 자원 사용량과 docker system df 결과도 저장하세요.

docker system df
wsl -l -v
wsl --status
# WSL 배포판 안에서
free -h
df -h

free -h의 used가 높다는 사실만으로 부족하다고 단정하지 마세요. 캐시가 많은 경우와 swap이 계속 늘어나는 경우는 대응이 다릅니다. 빌드 중 프로세스가 종료되면 메모리 피크를 의심하고, 빌드는 성공하지만 Windows가 느려지면 상한과 동시 실행 작업을 함께 확인하세요. 이미지·볼륨 사용량만 커지면 저장 공간 문제입니다.

.wslconfig는 전체 WSL2에 영향을 줘요

파일은 Windows 사용자 프로필의 %UserProfile%\.wslconfig에 둡니다. 아래 값은 정답이 아니라 형식을 보여 주는 예시예요. 실제 메모리는 브라우저, IDE, 백신, 화상회의 같은 Windows 작업 공간을 남긴 뒤 정해야 합니다.

[wsl2]
memory=12GB
processors=6
swap=8GB

[experimental]
autoMemoryReclaim=gradual

autoMemoryReclaim은 WSL 버전과 지원 상태에 따라 다를 수 있으므로 설정을 넣기 전에 현재 WSL 문서와 버전을 확인하세요.[1][2] 한 번에 메모리와 swap을 모두 바꾸면 어떤 값이 효과를 냈는지 알기 어렵습니다. 하나를 바꾼 뒤 wsl --shutdown으로 WSL2 VM을 종료하고 다시 같은 빌드를 실행하세요. 이 명령은 실행 중인 배포판과 컨테이너를 닫으므로 작업을 먼저 저장해야 합니다.

swap은 성공률과 속도를 바꾸는 완충재예요

swap을 늘리면 메모리 피크에서 프로세스가 즉시 종료되는 상황을 늦출 수 있지만, 디스크 접근은 RAM보다 느립니다. 빌드가 swap에 의존하면 성공해도 시간이 길어질 수 있어요. 이때는 swap만 키우기보다 BuildKit이나 Compose의 병렬 작업 수를 낮추고, 사용하지 않는 컨테이너를 내리고, 동시에 실행하는 테스트 수를 줄여 보세요.

swap을 0으로 두면 디스크 사용량은 줄어도 OOM이 빨리 나타날 수 있습니다. 개발 PC에서는 작은 swap을 유지하면서 실제 사용량을 관찰하는 편이 안전한 경우가 많아요. swap 파일을 다른 드라이브로 옮길 때는 그 드라이브의 여유 공간과 백업 여부를 함께 확인하세요. 저장 공간이 이미 부족한 PC에서는 큰 swap이 문제를 해결하기보다 디스크 압박을 키울 수 있습니다.

Docker 데이터와 VHDX는 별도 정리 대상이에요

docker system df로 이미지, 컨테이너, 로컬 볼륨의 사용량을 먼저 확인하세요. docker system prune은 사용하지 않는 객체를 제거하므로, 다시 만들기 어려운 볼륨까지 지울 수 있는 옵션은 목록을 확인한 뒤 선택해야 합니다. 파일을 컨테이너에서 삭제해도 가상 디스크 파일의 Windows 사용량이 즉시 같은 크기로 줄지 않을 수 있어요. 대규모 정리나 VHDX 이동은 백업과 되돌림 계획을 먼저 세우세요.

Docker Desktop WSL2 엔진 데이터 위치는 Settings의 Resources·Advanced에서 확인할 수 있습니다.[2][3] 데이터 위치를 옮기는 작업은 단순한 폴더 이동이 아니므로 Docker가 안내하는 절차를 사용하고, 기존 이미지와 볼륨이 보이는지 확인한 뒤 원본을 정리하세요. WSL 배포판의 ext4.vhdx 용량을 따로 관리해야 한다면 ext4.vhdx 용량 관리 글도 참고하세요.

파일 공유 병목은 메모리를 올려도 사라지지 않아요

Windows 경로에 소스 코드를 두고 컨테이너가 수천 개 파일을 읽는 프로젝트는 WSL VM 메모리보다 파일 공유 지연이 먼저 나타날 수 있어요. 같은 커밋을 WSL의 Linux 파일 시스템 안 임시 디렉터리에 복사해 동일한 명령으로 비교하세요. Linux 경로에서만 빨라지면 .wslconfig를 키우기보다 소스 위치와 바인드 마운트 방식을 바꾸는 편이 맞습니다.

반대로 대형 이미지 빌드나 여러 컴파일러가 동시에 돌아가 Windows 메모리가 압박되면 CPU를 더 주기보다 병렬성을 낮추는 것이 나을 수 있어요. CPU 수, 메모리, 파일 위치, 컨테이너 수를 한 번에 바꾸지 말고 하나씩 비교해야 합니다. “CPU를 많이 주면 항상 빨라진다”는 규칙은 메모리와 디스크가 충분할 때만 성립합니다.

증상별 조정 순서

1. OOM이나 프로세스 종료라면 동시 컨테이너와 빌드 병렬 수를 먼저 낮춥니다.
2. WSL 전체가 느리면 메모리 상한을 조금 조정하고 wsl --shutdown 뒤 재측정합니다.
3. swap이 계속 증가하면 작업량과 병렬성을 낮추고 swap 파일 여유 공간을 확인합니다.
4. Windows 디스크가 부족하면 docker system df, 이미지·볼륨, Docker 데이터 위치를 봅니다.
5. 파일이 많은 프로젝트만 느리면 Linux 경로에서 같은 빌드를 비교합니다.
6. 변경 후 악화되면 가장 마지막에 바꾼 항목 하나만 되돌립니다.

자주 묻는 질문

64GB RAM이면 WSL에 64GB를 줘도 되나요?

권장되지 않습니다. Windows와 다른 앱이 쓸 공간을 남겨야 하고, 모든 WSL2 배포판에 적용되는 전역 상한이라는 점도 고려해야 합니다.[1] 실제 작업량을 기록해 필요한 만큼만 배정하세요.

swap을 크게 잡으면 빌드가 빨라지나요?

보통은 반대일 수 있어요. OOM을 늦추는 완충재이지 RAM 확장팩이 아닙니다. swap 사용이 잦으면 병렬 작업과 컨테이너 수부터 줄이세요.

이미지를 지웠는데도 디스크가 그대로예요.

가상 디스크 파일의 회수 시점과 Docker 데이터 위치를 따로 확인해야 합니다. 즉시 VHDX를 직접 삭제하지 말고 Docker·WSL의 공식 관리 절차와 백업을 먼저 확인하세요.

메모리를 올렸는데 빌드가 여전히 느려요.

Windows 경로의 바인드 마운트, 파일 수, Docker 데이터 디스크, 네트워크 다운로드가 병목일 수 있습니다. Linux 경로 비교와 docker system df를 통해 메모리 문제와 분리하세요.

Docker Desktop WSL2 튜닝은 값을 많이 넣는 작업이 아니라 병목을 분리하는 작업입니다. 메모리 상한, swap, Docker 데이터, 파일 공유를 같은 조건에서 기록하고 한 번에 하나씩 바꾸면 설정을 되돌리기도 쉽습니다.

Sources

1. [1] Microsoft Learn: Advanced settings configuration in WSL
2. [2] Docker Docs: Docker Desktop WSL 2 backend on Windows
3. [3] Docker Docs: Change your Docker Desktop settings