VMSnapshotCleanup

VMSnapshotCleanup is a PowerShell utility for resetting VMware Workstation virtual machines from a known-good snapshot and cleaning up old backup folders.

It is designed for local test environments where you often need to return a VM to a clean baseline before trying another setup, installer, lab exercise, or troubleshooting path.

Why It Exists

Manual VM reset workflows can become repetitive and error-prone:

• find the correct .vmx file
• choose the right snapshot
• clone or restore the VM
• keep a backup of the previous state
• clean up old backup folders later

VMSnapshotCleanup wraps that flow into a repeatable PowerShell script with interactive and parameter-based usage.

Features

• Detects VMware vmrun.exe from common Windows install paths.
• Supports a default VM search location under the user's Documents\Virtual Machines folder.
• Finds snapshots that match a configurable tag, using (OK) by default.
• Clones a VM from the selected snapshot into a clean state.
• Moves the previous VM folder into a _Trash_ backup location before replacement.
• Provides an interactive menu for VM selection and backup cleanup.
• Supports direct scripted usage with a .vmx path.

Requirements

• Windows 10 or Windows 11.
• PowerShell 5.1 or newer.
• VMware Workstation Pro or Player with vmrun.exe available.
• A VM snapshot whose name contains the expected snapshot tag, such as (OK).

Safety Notes

This script changes local VM folders. Before using it on important machines:

• Test it first on a disposable VM.
• Make sure the target VM is powered off.
• Confirm that the selected snapshot is the intended clean baseline.
• Review the _Trash_ backup folder before deleting old backups.
• Keep separate backups for any VM data that cannot be recreated.

Installation

Clone the repository:

git clone https://github.com/AlexMnrs/VMSnapshotCleanup.git
cd VMSnapshotCleanup

If PowerShell blocks local scripts, run the script from a trusted location or use an execution policy appropriate for your environment.

Usage

Interactive Mode

Run the script without parameters:

.\Invoke-VMSnapshotCleanup.ps1

The menu lets you:

1. Select a detected VM.
2. Choose a snapshot, with preference for names containing (OK).
3. Manage cleanup of old _Trash_ backup folders.

Direct VM Path

Pass the full path to a .vmx file:

.\Invoke-VMSnapshotCleanup.ps1 -Path "D:\VMs\ClientLab\ClientLab.vmx"

Custom Snapshot Tag

Use -SnapshotTag if your baseline snapshots use a different name:

.\Invoke-VMSnapshotCleanup.ps1 -Path "D:\VMs\ClientLab\ClientLab.vmx" -SnapshotTag "CleanInstall"

Verification Ideas

Before relying on the workflow, validate it with a test VM:

# Confirm the script parses correctly
$null = [System.Management.Automation.PSParser]::Tokenize((Get-Content .\Invoke-VMSnapshotCleanup.ps1 -Raw), [ref]$null)

# Run against a disposable VM first
.\Invoke-VMSnapshotCleanup.ps1 -Path "D:\VMs\Disposable\Disposable.vmx"

Contributing

Careful improvements are welcome. See CONTRIBUTING.md for safety expectations, validation notes, and pull request guidelines.

Changelog

See CHANGELOG.md for notable project changes.

License

This project is released under the MIT License. See LICENSE for details.