Preparing for a vSphere migration, especially in enterprise environments with hundreds of Virtual Machines, demands meticulous planning. Thorough preliminary analysis is crucial to prevent service disruptions, compatibility issues, and unexpected delays. I’ve managed environment migrations involving over 300 VMs and 300+ servers, and experience has taught me that the pre-check phase determines the success or failure of the entire process. Without systematic verification, you risk discovering network incompatibilities, insufficient storage, or incorrect configurations only after the migration has begun, leading to high operational costs and a direct impact on business continuity. This article describes a PowerShell script to automate much of this analysis, providing a detailed report that enables proactive action.
Tested on: VMware vSphere 8.0 · PowerShell 7.4 · September 2026
Prerequisites / Test Environment
To run the script, you need a system with PowerShell (preferably PowerShell Core 7.x or higher) and the VMware PowerCLI module installed and configured. Ensure you have the necessary credentials to connect to your vCenter Server with read-only permissions on all VMs, hosts, and datastores. It’s advisable to execute the script from a dedicated management machine.
PowerCLI Installation:
Install-Module -Name VMware.PowerCLI -Scope CurrentUser
Set-PowerCLIConfiguration -Scope User -ParticipateInCEIP $false -Confirm:$falseConnect to vCenter Server:
Connect-VIServer -Server your_vcenter_fqdn -User your_username -Password your_passwordReplace your_vcenter_fqdn, your_username, and your_password with the correct values for your environment. For security reasons, consider using managed credentials or integrated authentication if available.
vSphere Pre-Migration Verification Script
This PowerShell script gathers crucial information about your vSphere environment, focusing on aspects that often cause issues during migrations. The output is structured to facilitate analysis and rapid identification of potential obstacles.
# vSphere Pre-Migration Verification Script
# Function to export data to CSV
function Export-Report {
param(
[Parameter(Mandatory=$true)]
[string]$ReportName,
[Parameter(Mandatory=$true)]
$Data
)
$Timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
$FileName = "vSphere_PreMig_Report_$(($ReportName -replace ' ' -replace '\(','' -replace '\)','') | Select -First 30)_$Timestamp.csv"
$Data | Export-Csv -Path $FileName -NoTypeInformation -UseCulture
Write-Host "Report '$ReportName' exported to: $FileName"
}
Write-Host "Starting vSphere environment analysis..."
# 1. Collect VM information
Write-Host "Detecting VMs..."
$vmInfo = Get-VM | Select Name, PowerState, NumCpu, MemoryGB, GuestId, Version, @{N='VMHost';E={$_.VMHost.Name}}, @{N='NetworkAdapter';E={($_.NetworkAdapters | Select -ExpandProperty NetworkName) -join ', '}}, @{N='Disks';E={($_.HardDisks | Select -ExpandProperty Name) -join ', '}}, @{N='Snapshots';E={($_.Snapshot | Select -ExpandProperty Name) -join ', '}}
Export-Report -ReportName "VM_General_Info" -Data $vmInfo
# 2. Detect VMs with active snapshots
Write-Host "Detecting active snapshots..."
$vmSnapshots = Get-VM | Get-Snapshot | Select VM, Name, Created, SizeGB
if ($vmSnapshots) {
Export-Report -ReportName "VM_Active_Snapshots" -Data $vmSnapshots
Write-Warning "Active snapshots detected. It is recommended to consolidate them before migration."
}
# 3. Detect VMs with RDM (Raw Device Mapping) disks
Write-Host "Detecting RDM disks..."
$vmRDM = Get-VM | Get-HardDisk -DiskType "RawPhysical", "RawVirtual" | Select Parent, Name, DiskType, CapacityGB, @{N='Datastore';E={$_.ExtensionData.Backing.FileName.Split("[")[-1].Split("]")[0]}}
if ($vmRDM) {
Export-Report -ReportName "VM_RDM_Disks" -Data $vmRDM
Write-Warning "RDM disks detected. These require special handling during migration."
}
# 4. Detect VMs with outdated or uninstalled VMware Tools
Write-Host "Detecting VMware Tools status..."
$vmToolsStatus = Get-VM | Select Name, GuestId, @{N='ToolsStatus';E={$_.ExtensionData.Guest.ToolsStatus}}, @{N='ToolsVersion';E={$_.ExtensionData.Guest.ToolsVersionStatus}}
Export-Report -ReportName "VM_Tools_Status" -Data $vmToolsStatus
# 5. Detect storage usage per datastore
Write-Host "Detecting datastore usage..."
$datastoreUsage = Get-Datastore | Select Name, Type, CapacityGB, FreeSpaceGB, @{N='UsedSpaceGB';E={$_.CapacityGB - $_.FreeSpaceGB}}, @{N='FreeSpacePercent';E={($_.FreeSpaceGB / $_.CapacityGB * 100).ToString("N2")}}
Export-Report -ReportName "Datastore_Usage" -Data $datastoreUsage
# 6. Detect ESXi hosts and their network configuration (vSwitch/PortGroup)
Write-Host "Detecting host network configuration..."
$hostNetwork = Get-VMHost | Get-VirtualSwitch | Select VMHost, Name, NumPorts, @{N='PortGroups';E={($_.PortGroups | Select -ExpandProperty Name) -join ', '}}
Export-Report -ReportName "Host_Network_Config" -Data $hostNetwork
Write-Host "Analysis complete. Check the generated CSV files in the current directory."Output and Data Analysis
The script will generate several CSV files, each containing a specific dataset. Analyze these reports carefully:
- VM_General_Info.csv: Provides a basic overview of all VMs. Check power state (
PowerState), hardware version (Version), and networks (NetworkAdapter). Outdated hardware versions might require an upgrade before migration. Read also: VMware Hardware Version: When and Why Upgrade - VM_Active_Snapshots.csv: Lists all VMs with active snapshots. Snapshots must be consolidated before initiating a migration, especially if you plan a vMotion between different datastores or hosts. Leaving active snapshots can cause performance issues and increase the risk of data corruption or significant transfer slowdowns.
- VM_RDM_Disks.csv: Identifies VMs with RDM disks. Managing RDMs during a migration is complex and requires specific planning, often involving conversion to VMDK or using advanced storage solutions.
- VM_Tools_Status.csv: Shows the status and version of VMware Tools. Outdated or uninstalled VM Tools can limit VM functionality post-migration, including shutdown management, network and disk performance, and compatibility with new vSphere features. Ensure they are updated for all critical VMs.
- Datastore_Usage.csv: Provides a clear view of datastore utilization. Verify that there is sufficient space in the destination datastore for the VMs to be migrated, also considering temporary space required for operations like vMotion or Storage vMotion.
- Host_Network_Config.csv: Details the network configuration of ESXi hosts. Check that vSwitches and port groups are correctly configured and reflect the desired network topology in the target environment. Discrepancies here can lead to connectivity problems after migration. A common approach is to use official VMware documentation for network configuration.
Common Errors and Troubleshooting
Connect-VIServerfails: Check the vCenter FQDN/IP, credentials, and network connectivity from the machine running the script. Ensure that the firewall is not blocking port 443 (HTTPS) to vCenter.- Insufficient permissions: If the script fails to retrieve all information, the user account used likely lacks the necessary permissions. Verify the roles and privileges assigned to the user on vCenter Server. Read-only permissions on VM, Host, Datastore, and Network objects are required.
- PowerCLI module not found: If you receive errors related to unknown cmdlets (
Get-VM,Connect-VIServer), ensure theVMware.PowerCLImodule is correctly installed and imported into the PowerShell session. - Empty or incomplete CSV output: This might indicate connection issues to vCenter (even if
Connect-VIServersucceeded) or limited permissions. Re-attempt the connection and check vCenter logs for errors.
FAQ — Frequently Asked Questions
Can this script be run in production without risks?
Yes, the script only performs read operations (Get-*) and makes no modifications to the vSphere environment. It is safe to run in a production environment. However, as a best practice, always run any script first in a test environment or with a user with minimal privileges to familiarize yourself with the output.
Is it possible to customize the output or add other checks?
Absolutely. This script is a baseline. You can modify it to include checks specific to your environment, such as verifying certain Guest OS versions, the presence of USB passthrough devices, or vGPU configuration. Every Get-* PowerCLI cmdlet offers a wide range of properties and filters.
How can I automate the regular execution of this script?
You can schedule the script’s execution using Windows Task Scheduler or cron on Linux (if using PowerShell Core) on a dedicated machine. It’s advisable to redirect console output to a log file and send the CSV reports via email for automated periodic review.
What is the difference between PowerCLI and vSphere API?
PowerCLI is a PowerShell-based command-line interface that interacts with the vSphere APIs. The vSphere APIs (Application Programming Interface) are the underlying set of programming interfaces that vCenter Server exposes for programmatic interaction. PowerCLI simplifies interaction with these APIs by providing easy-to-use cmdlets.
Conclusions with Operational Takeaways
Preparation is the cornerstone of every successful vSphere migration. This PowerShell script provides a robust framework to automate the pre-check phase, transforming a potentially chaotic process into a series of clear, documented steps. Investing time in pre-analysis dramatically reduces the risks of downtime and ensures a smooth transition for your workloads. Don’t rely on chance: verify, document, and plan every detail to protect operational continuity.
Sources
Updated: September 2026
