PowerShell Upgrade and Migration: A Practical Guide with Examples

Intro

PowerShell upgrades are among the highest-leverage changes you can make to your Windows and cross-platform automation. PowerShell 7 brings a modern runtime, better performance, and long-term maintainability while preserving familiar syntax and tooling. The safest path is side-by-side installation with Windows PowerShell 5.1, careful module and script validation, and a rollback plan you can execute in minutes.

This practitioner guide focuses on:

Inventory: versions, modules, scripts, profiles, scheduled tasks, and policies.
A safe migration path: side-by-side installation and small, observable pilots.
Verification: commands, expected results, and diagnostics.
Failure modes and recovery: predictable rollbacks and confirmation checks.
A repeatable checklist for teams.

A narrow, measurable pilot that you can inspect locally before deployment is the fastest way to reduce risk and build confidence for a wider rollout.

Version and Environment Inventory

Know what you have before you change it. Capture the baseline once, store it with your infrastructure documentation, and reuse it in future audits.

1) Core version and host

Run the following in each environment where you plan to upgrade:

# Version and host details
$PSVersionTable
Get-Host | Select-Object Name, Version

# OS architecture and platform
[Environment]::Is64BitOperatingSystem
Get-CimInstance Win32_OperatingSystem | Select-Object Caption, Version, OSArchitecture

Expected result: You can clearly see whether you are on Windows PowerShell 5.1 (powershell.exe) or PowerShell 7+ (pwsh.exe), plus OS version and architecture.

2) Module inventory and paths

# List installed modules and versions
Get-Module -ListAvailable | Sort-Object Name, Version | Select-Object Name, Version, Path

# Where PowerShell looks for modules
($env:PSModulePath -split ';') | ForEach-Object { $_.Trim() }

Record any critical modules that are Windows-only or rely on .NET Framework APIs.

3) Scripts, scheduled tasks, and services

Find scripts likely to be affected by the host change (powershell.exe to pwsh.exe):

# Inventory scripts in a repo or filesystem root
$root = 'C:\Automation'  # constructed example path
Get-ChildItem -Path $root -Recurse -Filter *.ps1 | Select-Object FullName

Find scheduled tasks that call powershell.exe:

Get-ScheduledTask |
Where-Object { $_.Actions.Execute -match 'powershell.exe' } |
Select-Object TaskName, TaskPath, @{n='Action';e={$_.Actions.Execute}}, @{n='Args';e={$_.Actions.Arguments}}

Record services or scripts started by Windows services that embed a path to powershell.exe.

4) Execution policy and profiles

# Execution policy across scopes
Get-ExecutionPolicy -List

# Profile files across hosts
$profiles = [pscustomobject]@{
    CurrentUserAllHosts = $PROFILE.CurrentUserAllHosts
    CurrentUserCurrentHost = $PROFILE.CurrentUserCurrentHost
    AllUsersAllHosts = $PROFILE.AllUsersAllHosts
    AllUsersCurrentHost = $PROFILE.AllUsersCurrentHost
}
$profiles
$profiles.PSObject.Properties | ForEach-Object {
    $_.Name, (Resolve-Path $_.Value -ErrorAction SilentlyContinue) -join ': '
}

Expected result: You have a list of profile scripts to preserve and a clear picture of execution policies.

Inventory cheatsheet

Engine version: $PSVersionTable — record PS edition and version (5.1 vs 7.x).
Modules: Get-Module -ListAvailable — record critical module names and versions.
Module paths: $env:PSModulePath -split ';' — note user vs system module directories.
Scripts: Get-ChildItem -Recurse *.ps1 — list critical scripts and owners.
Scheduled tasks: Get-ScheduledTask | Where-Object { $_.Actions.Execute -match 'powershell.exe' } — capture task names and arguments.
Profiles: $PROFILE variants — record paths to migrate or preserve.

Safe Configuration Path

The safest upgrade approach is side-by-side installation of PowerShell 7 while keeping Windows PowerShell 5.1 available. This lets you test without breaking existing jobs.

1) Install side-by-side

On Windows, use a package manager or MSI. Both result in pwsh.exe typically under C:\Program Files\PowerShell\7\pwsh.exe.

# Option A: winget (requires winget availability)
winget install --id Microsoft.PowerShell -e

# Option B: Chocolatey (if used internally)
choco install powershell -y

Verification:

# Confirm installation
"powershell.exe" -NoProfile -Command "$PSVersionTable.PSVersion.ToString()"
"pwsh.exe" -NoProfile -Command "$PSVersionTable.PSVersion.ToString()"

Expected result: Both hosts execute and report their versions.

2) Pilot scope first

Start with a small, measurable pilot that is easy to inspect locally before deployment. Good candidates:

A frequently run utility script that reads input and produces text or JSON.
One scheduled task with a well-defined, observable output (file drop, log entry, or event).
A module that has unit-like tests or deterministic behavior.

Constructed example pilot:

Scope: One data export script that writes C:\Automation\out\daily.json.
Observable: File exists, JSON validates, and row count matches yesterday +/- 2% (hypothetical threshold).
Success metric: 7 consecutive successful runs under PowerShell 7.

Pilot candidate examples:

Utility script: One export script → valid JSON file with stable row count.
Scheduled task: Single task with file output → dated file appears with expected size.
Module: One internal module cmdlet → deterministic function returns same output.

3) Profiles and settings

Keep profiles separate until validated. Then copy intentionally.

# Identify 5.1 and 7 profile paths (constructed example)
$ps51 = Join-Path $HOME 'Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1'
$ps7 = Join-Path $HOME 'Documents\PowerShell\Microsoft.PowerShell_profile.ps1'

# Backup and selectively copy lines you trust
if (Test-Path $ps51) { Copy-Item $ps51 "$ps51.bak" -Force }
New-Item -ItemType Directory -Force -Path (Split-Path $ps7) | Out-Null
if (-not (Test-Path $ps7)) { New-Item -ItemType File -Path $ps7 | Out-Null }

# Example: append safe aliases/functions only after testing
Add-Content $ps7 '# Aliases migrated after validation'

4) Module compatibility

Many modules work as-is on PowerShell 7. Windows-only modules may need the Windows PowerShell compatibility shim:

# Attempt a normal import first
Import-Module SomeWindowsOnlyModule -ErrorAction Stop

# If failing in 7, load via Windows PowerShell compatibility
Import-Module SomeWindowsOnlyModule -UseWindowsPowerShell -Verbose

Expected result: The module loads successfully or you have a clear error to investigate. Use -Verbose to see loading details.

5) Switch scheduled tasks gradually

Only switch a task from powershell.exe to pwsh.exe after the pilot passes.

# Preview tasks to change
Get-ScheduledTask |
Where-Object { $_.Actions.Execute -match 'powershell.exe' } |
Select-Object TaskName, @{n='Args';e={$_.Actions.Arguments}}

# Constructed example of updating one task action path and args
$taskName = 'DailyExport'  # constructed example
$task = Get-ScheduledTask -TaskName $taskName
$action = New-ScheduledTaskAction -Execute 'C:\Program Files\PowerShell\7\pwsh.exe' -Argument $task.Actions.Arguments
Set-ScheduledTask -TaskName $taskName -Action $action

Verification:

# Manually trigger after hours
Start-ScheduledTask -TaskName 'DailyExport'
Start-Sleep -Seconds 10
Get-ScheduledTaskInfo -TaskName 'DailyExport'

Expected result: The task runs, and its observable output appears as expected.

Verification and Diagnostics

Your goal is to make success obvious and failure noisy.

1) Host and path checks

# Confirm pwsh path on Windows
$pwshPath = (Get-Command pwsh).Source
$pwshPath
Test-Path $pwshPath

# Confirm Machine PATH update contains PowerShell 7
[Environment]::GetEnvironmentVariable('Path','Machine') -split ';' | Where-Object { $_ -match 'PowerShell\\7' }

Expected result: pwsh resolves correctly and is on PATH.

2) Execution policy in PowerShell 7

Policies can differ per host. Verify in both 5.1 and 7.

# In pwsh
Get-ExecutionPolicy -List

# If needed, set for current user in 7
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force

Expected result: Policy is compatible with your scripts and security requirements.

3) Output parity test between 5.1 and 7

Use a deterministic script and compare outputs.

# Constructed example
$script = 'C:\Automation\Export-Data.ps1'
"powershell.exe" -NoProfile -File $script -OutFile C:\Temp\out-51.json
"pwsh.exe" -NoProfile -File $script -OutFile C:\Temp\out-7.json

# Compare by size and JSON keys (simple heuristic)
$size51 = (Get-Item C:\Temp\out-51.json).Length
$size7 = (Get-Item C:\Temp\out-7.json).Length
[math]::Round((($size7 - $size51) / [double]$size51) * 100, 2)

# Spot-check JSON shape if applicable
$one51 = Get-Content C:\Temp\out-51.json -Raw | ConvertFrom-Json | Select-Object -First 1
$one7 = Get-Content C:\Temp\out-7.json -Raw | ConvertFrom-Json | Select-Object -First 1
$one51.PSObject.Properties.Name | Sort-Object
$one7.PSObject.Properties.Name | Sort-Object

Expected result: Outputs are identical or within acceptable tolerance for your use case.

4) Logging and diagnostics

# Create an execution transcript for a run
$logDir = 'C:\Logs'
New-Item -ItemType Directory -Path $logDir -Force | Out-Null
$ts = Join-Path $logDir ("pwsh-run-" + (Get-Date -Format yyyyMMdd_HHmmss) + \).log\)
Start-Transcript -Path $ts

# Your script
& pwsh -NoProfile -File 'C:\Automation\Export-Data.ps1' -Verbose

Stop-Transcript

Expected result: A clear log you can attach to incident records or change reviews.

5) Module load tests

# Programmatically test a list of critical modules in pwsh
$modules = 'Az.Accounts','SqlServer','ActiveDirectory'  # constructed examples
foreach ($m in $modules) {
    try {
        Import-Module $m -ErrorAction Stop -Verbose:($VerbosePreference -eq 'Continue')
        Write-Host "OK: $m"
    } catch {
        Write-Warning "FAIL: $m -> $($_.Exception.Message)"
    }
}

Expected result: You have a simple pass/fail report for critical modules.

Failure Modes and Recovery

The following problems are common and easy to prepare for.

Module incompatibility: Import-Module fails in pwsh → use -UseWindowsPowerShell or keep 5.1 host for that script.
PATH confusion: pwsh not found or wrong version → use full path C:\Program Files\PowerShell\7\pwsh.exe and verify PATH.
Execution policy blocks: Script cannot run in pwsh → align policy using Set-ExecutionPolicy -Scope CurrentUser.
Profile errors: pwsh starts with red errors → comment out non-portable lines and migrate selectively.
Scheduled task not starting: Action still points to powershell.exe → update action to pwsh.exe only after validation.

Rollback playbook

Aim to reverse changes in minutes, not hours.

Keep Windows PowerShell 5.1 available.
Restore scheduled tasks to powershell.exe if a cutover fails:

$taskName = 'DailyExport'  # constructed example
$task = Get-ScheduledTask -TaskName $taskName
$action = New-ScheduledTaskAction -Execute 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe' -Argument $task.Actions.Arguments
Set-ScheduledTask -TaskName $taskName -Action $action

Restore profiles from backup:

Copy-Item "$HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1.bak" `"
$HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1" -Force

If needed, remove PowerShell 7 while preserving 5.1:

# Uninstall via winget (constructed example; confirm package id first)
winget uninstall --id Microsoft.PowerShell -e

Validate recovery:

"powershell.exe" -NoProfile -Command "$PSVersionTable.PSVersion.ToString()"
Get-ScheduledTask | Where-Object { $_.Actions.Execute -match 'powershell.exe' } | Select-Object TaskName
Test-Path 'C:\Program Files\PowerShell\7\pwsh.exe'  # should be False if uninstalled

Expected result: Core jobs run under 5.1 again, and the environment is stable.

Operations Checklist

Use this concise checklist for each environment.

Planning

Define business reason and success criteria for the upgrade.
Choose a narrow, measurable pilot that you can verify locally.

Inventory

Record engine versions, OS, architecture.
Export module list and critical versions.
List scripts, scheduled tasks, and services calling powershell.exe.
Capture execution policies and profile paths.

Pilot

Install PowerShell 7 side-by-side.
Run the pilot script in both hosts; compare outputs.
Test module imports; add -UseWindowsPowerShell where needed.
Configure execution policy for CurrentUser if required.
Instrument with -Verbose, transcripts, and clear logs.

Cutover (pilot only)

Update one scheduled task to use pwsh.exe.
Trigger manually; verify observable outputs.
Monitor for 7 consecutive successful runs (constructed target).

Wider rollout

Batch more scripts/tasks in small groups.
Keep rollback steps ready for each batch.
Update documentation: version matrix, known exceptions, and owners.

Rollback (if needed)

Revert tasks to powershell.exe.
Restore profiles and configuration backups.
Optionally uninstall PowerShell 7.
Confirm stability and record lessons learned.

Conclusion

A careful, side-by-side PowerShell upgrade is straightforward when you start small, measure clearly, and maintain a fast rollback. Begin with a pilot that is easy to inspect locally, prove output parity, and then expand in controlled batches. Keep your inventory, verification steps, and rollback playbook close at hand, and you will reduce risk while gaining the performance and maintainability benefits of PowerShell 7.