🐧
WSL2 치트시트

배포판 설치/관리, vhdx 가상 디스크 압축 및 Sparse 축소, .wslconfig 리소스 최적화, Windows 상호 운용, Mirrored 네트워킹, USB/디스크 마운트, Docker 및 트러블슈팅 완벽 가이드
#wsl#wsl2#windows#linux#ubuntu#terminal#cli#virtualization#sysadmin#devops최종 업데이트: 2026-10-03
WSL2 치트시트 핵심 명령어 및 실전 가이드

## 1. WSL2 설치 및 환경 초기화 (Installation & Setup)
Windows 10(2004 이상) 및 Windows 11에서는 단 한 줄의 명령어로 WSL2 커널과 기본 Ubuntu 배포판을 설치할 수 있습니다.
```powershell
# ⚡ [1] 기본 설치 (최신 Linux 커널 + 기본 Ubuntu 자동 설치, 관리자 권한 권장)
wsl --install

# 🔍 [2] 설치 가능한 온라인 Linux 배포판 목록 확인
wsl --list --online
# 축약형:
wsl -l -o

# 📦 [3] 원하는 특정 배포판 지정 설치
wsl --install -d Ubuntu-24.04
wsl --install -d Debian
wsl --install -d Kali-linux
wsl --install -d openSUSE-Tumbleweed

# 🛠️ [4] OS 기능만 활성화하고 배포판은 나중에 설치할 때
wsl --install --no-distribution

# 🔄 [5] WSL 커널 및 WSLg 최신 버전 업데이트
wsl --update
wsl --update --pre-release     # 프리릴리즈(실험 기능 포함) 업데이트
wsl --update --web-download   # Microsoft Store 대신 GitHub 웹에서 직접 다운로드

# 📊 [6] 현재 WSL 버전 및 구성 요소 상세 확인
wsl --version
# 결과 예시:
# WSL 버전: 2.3.24.0
# 커널 버전: 5.15.153.1-2
# WSLg 버전: 1.0.65
# Windows 버전: 10.0.26100.1742

# ⚙️ [7] WSL 상태 확인 및 기본 버전을 2로 고정
wsl --status                  # 기본 배포판, 커널 버전, 파일 시스템 상태
wsl --set-default-version 2   # 향후 설치되는 배포판 기본 아키텍처를 WSL2로 지정
```

## 2. 배포판(Distro) 조회, 실행 및 세션 관리
설치된 여러 리눅스 배포판을 확인하고 실행하는 기본 조작입니다.
```powershell
# 📋 [1] 설치된 배포판 목록 및 실행 상태 확인 (매우 중요)
wsl --list --verbose
# 축약형:
wsl -l -v
# 출력 항목: NAME(이름), STATE(Running/Stopped), VERSION(1 또는 2)

# 🚀 [2] 배포판 진입 및 실행
wsl                           # 기본(Default) 배포판으로 즉시 쉘 진입
wsl -d Ubuntu-24.04           # 특정 배포판 이름으로 지정 진입
wsl -d Debian -u root         # 특정 사용자(예: root) 권한으로 진입
wsl --cd ~                    # Linux 홈 디렉토리에서 시작
wsl --cd /var/log             # 지정한 특정 Linux 경로에서 시작

# ⭐ [3] 기본(Default) 배포판 변경 (wsl 명령 단독 실행 시 열릴 배포판)
wsl --set-default Ubuntu-24.04
# 축약형:
wsl -s Ubuntu-24.04

# 🔄 [4] WSL1 배포판을 WSL2 아키텍처로 변환 (또는 반대)
wsl --set-version Ubuntu-20.04 2

# ⚡ [5] 쉘에 진입하지 않고 인라인으로 Linux 명령 직접 실행
wsl ls -la /var/www
wsl uname -r
wsl -d Debian cat /etc/os-release
```

## 3. 인스턴스 중지, 전체 종료 및 리소스 반환 (Stop & Shutdown)
WSL2는 사용 후에도 가상 머신(VM)이 메모리를 점유할 수 있으므로, 종료 및 재시작 명령을 숙지해야 합니다.
```powershell
# 🛑 [1] 특정 배포판 하나만 즉시 강제 종료 (좀비 프로세스 해결)
wsl --terminate Ubuntu-24.04
# 축약형:
wsl -t Ubuntu-24.04

# 🔌 [2] 모든 배포판 및 백그라운드 WSL 가상 머신 전체 강제 종료
# 💡 .wslconfig 수정 후 설정을 적용하거나 RAM을 호스트에 즉시 반환할 때 필수!
wsl --shutdown

# 🔍 [3] 모든 인스턴스가 완전히 멈추었는지 확인
wsl -l -v
# 모든 항목의 STATE가 "Stopped"인지 확인

# 🔄 [4] 빠른 WSL 재시작 원라이너 (PowerShell)
wsl --shutdown; wsl
```

## 4. 배포판 백업, 복원 및 인스턴스 복제 (Export & Import)
배포판 환경(도구 설치, 설정 완료 상태)을 .tar 파일로 백업해 다른 PC로 옮기거나, 복제본을 만들어 테스트할 수 있습니다.
```powershell
# 💾 [1] 특정 배포판을 tar 아카이브로 내보내기 (전체 백업)
# 형식: wsl --export <배포판이름> <백업파일경로.tar>
wsl --export Ubuntu-24.04 D:\WSL_Backups\ubuntu24_backup.tar

# 📦 [1-1] VHDX 원본 형식 그대로 고속 내보내기 (WSL 최신 기능)
wsl --export Ubuntu-24.04 D:\WSL_Backups\ubuntu.vhdx --vhd

# 📥 [2] 백업본을 새 배포판으로 가져오기 (복원 또는 인스턴스 복제)
# 형식: wsl --import <신규배포판이름> <설치될폴더경로> <백업파일경로.tar> [--version 2]
wsl --import Ubuntu-Dev D:\WSL_Distros\Ubuntu-Dev D:\WSL_Backups\ubuntu24_backup.tar --version 2

# 📂 [3] 기존 vhdx 파일을 활용한 인-플레이스 등록
wsl --import-in-place Ubuntu-Prod D:\WSL_Distros\ext4.vhdx

# 🗑️ [4] 배포판 등록 취소 및 완전 삭제 (가상 디스크 ext4.vhdx 영구 삭제 주의!)
wsl --unregister Ubuntu-Dev

# 👤 [5] 팁: --import로 복원한 배포판은 기본 사용자가 root가 됩니다.
# 일반 사용자로 기본 로그인하려면 Linux 내부 /etc/wsl.conf에 설정 추가:
# [user]
# default = <내유저네임>
```

## 5. VHDX 디스크 용량 축소 및 최적화 (Sparse & Compact)
WSL2 가상 디스크(`ext4.vhdx`)는 동적 확장형이라 안에서 파일을 지워도 Windows 호스트에서는 파일 크기가 줄어들지 않습니다.
```powershell
# 🚀 [방법 1] 내장 Sparse VHDX 활성화 (가장 추천! WSL 2.0+ 자동 공간 회수)
# Linux에서 파일을 삭제하면 Windows 호스트 가상 디스크 크기가 자동으로 축소됨
wsl --manage Ubuntu-24.04 --set-sparse true

# 신규 설치되는 모든 배포판에 Sparse를 기본 적용하려면:
# %USERPROFILE%\.wslconfig 에 [wsl2] sparseVhd=true 추가

# 🧹 [방법 2] 전통적인 Diskpart 수동 디스크 압축 (구버전 호환)
# 단계 1: WSL 완전 종료
wsl --shutdown

# 단계 2: 해당 배포판의 ext4.vhdx 위치 확인 (보통 AppData 아래)
# 예: C:\Users\<사용자>\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu...\LocalState\ext4.vhdx

# 단계 3: 관리자 권한 PowerShell/CMD에서 diskpart 실행
# diskpart 진입 후 순서대로 입력:
select vdisk file="C:\경로\ext4.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit

# 🐧 [보조 팁] Linux 내부에서 블록 비우기 (TRIM 실행)
# Linux 내부 터미널에서 실행하여 미사용 블록을 정리
sudo fstrim -av
```

## 6. Windows-Linux 상호 운용 & 파일시스템 성능 규칙
Windows와 Linux 간 파일 및 실행 파일 교차 접근 방법과 I/O 성능 극대화 원칙입니다.
```powershell
# 📁 [1] Linux에서 Windows 드라이브 접근
# C 드라이브: /mnt/c/
# D 드라이브: /mnt/d/
cd /mnt/c/Users/Username/Documents

# 🪟 [2] Windows 탐색기에서 Linux 파일시스템 열기
# Linux 터미널 현재 경로를 Windows 탐색기 GUI로 즉시 오픈:
explorer.exe .

# Windows 탐색기 주소창(또는 Win+R 실행창)에 직접 입력:
\\wsl.localhost\Ubuntu-24.04\home\username
\\wsl$\Ubuntu-24.04\

# ⚡ [3] 크로스 실행 (Cross-Execution)
# Linux 터미널 안에서 Windows 프로그램 실행:
notepad.exe memo.txt
code .                          # 현재 폴더를 VS Code로 열기
powershell.exe -Command "Get-Process"

# PowerShell/CMD에서 Linux 파이프라인 활용:
ipconfig | wsl grep -i ipv4
Get-ChildItem | wsl awk '{print $1}'

# ⚠️ [CRITICAL] 파일시스템 I/O 성능 핵심 규칙
# ❌ 절대 금지: Git 프로젝트, node_modules, Python venv를 /mnt/c/... 에 두고 빌드하지 마세요! (최대 10~20배 느림)
# ⭕ 권장 위치: 반드시 Linux 루트(/home/<username>/projects/...) 내부에 코드를 두고 작업하세요.
```

## 7. 전역 설정(.wslconfig) & 배포판 설정(/etc/wsl.conf)
WSL2의 CPU/RAM 점유 한도 제한, systemd 활성화, 네트워킹 방식 커스터마이징 핵심입니다.

### 전역 설정: `%USERPROFILE%\.wslconfig` (Windows 호스트 레벨)
Windows 사용자 폴더(`C:\Users\<사용자>\.wslconfig`)에 파일을 만들고 설정합니다. (설정 후 `wsl --shutdown` 필수)
```ini
[wsl2]
# 💻 최대 사용 메모리 제한 (기본값은 호스트 RAM의 50% 또는 8GB 중 작은 값)
memory=8GB

# ⚙️ 할당할 CPU 코어 수 제한
processors=4

# 💾 스왑(Swap) 파일 크기 설정 (0GB 설정 시 비활성화)
swap=4GB

# 🌐 로컬호스트 포트 자동 전달
localhostForwarding=true

# 🚀 최신 미러드 네트워킹 (Windows와 WSL이 IP/포트를 완전 공유, VPN 문제 해결)
networkingMode=mirrored
dnsTunneling=true
autoProxy=true

# 📦 Sparse VHD 자동 활성화 (용량 자동 반환)
sparseVhd=true

[experimental]
# 🧠 Linux에서 사용 후 남은 메모리를 Windows에 점진적으로 반환 (gradual 또는 dropcache)
autoMemoryReclaim=gradual
```

### 배포판 설정: `/etc/wsl.conf` (Linux 내부 레벨)
각 Linux 배포판의 `/etc/wsl.conf`에 작성합니다.
```ini
# 🚀 [1] systemd 활성화 (systemctl, Docker, Cron, Nginx 데몬 사용 시 필수)
[boot]
systemd=true

# 👤 [2] 기본 로그인 사용자 설정
[user]
default=lucky

# 📂 [3] Windows 드라이브(/mnt/c) 마운트 옵션 및 파일 권한 지정
[automount]
enabled=true
options="metadata,umask=22,fmask=11"
mountFsTab=true

# 🌐 [4] DNS 파일 자동 덮어쓰기 방지 (고정 사내 DNS/Google DNS 사용 시)
[network]
generateResolvConf=false
```

## 8. 네트워크(NAT vs Mirrored) & 포트 포워딩, VPN 대응
기본 NAT 모드와 모던 Mirrored 모드의 동작 차이와 네트워크 문제 해결법입니다.
```powershell
# 🌐 [1] 모드 비교
# - NAT(기본값): WSL이 자체 가상 IP(172.x.x.x)를 가짐. Windows -> localhost로 접근 가능.
# - Mirrored(권장): Windows와 WSL2가 동일한 IP 주소와 포트 공간을 공유 (Windows 11 23H2+)

# 🔌 [2] 외부 LAN(동일 공유기 내 다른 PC/모바일)에서 WSL2 웹 서버 접속 (NAT 모드일 때)
# 단계 1: Linux 내부 IP 확인
wsl hostname -I

# 단계 2: Windows 관리자 PowerShell에서 포트프록시 규칙 등록 (외부 8080 -> WSL 8080)
netsh interface portproxy add v4tov4 listenport=8080 listenaddress=0.0.0.0 connectport=8080 connectaddress=172.28.96.15

# 단계 3: 포트프록시 목록 확인 및 삭제
netsh interface portproxy show all
netsh interface portproxy delete v4tov4 listenport=8080 listenaddress=0.0.0.0

# 🛡️ [3] Windows 방화벽 포트 오픈 (외부 접속 허용)
New-NetFirewallRule -DisplayName "WSL2 Port 8080" -Direction Inbound -LocalPort 8080 -Protocol TCP -Action Allow

# 🔒 [4] VPN(Cisco AnyConnect, GlobalProtect 등) 연결 시 WSL2 인터넷 단절 해결법
# 해결책: %USERPROFILE%\.wslconfig 에 아래 2줄 추가 후 wsl --shutdown
# [wsl2]
# networkingMode=mirrored
# dnsTunneling=true
```

## 9. 물리 디스크 마운트 및 USB 디바이스 연결 (usbipd)
외장 리눅스 하드 디스크(ext4 포맷) 또는 아두이노/시리얼 USB 장비를 WSL로 연결하는 방법입니다.
```powershell
# 💽 [1] 물리 디스크 직접 마운트 (Windows 관리자 PowerShell)
# 디스크 ID 확인
GET-CimInstance -ClassName Win32_DiskDrive | Select-Object DeviceID, Model, Size

# 물리 디스크 전체 마운트
wsl --mount \\.\PHYSICALDRIVE1

# 특정 파티션 및 파일시스템(ext4) 지정 마운트
wsl --mount \\.\PHYSICALDRIVE1 --partition 1 -t ext4

# 마운트 해제 (안전 제거)
wsl --unmount \\.\PHYSICALDRIVE1

# 🔌 [2] USB 장비 연결 (usbipd-win 도구 필요: winget install dorssel.usbipd-win)
# USB 장비 목록 및 BUSID 확인 (Windows 관리자 PowerShell)
usbipd list

# 특정 BUSID 장비를 WSL 공유 가능 상태로 바인딩 (최초 1회)
usbipd bind --busid 2-3

# WSL2 배포판으로 USB 연결 (Attach)
usbipd attach --wsl --busid 2-3

# 연결 해제 (Detach)
usbipd detach --busid 2-3

# 🐧 Linux 내부에서 연결된 USB 확인
lsusb
```

## 10. 개발 도구 연동: Docker, VS Code & WSLg (GUI)
WSL2를 메인 개발 환경으로 활용하기 위한 핵심 도구 연동 가이드입니다.
```bash
# 💻 [1] VS Code 연동 (VS Code Remote - WSL 확장 설치)
# Linux 터미널에서 아래 명령을 치면 Windows의 VS Code가 해당 Linux 경로로 즉시 연결
code .

# 🐳 [2] Docker 연동 (2가지 방식)
# 방식 A: Docker Desktop 사용
# Docker Desktop 설정 -> Resources -> WSL integration -> 설치된 배포판 체크

# 방식 B: Docker Desktop 없이 가벼운 네이티브 Docker Engine 단독 설치 (/etc/wsl.conf에 systemd=true 필수)
sudo apt update && sudo apt install -y docker.io docker-compose-plugin
sudo usermod -aG docker $USER
newgrp docker
docker run --rm hello-world

# 🖼️ [3] WSLg 내장 GUI 앱 실행 (X-Server 별도 설치 불필요, Windows 11 기본 내장)
sudo apt install -y gedit x11-apps
xclock                # 아날로그 시계 GUI 테스트 창 실행
gedit memo.txt        # GUI 텍스트 편집기 실행

# 🚀 [4] NVIDIA GPU 가속 & CUDA 확인 (Windows에 최신 NVIDIA 드라이버만 깔면 WSL 내부 자동 통과)
nvidia-smi
```

## 11. 문제 해결(Troubleshooting) 및 자주 발생하는 오류
자주 마주치는 에러 코드와 즉시 해결하는 처방전입니다.
```powershell
# ⚠️ [오류 1] 0x800701bc (WSL 2 requires an update to its kernel component)
# 원인: Linux 커널 패키지가 구버전이거나 누락됨
# 해결: 커널 업데이트 실행
wsl --update

# ⚠️ [오류 2] 0x80370102 (가상화 지원이 비활성화되어 있습니다)
# 원인: 메인보드 BIOS/UEFI에서 CPU 가상화(Intel VT-x / AMD SVM) 미활성화
# 해결: BIOS 진입하여 CPU Virtualization 활성화 + Windows 기능 활성화:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# ⚠️ [오류 3] Wsl/Service/CreateInstance/CreateVm/0x80040326
# 원인: Windows 빌드가 오래되었거나 Hyper-V 관련 드라이버 충돌
# 해결: Windows 최신 업데이트 설치 및 PowerShell(관리자)에서 서비스 재시작:
Get-Service LxssManager | Restart-Service

# 🔑 [오류 4] Linux 일반 사용자 계정 비밀번호를 잊어버렸을 때
# 해결: PowerShell에서 root 권한으로 접속 후 passwd 재설정
wsl -u root
# (Linux 내부 진입 후)
passwd <계정아이디>
exit

# 🌐 [오류 5] Linux 내부에서 인터넷/DNS가 안 잡힐 때 (Temporary failure in name resolution)
# 해결: /etc/resolv.conf 수동 재생성
sudo rm /etc/resolv.conf
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
sudo chattr +i /etc/resolv.conf   # 파일 수정 방지 잠금 (선택 사항)
```
💬
WSL2 치트시트

의견 및 질문

댓글 수정

댓글 삭제
