How to check library version limits in SharePoint Online

Before you start

Use an account with the SharePoint Administrator role. The PowerShell example also signs in to Microsoft Graph with Sites.Read.All to list the site's libraries; that permission acts as you, so your account must be able to open the site, and your organisation may require administrator consent. In PowerShell 7 the SharePoint Online Management Shell must be loaded through Windows PowerShell, which the last line of the install block does.

The limits are read live. A library's limits can be automatic, a number of major versions, or a number with an expiry in days. The examples read and export and change nothing; they never call Set-SPOListVersionPolicy.

Option 1

Check library version limits with PowerShell

Install the modules once, then connect to both services, list the site's document libraries and read each one's policy. Replace contoso and the site address with your own.

# Install once, if the modules are not already installed.
Install-Module Microsoft.Online.SharePoint.PowerShell, Microsoft.Graph.Sites -Scope CurrentUser
# In PowerShell 7 only: load the SharePoint module through Windows PowerShell.
Import-Module Microsoft.Online.SharePoint.PowerShell -UseWindowsPowerShell

$ErrorActionPreference = 'Stop'
$siteUrl = 'https://contoso.sharepoint.com/sites/research'
Connect-SPOService -Url 'https://contoso-admin.sharepoint.com'
Connect-MgGraph -Scopes 'Sites.Read.All' -NoWelcome
try {
    # Graph finds a site by its host name and path, such as contoso.sharepoint.com:/sites/hr
    $address = [uri]$siteUrl
    $siteId = $address.Host
    if ($address.AbsolutePath -ne '/') { $siteId += ':' + $address.AbsolutePath.TrimEnd('/') }
    $site = Get-MgSite -SiteId $siteId
    $libraries = @(Get-MgSiteList -SiteId $site.Id -All |
        Where-Object { $_.List.Template -eq 'documentLibrary' -and -not $_.List.Hidden })
    $report = @(foreach ($library in $libraries) {
        $policy = Get-SPOListVersionPolicy -Site $siteUrl -List $library.DisplayName
        [pscustomobject]@{
            Library = $library.DisplayName
            Policy = $policy | ConvertTo-Json -Compress -Depth 4
        }
    })
    if ($report.Count -eq 0) {
        Write-Output "No document library was found on $siteUrl."
    } else {
        $report | Export-Csv -Path './library-versions.csv' -NoTypeInformation -Encoding utf8
        Write-Output "$($report.Count) libraries written to library-versions.csv."
    }
} finally {
    Disconnect-MgGraph | Out-Null
    Disconnect-SPOService
}

The CSV has 1 row for each visible document library on the site, with its version policy as Get-SPOListVersionPolicy returns it, kept whole in the Policy column. Hidden and system libraries are left out. To check another site, change $siteUrl; to check many, run the block for each address Get-SPOSite -Limit All returns.

Check a single library

Reconnect with Connect-SPOService, then read 1 library's limits by its name. The export above disconnects when it finishes.

# Run while connected to SharePoint. Replace the example site and library.
$site = 'https://contoso.sharepoint.com/sites/research'
Get-SPOListVersionPolicy -Site $site -List 'Documents'

Option 2

Check the default limits in the admin centre

1. Sign in to the SharePoint admin centre as a SharePoint Administrator.
2. Go to Settings and select Version history limits.
3. Read whether new libraries are set Automatically or Manually, and for manual limits the Number of major versions and Delete versions after this period of time.
4. Leave the page without selecting Save.

This shows the default for libraries created from now on, not what existing libraries keep. For each library's own limits, use PowerShell or Altivane.

Common questions

Why does a library keep more versions than the organisation setting?

Microsoft applies the organisation's limits to libraries created after the change, and a change can take up to 24 hours to reach them. Existing libraries keep their own limits until they're changed on the site or the library.

What happens to old versions when a limit is lowered?

Microsoft trims them gradually. Each time a file is updated, up to 20 of its oldest versions over the new count are deleted, and a new expiry applies only to versions created after the change.

Do old versions use the site's storage?

Yes. Microsoft's planning advice warns that high count limits on heavily edited files use a lot of storage. To see what each site uses, see how to export site storage usage in SharePoint Online.