cleaning-wsl-docker
回收WSL2/Docker占用的SSD磁盘空间。当用户报告磁盘空间问题、由于空间不足导致的Docker构建失败或WSL性能缓慢时使用。处理Docker修剪、缓存清理、VHDX压缩和预防设置。当提到“磁盘已满”、“空间不足”或“VHDX”时必须使用。
📖 中文导读:回收WSL2/Docker占用的SSD磁盘空间。当用户报告磁盘空间问题、由于空间不足导致的Docker构建失败或WSL性能缓慢时使用。处理Docker修剪、缓存清理、VHDX压缩和预防设置。当提到“磁盘已满”、“空间不足”或“VHDX”时必须使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: cleaning-wsl-docker description: Reclaims SSD disk space consumed by WSL2/Docker. Use when user reports disk space issues, Docker build failures due to space, or slow WSL performance. Handles Docker prune, cache cleanup, VHDX compaction, and prevention setup. MUST BE USED when "disk full", "out of space", or "VHDX" mentioned.
WSL2/Docker Disk Space Cleanup
Problem
WSL2 stores all data in ext4.vhdx files that:
- GROW automatically when adding files/building Docker images
- NEVER SHRINK automatically when files are deleted
docker system prunefrees space inside WSL but NOT on Windows SSD
Workflow
PHASE 1: Diagnose → PHASE 2: Cleanup → PHASE 3: Compact VHDX → PHASE 4: Prevent
PHASE 1: Diagnose
Check VHDX Size
# Find VHDX files and sizes
Get-ChildItem -Path "$env:LOCALAPPDATA" -Recurse -Filter "ext4.vhdx" -ErrorAction SilentlyContinue |
Select-Object FullName, @{N='SizeGB';E={[math]::Round($_.Length/1GB,2)}}
Check Docker Usage
wsl -e bash -c "docker system df -v"
PHASE 2: Cleanup (Inside WSL)
Docker Cleanup
wsl -e bash -c "
docker stop \$(docker ps -aq) 2>/dev/null
docker container prune -f
docker image prune -a -f
docker builder prune -a -f
# CAUTION: Only if volumes are disposable
# docker volume prune -f
docker system df
"
Project Caches
wsl -e bash -c "cd /mnt/c/path/to/project && \
rm -rf .mypy_cache .pytest_cache .ruff_cache htmlcov __pycache__ && \
find . -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null"
Unbounded Logs
wsl -e bash -c "rm -rf main/logs/traces/* main/logs/workflow_test* main/logs/langfuse/*"
PHASE 3: Compact VHDX (CRITICAL - Reclaims Windows Space)
IMPORTANT: This phase requires Administrator privileges. The AI agent CANNOT run diskpart directly. You MUST provide manual instructions to the user.
Step 1: Shutdown WSL (AI can run this)
wsl --shutdown
wsl --list --running # Should show "no running distributions"
Step 2: Find VHDX Path (AI can run this)
Get-ChildItem -Path "$env:LOCALAPPDATA" -Recurse -Filter "ext4.vhdx" -ErrorAction SilentlyContinue | Select-Object FullName
Step 3: Update compact-wsl.txt Script
Edit .claude/skills/cleaning-wsl-docker/compact-wsl.txt with the correct VHDX path:
select vdisk file="C:\Users\USERNAME\AppData\Local\wsl\{GUID}\ext4.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit
Step 4: MANUAL USER ACTION REQUIRED
Tell the user to run these commands in Administrator PowerShell:
1. Press Win + X
2. Click "Terminal (Admin)" or "PowerShell (Admin)"
3. Click Yes on UAC prompt
4. Run:
diskpart /s "PROJECT_ROOT/.claude/skills/cleaning-wsl-docker/compact-wsl.txt"
If "file in use" error:
wsl --shutdown
taskkill /F /IM wslservice.exe
taskkill /F /IM wsl.exe
:: Wait 10 seconds, retry diskpart
Step 5: Verify (AI can run after user completes)
Get-ChildItem -Path "$env:LOCALAPPDATA" -Recurse -Filter "ext4.vhdx" | Select-Object FullName, @{N='SizeGB';E={[math]::Round($_.Length/1GB,2)}}
PHASE 4: Prevent Future Bloat
Update .wslconfig
Add to C:\Users\USERNAME\.wslconfig:
[experimental]
sparseVhd=true # Auto-reclaim space (WSL 2.0+)
autoMemoryReclaim=gradual
Then: wsl --shutdown to apply.
Weekly Maintenance
# Run in Admin PowerShell
wsl -e bash -c "docker container prune -f && docker image prune -a -f && docker builder prune -a -f"
wsl --shutdown
# Then run diskpart compact
Expected Recovery
| Action | Recovery |
|---|---|
| Docker image prune | 2-10 GB |
| Docker builder prune | 10-100 GB |
| Cache cleanup | 200-500 MB |
| VHDX compaction | 5-50 GB |
Checklist
- Diagnose: Check VHDX size and Docker usage
- Docker: Prune containers, images, build cache
- Caches: Remove .mypy_cache, .pytest_cache, etc.
- Logs: Clean unbounded log directories
- WSL: Shutdown completely
- VHDX: Compact using diskpart (Admin required)
- Prevent: Enable sparseVhd in .wslconfig