docker wsl - Tistory 실전 요약
Windows에서 Docker를 쓸 때 가장 자주 부딪히는 문제는 어떤 구성으로 실행해야 하는지와 프로젝트 파일을 어디에 둘지입니다. Docker Desktop, WSL 2, Windows 파일 시스템을 함께 쓰면 설정 자체는 단순해 보여도, 경로와 권한, 성능 특성이 서로 달라서 예상과 다른 동작이 자주 발생합니다.
이 글은 Windows + WSL 2 + Docker Desktop 조합을 기준으로, 실무에서 바로 확인해야 할 점만 정리합니다. 설치 절차를 처음부터 길게 설명하기보다, 무엇이 확인 대상인지, 어디서 문제가 자주 생기는지, 어떤 선택이 안전한지에 초점을 맞춥니다.
프로젝트를 Windows 경로와 WSL 경로 사이에 두고 옮겨 다니는 팀이라면 특히 유용합니다. 핵심은 Linux 컨테이너는 Linux 커널이 필요하고, 파일이 놓인 위치에 따라 성능과 동작이 달라질 수 있다는 점입니다.
핵심 요약
- Windows에서 Linux 컨테이너를 다룰 때는 WSL 2 기반의 Docker Desktop 구성을 먼저 검토하는 것이 안전합니다.
- WSL 1은 Linux 커널을 제공하지 않으므로 Linux 컨테이너 실행 환경으로는 제약이 큽니다.
- 성능과 일관성을 중시한다면 프로젝트 파일은 가능하면 WSL의 Linux 파일 시스템에 두는 편이 좋습니다.
- 문제가 생기면 먼저 WSL 버전, Docker Desktop 실행 상태, WSL 통합 설정, 프로젝트 경로를 순서대로 확인하세요.
1. Docker와 WSL을 함께 쓴다는 뜻부터 정리하기
Windows에서 “Docker WSL”이라고 말할 때는 보통 다음 구성을 뜻합니다.
- Windows
- WSL 2
- Docker Desktop
- 필요에 따라 Docker Desktop에 연결된 Linux 배포판(예: Ubuntu)
Microsoft 문서에 따르면 WSL 2는 경량 가상 머신 안에서 실제 Linux 커널을 사용합니다. 반면 WSL 1은 Linux 커널을 포함하지 않습니다. Docker의 Linux 컨테이너는 Linux 커널 기능을 전제로 하므로, Windows에서 Linux 컨테이너를 안정적으로 다루려면 WSL 2 구성이 중요합니다.
즉, 이 글에서의 전제는 다음과 같습니다.
- Windows 자체에서 Docker 엔진을 직접 다루는 상황이 아니라,
- Docker Desktop + WSL 2를 통해 Linux 컨테이너를 사용한다는 상황입니다.
1-1. WSL 1과 WSL 2의 핵심 차이
아래 표는 실무 판단에 필요한 수준으로만 간단히 정리한 것입니다.
| 항목 | WSL 1 | WSL 2 |
|---|---|---|
| Linux 커널 | 없음 | 있음 |
| Linux 컨테이너 실행 적합성 | 제약 큼 | 적합 |
| Windows와의 파일 경로 체감 | 직접적인 편 | 경로/파일 시스템 차이를 더 의식해야 함 |
| 현재 선택 기준 | 레거시/특정 호환 목적 | 일반적인 권장 선택 |
WSL 1이 무조건 잘못된 것은 아니지만, Linux 컨테이너를 주로 다루는 실무에서는 WSL 2가 훨씬 자연스럽습니다.
2. 실무에서 먼저 정해야 하는 구성
Docker를 Windows에서 쓰는 방법은 여러 가지가 있지만, 실제로는 아래 선택이 가장 중요합니다.
2-1. 빠른 판단 기준
| 상황 | 권장 방향 | 이유 |
|---|---|---|
| Windows에서 Linux 컨테이너를 자주 빌드/실행 | Docker Desktop + WSL 2 | Linux 커널을 사용할 수 있고 관리가 단순함 |
| 소스 편집과 Docker 작업을 자주 함께 수행 | 프로젝트를 WSL 파일 시스템에 저장 | 파일 I/O와 경로 일관성에 유리 |
| 학습용, 간단한 테스트 | Docker Desktop 기본 구성 + WSL 통합 | 진입 장벽이 낮음 |
| WSL 1만 사용 중 | WSL 2 전환 검토 | Linux 컨테이너 제약을 줄이기 위해 |
2-2. 권장 구조
가장 무난한 흐름은 다음과 같습니다.
- Windows에서 WSL 2를 사용하도록 설정
- Linux 배포판 설치
- Docker Desktop 설치
- Docker Desktop에서 WSL 2 backend와 WSL integration 사용
- 프로젝트 코드는 가능하면 WSL 내부 경로에 저장
이 구조의 장점은 분명합니다.
- Docker 엔진을 Windows에서 따로 직접 운영하는 복잡도를 줄일 수 있습니다.
- Linux 개발 도구와 Docker가 같은 실행 환경에 가까워집니다.
- Windows 파일 시스템과 Linux 파일 시스템의 차이를 명확히 구분할 수 있습니다.
2-3. 알아두어야 할 전제
Docker Desktop은 Docker 엔진을 편하게 쓰게 해 주는 도구이고, WSL은 Linux 실행 환경입니다. 둘은 같은 것이 아닙니다.
실무에서 문제를 디버깅할 때는 다음처럼 역할을 분리해서 생각해야 합니다.
- WSL: Linux 배포판이 실행되는 환경
- Docker Desktop: Docker 엔진과 통합 관리
- 컨테이너: 실제로 실행되는 격리된 프로세스
이 구분을 놓치면 문제가 생겼을 때 원인을 잘못 짚기 쉽습니다.
3. 설치 후 최소 확인 사항
설치가 끝났다고 바로 작업을 시작하기보다, 다음 항목을 먼저 확인하는 것이 좋습니다.
3-1. WSL 2인지 확인
Microsoft는 WSL 2 사용을 위해 필요한 Windows 기능과 배포판 설치 절차를 안내합니다. 환경마다 절차가 다를 수 있으므로, 운영체제 버전에 맞는 공식 문서를 따르는 편이 안전합니다.
확인해야 할 핵심은 다음입니다.
- WSL이 활성화되어 있는가
- 설치된 배포판이 WSL 2인지
- 배포판이 정상적으로 실행되는가
확인 명령 예시는 다음과 같습니다.
wsl -l -v이 명령은 설치된 배포판과 각 배포판의 WSL 버전을 보여줍니다.
3-2. Docker Desktop이 실행 중인지 확인
Docker Desktop을 설치했다면, 단순히 설치만 된 상태가 아니라 실행 중인지도 확인해야 합니다.
Docker CLI가 동작하려면 Docker Desktop 쪽 엔진이 살아 있어야 합니다.
기본 점검 예시는 다음과 같습니다.
docker version
docker infodocker version은 클라이언트와 서버가 연결되는지 보는 데 유용합니다.docker info는 현재 엔진 상태를 확인하는 데 도움이 됩니다.
3-3. WSL 통합이 켜져 있는지 확인
Docker Desktop은 WSL 배포판과 통합해서 사용할 수 있습니다.
실무에서는 “Docker Desktop은 켜져 있는데 WSL 배포판에서 docker가 안 된다”는 식의 혼동이 자주 생깁니다.
확인 포인트는 다음입니다.
- Docker Desktop의 WSL 2 backend 사용 여부
- 사용할 WSL 배포판에 대한 integration 활성화 여부
- 작업 중인 터미널이 Windows PowerShell인지, WSL 터미널인지
이 세 가지는 서로 다른 축입니다. 하나만 맞아도 전체가 정상이라고 볼 수는 없습니다.
4. 프로젝트 파일은 어디에 두는 것이 좋은가
Docker + WSL 환경에서 가장 체감 차이가 큰 부분입니다.
4-1. 권장: WSL의 Linux 파일 시스템
가능하면 프로젝트를 다음처럼 WSL 내부 경로에 두는 편이 좋습니다.
/home/<user>/projects/my-app이 방식이 유리한 이유는 다음과 같습니다.
- Linux 도구가 기대하는 파일 의미론에 더 가깝습니다.
- Windows 파일 시스템을 WSL에서 반복적으로 접근하는 구조보다 단순합니다.
- 빌드, 마운트, 파일 감시 작업에서 불필요한 지연을 줄일 가능성이 있습니다.
4-2. 주의: /mnt/c 같은 Windows 경로
WSL에서는 Windows 드라이브가 /mnt/c, /mnt/d처럼 보입니다. 접근은 쉽지만, Docker 중심 개발에서는 다음 상황에서 불편해질 수 있습니다.
- 작은 파일이 매우 많은 빌드
- 컨테이너 마운트가 잦은 개발
- 파일 감시를 사용하는 도구를 많이 쓰는 경우
이것은 /mnt/c가 “잘못된 선택”이라는 뜻이 아닙니다. 다만 Docker를 적극적으로 사용하는 프로젝트라면, 기본값으로는 WSL 내부 경로가 더 예측 가능하다는 뜻입니다.
4-3. 빠른 선택표
| 프로젝트 성격 | 파일 위치 추천 | 이유 |
|---|---|---|
| Docker 빌드가 잦음 | WSL 내부 경로 | 경로와 I/O 특성이 더 일관적임 |
| Windows IDE와 파일을 강하게 공유 | Windows 경로도 가능 | 편집 편의성이 높음 |
| 대량의 소스/의존성/생성 파일이 있음 | WSL 내부 경로 우선 | 빌드와 감시 작업에서 유리할 수 있음 |
| 단순 테스트/학습 | 둘 다 가능 | 편의성 우선 선택 가능 |
5. 자주 보는 문제와 원인
5-1. docker 명령이 인식되지 않음
가능한 원인은 다음과 같습니다.
- Docker Desktop이 설치되지 않았거나 실행 중이 아님
- WSL 통합이 꺼져 있음
- 터미널 환경과 Docker CLI 연결이 꼬였음
우선 아래를 확인합니다.
docker version여기서 실패하면, 먼저 Docker Desktop 실행 상태와 WSL 통합 설정을 봐야 합니다.
5-2. 컨테이너는 뜨는데 느림
가능한 원인은 다음과 같습니다.
- 프로젝트가 Windows 파일 시스템(
/mnt/c)에 있음 - 빌드 컨텍스트가 너무 큼
- 불필요한 파일이 이미지 빌드에 포함됨
권장 대응은 다음과 같습니다.
- 프로젝트를 WSL 내부 경로로 옮겨 보기
.dockerignore를 정리해 빌드 컨텍스트 줄이기- 대용량 산출물이나 캐시 파일을 컨텍스트에서 제외하기
.dockerignore는 공식 Docker 문서가 안내하는 표준 기능이므로, 대형 프로젝트일수록 꼭 점검하는 편이 좋습니다.
5-3. Linux 컨테이너가 기대대로 동작하지 않음
가능한 원인은 다음과 같습니다.
- WSL 1 사용
- Docker Desktop이 Linux 컨테이너 용도로 설정되지 않음
- WSL 배포판 통합이 잘못됨
우선순위는 다음과 같습니다.
- WSL 버전 확인
- Docker Desktop 실행 상태 확인
- WSL integration 확인
- 작업 중인 배포판에서
docker version확인
5-4. 권한 문제처럼 보이는 오류
WSL과 Linux 컨테이너는 기본적으로 Linux 권한 모델을 따릅니다.
따라서 Windows 경로와 Linux 경로를 섞어 쓰면 다음과 같은 문제가 권한 문제처럼 보일 수 있습니다.
- 파일 소유자/권한 불일치
- 호스트와 컨테이너의 UID/GID 차이
- Windows에서 생성된 파일 속성 차이
이때는 “Docker가 고장났다”라고 단정하기보다, 파일이 어느 파일 시스템에 있고 어떤 권한 모델을 따르는지부터 확인해야 합니다.
6. 문제를 빠르게 좁히는 진단 순서
문제가 생기면 아래 순서대로 확인하면 대체로 빠르게 원인을 좁힐 수 있습니다.
- WSL 2인지 확인
- Docker Desktop이 실행 중인지 확인
- WSL 통합이 켜져 있는지 확인
- 프로젝트 위치가
/mnt/c인지 확인 - 빌드 컨텍스트와
.dockerignore를 점검 docker version,docker info로 연결 상태 확인
6-1. 최소 진단 명령
wsl -l -v
docker version
docker info이 세 개만으로도 많은 문제를 분류할 수 있습니다.
wsl -l -v: 배포판과 WSL 버전 확인docker version: 클라이언트/서버 연결 확인docker info: 엔진 상태와 기본 설정 확인
명령 출력은 환경마다 다르므로, 숫자나 필드 하나만 보고 판단하지 말고 전체 맥락을 보는 것이 중요합니다.
7. 실무 운영 원칙
7-1. 역할을 분리해서 기억하기
다시 정리하면 다음과 같습니다.
- WSL은 Linux 실행 환경입니다.
- Docker Desktop은 Docker 엔진을 관리하고 WSL과 통합할 수 있습니다.
- 컨테이너는 실제 실행 대상입니다.
이 셋을 혼동하면 문제 해결 속도가 느려집니다.
예를 들어, 파일 경로 문제가 사실은 WSL 파일 시스템 선택 문제일 수 있고, Docker 엔진 문제처럼 보였던 것이 사실은 통합 설정 문제일 수도 있습니다.
7-2. 새 프로젝트는 시작점에서 파일 위치를 정하기
프로젝트를 시작할 때 아래 질문에 먼저 답하는 것이 좋습니다.
- Docker 빌드가 자주 일어나는가?
- Windows 앱과 같은 파일을 동시에 편집해야 하는가?
- 성능과 편의성 중 무엇이 더 중요한가?
Docker 중심 작업이라면 WSL 내부 경로, Windows와의 연동이 더 중요하다면 Windows 경로라는 기준을 초기에 정해 두면 혼란이 줄어듭니다.
7-3. 재현 가능한 설정을 우선하기
팀 환경에서는 개인 환경 차이가 문제를 자주 만듭니다. 따라서 다음을 권장합니다.
- Dockerfile을 명확하게 유지
.dockerignore를 정리- WSL/Windows 경로 혼용을 최소화
- 배포판 이름과 버전을 문서화
이 원칙은 Docker 자체보다, 환경 차이로 인한 재현 실패를 줄이는 데 효과적입니다.
8. 결론
Windows에서 Docker를 안정적으로 쓰려면, 먼저 WSL 2 + Docker Desktop 조합을 기본 전제로 두는 것이 좋습니다. WSL 1은 Linux 커널이 없기 때문에 Linux 컨테이너 실행 환경으로는 제약이 크고, 프로젝트 파일은 가능하면 WSL의 Linux 파일 시스템에 두는 편이 성능과 일관성 면에서 안전합니다.
문제가 생기면 복잡하게 추측하기보다 WSL 버전, Docker Desktop 실행 상태, WSL 통합 여부, 프로젝트 경로를 먼저 확인하세요. 이 네 가지를 점검하는 것만으로도 대부분의 docker wsl 관련 이슈는 빠르게 좁힐 수 있습니다.