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