cleaning-wsl-docker

Danik911 的头像作者 Danik911

回收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 prune frees 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