Docker WSL Disk Cleanup & Compact Script

A PowerShell script for automated Docker maintenance on Windows with WSL2 backend. This script performs monthly Docker cleanup and virtual disk compaction to prevent disk space bloat and maintain optimal Docker performance.

Overview

Docker Desktop with WSL2 backend can accumulate significant disk space over time due to:

• Unused containers, images, and build cache
• WSL2 virtual disk files that grow but never shrink automatically
• Dangling volumes and networks

This script automates the cleanup process and can reclaim substantial disk space (users typically see 20-140GB+ freed during initial runs).

Features

• ✅ Automated Docker cleanup - Removes unused containers, images, networks, and build cache
• ✅ WSL2 virtual disk compaction - Shrinks Docker's virtual disk file to actual usage size
• ✅ Graceful Docker daemon shutdown - Prevents "WSL distro terminated abruptly" errors
• ✅ Comprehensive logging - Detailed logs for monitoring and troubleshooting
• ✅ Safe restart sequence - Ensures Docker Desktop restarts cleanly after maintenance
• ✅ Multiple fallback methods - Handles different Docker Desktop versions and configurations
• ✅ Production ready - Designed for unattended monthly automation

Prerequisites

• Windows 10/11 with WSL2 enabled
• Docker Desktop with WSL2 backend
• PowerShell 5.1 or later
• Administrator privileges (required for diskpart operations)

Installation

1. Download the script to your preferred location (e.g., C:\Scripts)
2. Create the log directory: New-Item -ItemType Directory -Path "C:\Logs" -Force
3. Test the script by running it manually first

Usage

Manual Execution

Run as Administrator

.\docker_wsl_compact_vdisk.ps1

Custom Log Location

.\docker_wsl_compact_vdisk.ps1 -LogPath "D:\MyLogs\DockerCleanup.log"

Automated Scheduling

Option 1: Windows Task Scheduler (Recommended)

1. Open Task Scheduler as Administrator
2. Create Basic Task → Name: "Docker Monthly Cleanup"
3. Trigger: Monthly (first Sunday at 3:00 AM recommended)
4. Action: Start a program
   • Program: powershell.exe
   • Arguments: -ExecutionPolicy Bypass -File "C:\Scripts\docker_wsl_compact_vdisk.ps1"
5. Settings:
   • ✅ Check "Run with highest privileges" (REQUIRED)
   • ✅ Check "Run whether user is logged on or not"
   • Configure for: Windows 10/11

Option 2: PowerShell Scheduled Job

Run once as Administrator to create the scheduled job

First command - create the trigger

$trigger = New-JobTrigger -Weekly -WeeksInterval 4 -DaysOfWeek Sunday -At 3AM

Second command - register the scheduled job (user-agnostic)

Register-ScheduledJob -Name "DockerMonthlyCleanup" -ScriptBlock { & "$env:USERPROFILE\dev\docker_wsl_compact_vdisk\docker_wsl_compact_vdisk.ps1" } -Trigger $trigger

What the Script Does

1. Docker Cleanup Phase

• Removes all unused containers
• Removes all unused images (including dangling images)
• Removes all unused networks
• Clears Docker build cache
• Reports space reclaimed

2. Graceful Shutdown Phase

• Stops Docker daemon using docker desktop stop
• Terminates Docker WSL distros if needed
• Safely shuts down WSL subsystem

3. Disk Compaction Phase

• Locates Docker's WSL virtual disk (docker_data.vhdx)
• Uses Windows diskpart to compact the virtual disk
• Reports actual disk space reclaimed

4. Restart Phase

• Kills any lingering Docker processes
• Restarts Docker Desktop using docker desktop start CLI (preferred)
• Falls back to launching Docker Desktop.exe if CLI unavailable
• Waits for Docker daemon to be ready (up to 3 minutes)
• Verifies successful startup

Expected Results

Initial Run

• Docker cleanup: 5-50GB typically freed
• Disk compaction: 20-140GB+ reclaimed from bloated virtual disk
• Total time: 2-5 minutes

Monthly Runs

• Docker cleanup: 2-20GB freed (depends on usage)
• Disk compaction: 1-10GB reclaimed
• Total time: 1-3 minutes

Log Files

Logs are stored at C:\Logs\DockerCleanup.log by default and include:

• Timestamp for each operation
• Docker disk usage before/after cleanup
• Space reclaimed by each phase
• Any errors or warnings
• Complete diskpart output for troubleshooting

Sample Log Output

2025-09-16 01:26:39 - === Starting Docker Monthly Cleanup === 2025-09-16 01:26:44 - Initial usage: Images: 8.069GB, Containers: 64.88MB, Volumes: 25.76GB 2025-09-16 01:26:45 - Gracefully stopping Docker daemon... 2025-09-16 01:27:11 - Docker daemon stopped successfully via CLI 2025-09-16 01:27:17 - Initial VHDX size: 40.22 GB 2025-09-16 01:27:45 - Final VHDX size: 40.22 GB 2025-09-16 01:27:52 - Docker is ready. Version: 27.4.0 2025-09-16 01:27:52 - === Docker Monthly Cleanup Completed Successfully ===

Troubleshooting

Docker Won't Start After Scheduled Task Runs

• Cause: Scheduled task not running with highest privileges
• Solution: Edit scheduled task → Check "Run with highest privileges"
• Note: The docker desktop start CLI command requires admin rights to work from scheduled tasks

Docker Desktop Won't Start (Manual Intervention Needed)

• Symptoms: Script completes but Docker doesn't start automatically
• Manual fix:
  1. Open Task Manager → End all Docker processes
  2. Launch Docker Desktop from Start menu
• Prevention: Ensure scheduled task has "Run with highest privileges" checked

"Access Denied" Errors

• Cause: Script not running as Administrator
• Solution: Always run PowerShell as Administrator or enable "Run with highest privileges" in Task Scheduler

Script Can't Find Docker Disk

• Cause: Non-standard Docker installation location
• Solution: Check script logs for actual disk location and update path

PowerShell Execution Policy Error

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Technical Details

Docker Disk Locations

The script automatically detects Docker's WSL disk in these locations:

• %LOCALAPPDATA%\Docker\wsl\disk\docker_data.vhdx (primary)
• %LOCALAPPDATA%\Docker\wsl\data\ext4.vhdx (fallback)

Supported Docker Versions

• Docker Desktop 4.0+ with WSL2 backend
• Works with both Windows Home and Pro editions

Safety Features

• Administrator check - Prevents permission issues
• Docker readiness verification - Ensures Docker is operational before cleanup
• Multiple shutdown methods - Graceful → Forceful fallback
• Error handling - Comprehensive try/catch blocks
• Process verification - Confirms each step before proceeding

License

This script is provided as-is for personal and commercial use. No warranty implied.

---

Disk space is precious. Keep your Docker installation clean! 🐳✨