The Mystery of Phantom Disk Space in WSL: When Deletion Doesn’t Free Up Space

For anyone using Windows Subsystem for Linux (WSL) for development, encountering a scenario where deleting hefty files barely makes a dent in your Windows disk space can be all too familiar. This isn’t a bug—it’s a quirk of how WSL manages its virtual storage. In this article, we delve into why disk space seems “stuck” even after file removal, and we introduce an automated solution designed to simplify reclaiming that lost space.

Uncovering the Hidden Mechanics Behind WSL’s Phantom Disk Space

When you delete large files within your WSL environment, you might expect an immediate reduction in your Windows disk usage. However, the reality is more nuanced. Let’s break down the underlying factors:

1. Virtual Disk Characteristics

WSL2 leverages a dynamically allocated virtual disk file (typically named ext4.vhdx) to store the Linux filesystem. Here’s what you need to know:

• Expansion Without Automatic Contraction:
  The VHDX file expands as you add data, but—by design—it does not shrink automatically when you delete files.
• Perceived vs. Actual Free Space:
  Within the Linux environment, the filesystem reports the freed space correctly. In contrast, Windows continues to see the unchanged size of the VHDX file.

To illustrate, consider the following table:

2. Dual Layered Disk Space Management

WSL2 essentially employs two separate layers of disk management:

• Inside Linux:
  • When you delete files, the Linux filesystem immediately recognizes the reclaimed space.
  • This makes it seem as though storage has been freed.
• On the Windows Host:
  • The underlying VHDX file remains at its expanded size.
  • No automatic process compresses or shrinks this virtual disk, leaving Windows unaware of the freed space.

This disparity between the two layers is what creates the “phantom” disk space issue.

3. Limitations in Dynamic Shrinking

Currently, WSL2 lacks an automatic mechanism to reclaim the unused space within the VHDX file. Key limitations include:

• No Auto-Deallocation:
  Unused space inside the virtual disk isn’t automatically released.
• Absence of Built-In Shrinking Functions:
  Users must manually initiate disk compaction to reclaim wasted space.
• Necessity for External Tools or Scripts:
  Without intervention, the discrepancy between internal and external disk usage persists.

A Real-World Lesson: From Frustration to Innovation

A while back, I published an in-depth guide detailing manual steps to address this issue. However, feedback from a friend—who admitted the technical jargon made the process hard to follow—sparked a crucial realization: Even the most detailed guides can fail when they’re not user-friendly.

This experience drove me to develop an automated solution that anyone, regardless of technical expertise, can use. By streamlining the process into a few simple steps, this tool takes the guesswork out of reclaiming lost disk space in WSL.

For those interested in the original manual procedure, please refer to the detailed guide here:
In-Depth WSL Disk Optimization Guide

A certain site

WSL, Docker, and VirtualBox Disk Management: Reclaim Freed Space on Windows Discover why your disk usage barely changes after deleting files in WSL, Docker, or VirtualBox. Learn practical zero-fill and compaction methods to truly free u…

Introducing the Automated WSL Disk Compaction Script

To address the phantom disk space issue without delving into complicated manual processes, I’ve developed an automated script that simplifies everything. This solution comes in two flavors:

A. PowerShell Script (.ps1)

This script is designed to automatically:

• Locate the VHDX File:
  It searches for the ext4.vhdx file (commonly found in the local app data directory for Ubuntu installations).
• Ensure Safe Operation:
  Before any operation, the script detaches the disk if it’s currently in use to avoid conflicts.
• Execute Disk Compaction:
  It mounts the virtual disk in a read-only mode and runs the diskpart command to compact the VHDX file—effectively releasing the unutilized space.
• Handle Errors Gracefully:
  Robust error handling ensures that any issues during the process are communicated clearly, and temporary files are cleaned up.

Here’s an overview of the workflow:

Remember:

• Prerequisites:
  • Ensure WSL is stopped using wsl --shutdown.
  • Run PowerShell as an administrator.

B. Batch Script (.bat)

For users who prefer or require a more direct approach—especially if you already know the location of your VHDX file—there’s a batch script alternative. This version:

• Verifies the VHDX File Location:
  Checks if the specified virtual disk file exists.
• Generates and Executes a diskpart Script:
  Automates the compaction process using a pre-configured set of commands.
• Includes Comprehensive Error Handling:
  Ensures that each step is verified, and any issues are promptly reported.

Key Advantages of the Batch Script:

• Ideal for environments with multiple WSL instances.
• Particularly useful if you have installed WSL in a custom location.
• Simple to configure—just specify the path to your VHDX file.

How to Save and Execute the Scripts

1. PowerShell Script (.ps1)

Saving the Script:

1. Copy the provided PowerShell code.
2. Paste it into your preferred text editor (such as Notepad or Visual Studio Code).
3. Save the file with a clear name like WSL_Compact.ps1.

#----------------------------------------------
# Script to automatically detect the WSL VHD file and, if it is already attached,
# detach it before executing diskpart to compact it.
#----------------------------------------------
# Please stop WSL beforehand (e.g., wsl --shutdown)
# Run PowerShell with administrative privileges

# Function to create and execute a temporary script for diskpart
function Invoke-DiskPartScript {
    param (
        [Parameter(Mandatory)]
        [string]$ScriptContent
    )
    # Create a random temporary filename
    $tempFile = Join-Path $env:TEMP ("dp_" + [System.IO.Path]::GetRandomFileName() + ".txt")
    try {
        # Write the temporary file using ASCII encoding
        $ScriptContent | Out-File -FilePath $tempFile -Encoding ascii
        Write-Host "Executing diskpart: $tempFile" -ForegroundColor Yellow
        # Capture and display the output from diskpart
        $result = diskpart /s $tempFile 2>&1
        Write-Host $result
    }
    finally {
        if (Test-Path $tempFile) {
            Remove-Item $tempFile -Force
        }
    }
}

try {
    # Recursively search for the ext4.vhdx path (for the Ubuntu package)
    $wslVhd = Get-ChildItem "$env:LOCALAPPDATA\Packages\*Ubuntu*\LocalState\ext4.vhdx" -Recurse -ErrorAction Stop | Select-Object -First 1

    if (-not $wslVhd) {
        throw "WSL VHD file not found. Please ensure the Ubuntu package is installed."
    }

    Write-Host "Found VHD file: $($wslVhd.FullName)" -ForegroundColor Green

    # ★ Since the VHD might already be attached, first attempt to detach it ★
    $detachScript = @"
select vdisk file="$($wslVhd.FullName)"
detach vdisk
"@

    Write-Host "Detaching the possibly attached VHD..." -ForegroundColor Yellow
    Invoke-DiskPartScript -ScriptContent $detachScript

    # Main process: attach (read-only) → compact → detach
    $compactScript = @"
select vdisk file="$($wslVhd.FullName)"
attach vdisk readonly
compact vdisk
detach vdisk
"@

    Write-Host "Executing compact operation with diskpart..." -ForegroundColor Yellow
    Invoke-DiskPartScript -ScriptContent $compactScript

    Write-Host "Operation completed successfully." -ForegroundColor Green

} catch {
    Write-Error "An error occurred: $_"
    exit 1
}

Executing the Script:

1. Open PowerShell as Administrator:
   Right-click on the Windows PowerShell icon and select “Run as Administrator.”
2. Navigate to the Script Directory:
   cd "C:\Path\To\Your\Script\Directory"
3. Set the Execution Policy (if necessary):
   Set-ExecutionPolicy RemoteSigned -Scope Process
4. Run the Script:
   .\WSL_Compact.ps1

2. Batch Script (.bat)

Saving the Script:

1. Copy the provided batch script code.
2. Paste it into a text editor.
3. Save the file as WSL_Compact.bat (ensure the extension is .bat).

@echo off
setlocal enabledelayedexpansion

REM ================================================
REM Please specify the path to the WSL VHD(X) file.
REM Example: set "VHD_FILE=%LOCALAPPDATA%\Packages\...\LocalState\ext4.vhdx"
REM ================================================
set "VHD_FILE=C:\wsl\ubuntu24.04lts\ext4.vhdx"

REM Check if the VHD file exists
if not exist "%VHD_FILE%" (
    echo ERROR: The specified VHD file was not found: "%VHD_FILE%"
    pause
    exit /b 1
)

REM Set the path for the temporary diskpart script file
set "DP_SCRIPT=%TEMP%\dp_script.txt"

REM Create the diskpart script
(
    echo select vdisk file="%VHD_FILE%"
    echo attach vdisk readonly
    echo compact vdisk
    echo detach vdisk
) > "%DP_SCRIPT%"

if errorlevel 1 (
    echo ERROR: Failed to create the temporary script file.
    pause
    exit /b 1
)

REM Execute diskpart
echo -------------------------------
echo Executing diskpart...
diskpart /s "%DP_SCRIPT%"
if errorlevel 1 (
    echo ERROR: An issue occurred while running diskpart.
    del "%DP_SCRIPT%" >nul 2>&1
    pause
    exit /b 1
)

REM Delete the temporary script file
del "%DP_SCRIPT%" >nul 2>&1
if exist "%DP_SCRIPT%" (
    echo WARNING: Failed to delete the temporary script file: "%DP_SCRIPT%"
) else (
    echo The temporary script file was deleted.
)

echo -------------------------------
echo Operation completed successfully. Well done!
pause
endlocal

Executing the Script:

1. Run as Administrator:
   Right-click the file and select “Run as Administrator”
   or
   Open an elevated Command Prompt, navigate to the script directory, and execute:
   WSL_Compact.bat

GitHub

GitHub – superdoccimo/VHDX Contribute to superdoccimo/VHDX development by creating an account on GitHub.

Important Final Reminders

Before running either script, please keep in mind:

• Stop WSL First:
  Always run wsl --shutdown to ensure no instances of WSL are active.
• Administrator Rights Are a Must:
  Both scripts require elevated permissions to function correctly.
• Backup Your Data:
  Since these scripts directly interact with your virtual disk file, make sure to back up important data beforehand.
• Test in Your Environment:
  Although designed for standard setups, variations in system configurations can occur. Test the script in your environment to confirm safe operation.
• Use at Your Own Risk:
  The provided scripts are intended as a convenience tool. Please exercise caution and ensure you fully understand the steps involved before execution.