Deleting 500 GB inside a Linux virtual machine does not necessarily reduce the VMDK allocation or the physical storage usage immediately. Free space must be communicated through several layers, and each layer reports a different number.
On a normal thin-provisioned Linux VMDK on VMFS 6, the preferred path is online discard from the guest followed by asynchronous reclamation on the datastore. vmkfstools --punchzero is an offline fallback for specific legacy cases, not the second half of every fstrim command.
Understand the Four Space Counters
Linux filesystem free blocks
↓ discard/TRIM
thin VMDK allocated blocks
↓ VMFS tracking
VMFS datastore free space
↓ SCSI UNMAP or NVMe deallocate
backing array or device allocation
These values can disagree without corruption:
dfshows free space inside the guest filesystem;- vCenter shows virtual capacity and actual datastore consumption;
- VMFS shows free blocks available to the host;
- a thin SAN, NVMe namespace, or storage pool shows physical allocation underneath VMFS.
A local hardware RAID logical volume is commonly fixed-capacity from ESXi’s perspective. Reclaiming a VMDK can return space to VMFS for other VMs even when there is no thinner array pool below it.
Prerequisites for Guest-Initiated Reclamation
Confirm all of these before running commands:
- The virtual disk is thin provisioned.
- The guest filesystem and virtual controller support discard.
- The virtual hardware exposes the required UNMAP capability.
- Snapshots or filters are not interfering with the expected allocation view.
- The datastore is VMFS 6 with reclamation enabled for the relevant layer.
- The backing device supports the needed deallocate primitive if array-level reclamation is expected.
Broadcom’s current Linux guest UNMAP troubleshooting article documents a case where virtual hardware earlier than version 13 does not expose Write Same with UNMAP, causing fstrim to fail with an I/O error. A hardware-version upgrade requires the VM to be powered off and should follow the compatibility and backup process for that VM.
Verify the VMDK Provisioning Type
In vSphere Client, inspect the virtual disk’s provisioning. With PowerCLI, Broadcom documents reading the backing flags:
Get-VM 'vm-name' | Get-HardDisk |
Select-Object Filename,
@{N='Thin';E={$_.ExtensionData.Backing.ThinProvisioned}},
@{N='EagerZeroed';E={$_.ExtensionData.Backing.EagerlyScrub}}
Broadcom’s VMDK provisioning reference explains the flags. A thick disk can have free filesystem blocks, but its VMFS allocation is intentionally preallocated. Do not expect ordinary discard to turn it into a thin disk.
Run and Verify fstrim Inside Linux
First see whether the guest block device advertises discard:
lsblk --discard
findmnt -o TARGET,SOURCE,FSTYPE,OPTIONS
Then trim the intended mounted filesystem:
sudo fstrim -v /
Or trim all eligible mounted filesystems:
sudo fstrim --all --verbose
fstrim tells lower layers which filesystem blocks are unused. It does not shrink the guest’s virtual disk capacity. A 1 TB virtual disk remains a 1 TB virtual disk; fewer backing blocks may be allocated.
Run trimming while the VM is powered on under the normal supported discard path. Use the distribution’s periodic fstrim.timer for ongoing maintenance where appropriate. A reported trimmed byte count is the range submitted, not proof that the final storage array released exactly that amount.
Let VMFS 6 Reclaim Asynchronously
Broadcom states that VMFS 6 automatic space reclamation is asynchronous: the result appears gradually rather than immediately. Its automatic UNMAP monitoring guide covers ESXi 7.x and 8.x and notes that most modern guests send deallocation requests.
Check the datastore identity before any ESXCLI command:
esxcli storage filesystem list
Copy the exact volume label or UUID. A one-character mismatch such as nvme versus nwme produces “Cannot find VMFS volume” and says nothing about reclamation support.
In vCenter, inspect the datastore’s Space Reclamation setting. Low priority is the normal automatic VMFS 6 mode; Disabled prevents the expected background path. Observe capacity over time and use Broadcom’s documented esxtop/vsish counters when proof of UNMAP activity is required. Those counters can be zero between bursts and reset on reboot.
Do Not Confuse VMDK Reclamation with Datastore UNMAP
Two operations solve different boundaries:
- Guest
fstrimcan deallocate blocks inside a thin VMDK so VMFS can reuse them. esxcli storage vmfs unmaptells compatible backing storage that free VMFS blocks can be released below the datastore.
Running datastore UNMAP cannot discover files deleted inside a guest if the VMDK still owns those blocks. Running guest trim cannot force a storage array to release VMFS free blocks when the backing device does not support UNMAP.
Broadcom’s VMFS reclamation guidance recommends confirming the thin VMDK, guest discard, datastore policy, and VAAI Delete support. Use the storage vendor’s recommended reclaim unit when manual datastore UNMAP is genuinely required.
Know When vmkfstools -K Applies
vmkfstools -K or --punchzero removes zeroed blocks from a compatible thin virtual disk. It does not process arbitrary deleted data; unused blocks must first read as zero. Legacy workflows therefore zero free space in the guest, shut down or detach the disk, and punch holes offline.
This procedure has material risks:
- zero-filling can temporarily grow a thin VMDK toward full capacity;
- insufficient datastore space can cause an outage;
- snapshots must be handled correctly;
- the disk must not be in use;
- the command is not compatible with every datastore or disk type;
- selecting the wrong descriptor or path can damage a VM.
Broadcom’s punchzero guidance explicitly requires no snapshots and shutting down or detaching the disk. Use it only with a verified backup and when supported guest UNMAP cannot meet the requirement.
Diagnose the Layer Where Reclamation Stops
| Observation | Likely boundary |
|---|---|
df shows free space, fstrim reports unsupported/I/O error | Guest device, controller, or virtual hardware does not expose discard correctly |
fstrim succeeds but VMDK allocation does not fall | Snapshots, provisioning, filter, guest capability interpretation, or measurement delay |
| VMDK allocation falls and VMFS free space rises, array does not | Backing storage/VAAI/NVMe deallocate support or datastore UNMAP policy |
| VMFS 6 reclaim moves slowly | Expected asynchronous behaviour or low-priority rate |
| Manual command cannot find the volume | Wrong label/UUID, not a storage capability failure |
| VAAI Delete is unsupported on a local RAID logical volume | VMFS may reuse free space, but no thin-array layer exists to reclaim below it |
For NVMe-backed datastores, do not use SCSI-only checks as definitive evidence. Broadcom’s current NVMe deallocate guide explains that NVMe uses Dataset Management Deallocate and that traditional VAAI status can misleadingly report unsupported.
A Safe Verification Run
Use a noncritical VM and record baseline values at all layers. Create a test file of a controlled size, wait for allocation to appear, delete it, run fstrim, and observe the VMDK and datastore over the asynchronous window. Do not generate a file large enough to threaten datastore headroom.
Success is not “the command returned zero.” It is a traceable sequence: the guest freed blocks, the thin VMDK released allocation, VMFS regained reusable space, and—only where applicable—the backing thin storage received deallocation. Once those boundaries are separated, space reclamation becomes measurable rather than mysterious.
