Invoke-VersionTrim

This PnP PowerShell script trims version history across all files in a SharePoint document library, permanently deleting versions older than a defined threshold. Version deletion is irreversible — always run Get-VersionReport first to understand the scope before executing this script.

Purpose

SharePoint document libraries accumulate versions silently during normal use. AutoSave and collaborative editing can generate dozens of versions per document per day. This script gives you direct control over version history by:

• Iterating over every file in the target library
• Skipping folders so only files are processed
• Retaining the most recent N versions per file (configurable)
• Permanently deleting all versions beyond that threshold
• Logging each file it acts on so you have an audit trail

Prerequisites

• PnP PowerShell module installed
• Site collection administrator permissions
• A registered Entra ID app with appropriate SharePoint permissions and a Client ID
• Run Get-VersionReport first to review version counts before deleting

Parameters to update

• Url — your site URL in the format https://tenantName.sharepoint.com/sites/siteName
• ClientId — your registered Entra ID app Client ID
• -List — the internal name of the library to trim (e.g. Documents, SitePages)
• 50 — the number of recent versions to retain per file; adjust to fit your organisation's policy

Connect-PnPOnline -Url "https://tenantName.sharepoint.com/sites/siteName" -Interactive -ClientId ""

$items = Get-PnPListItem -List "SitePages" -Fields "FileLeafRef", "FileRef", "FSObjType"

foreach ($item in $items) {
    # Skip folders
    if ($item["FSObjType"] -eq 1) { continue }

    $versions = Get-PnPFileVersion -Url $item["FileRef"]
    if ($versions.Count -gt 50) {
        Write-Host "$($item["FileLeafRef"]) has $($versions.Count) versions"
        $toDelete = $versions | Sort-Object Created -Descending | Select-Object -Skip 50
        foreach ($version in $toDelete) {
            Remove-PnPFileVersion -Url $item["FileRef"] -Identity $version.Id -Force
        }
    }
}