Set version limits for a site (Preview)

By default, organization level settings define the version history limits that are applied to all new document libraries created in a site. However, to meet specific content needs, admins can choose to set distinct version history limits on individual sites. This way, users can break the inheritance from organization limits on an individual site.

Version history limits for an individual site can be managed in the following ways:

Version history limits option	Description
Apply to all new and existing document libraries in a site:	To achieve a consistent version storage policy for a site, you can choose to set a limit to universally apply to all libraries in the site. Using this option, the Version history limit set on site-level is applied to all the new document libraries created in the site and creates a background request to asynchronously process the update on existing document libraries.
Apply to only new document libraries created in a site:	To avoid impacting the settings on existing libraries, you can set a version history limit only for new libraries. Using this option, the Version history limits set on site-level are only applied to new document libraries created in the site. There are no changes made to the limits on the existing document libraries or on libraries that aren't enabled for versioning in the site.
Apply to existing document libraries only in a site:	You can update the limits only on existing document libraries on a site without setting a site level version history setting for new document libraries. Using this option creates a background request to asynchronously process the update on existing document libraries while allowing the new document libraries created in the site to inherit the organization level version history limits.
Clear existing limits set on a site:	You can clear the existing limits on a site to allow new document libraries created in the site to follow organization level limits. Note: Clearing a setting on a Site applies only to new document libraries created on the site and doesn't impact the settings on existing doc libraries or trim existing versions.

Example scenario

Take an example of Contoso, where the default organization Version history limits is configured to Automatic setting and no version limits are initially applied on marketing and legal sites. To meet business needs, the admin can decide to apply 'Manual' setting on legal site, thus breaking inheritance of legal site with the organization default version setting.

The following is the version storage for Contoso:

• Version storage behavior on marketing site: Since no limits are configured for marketing site, all new document libraries created within marketing site collection inherit the organization default setting of automatic.

• Version storage on legal site: Since the legal site has manual settings configured, all new libraries created within the legal site have the manual settings applied.

Important

• Site level Version history limits can be set using PowerShell cmdlets only.
• Setting site level Version history limits doesn't trim existing versions to meet the new limits. Additional steps are needed to trim existing versions on a site or library.
• Requests to update the limits on existing libraries are processed asynchronously by a background job, which can take up to 24 hours to process. You can use PowerShell to check the progress of the job.
• Cancelling an in-progress job stops the update on libraries that were not processed. This action doesn't revert the change for document libraries where the settings update was already processed.

Manage Version history limits for a site using PowerShell

Follow these steps to manage Version history limits for a site by using PowerShell.

1. Download the latest SharePoint Online Management Shell.

   Note

   If you installed a previous version of the SharePoint Online Management Shell, go to Add or remove programs and uninstall SharePoint Online Management Shell.

2. Connect to SharePoint as a SharePoint Administrator in Microsoft 365. To learn how, see Getting started with SharePoint Online Management Shell.

3. Run one of the following commands to manage version history limits on your site:

Action	PowerShell Command
View the version history limits set on a site	Get-SPOSite -Identity $siteUrl | fl Url, EnableAutoExpirationVersionTrim, ExpireVersionsAfterDays, MajorVersionLimit
Set Automatic version history limits on a site.	To set Automatic Version History Limits for all libraries on a site: Set-SPOSite -Identity $siteUrl -EnableAutoExpirationVersionTrim $true Append -ApplyToNewDocumentLibraries parameter to apply only to new document libraries on the site: Set-SPOSite -Identity $siteUrl -EnableAutoExpirationVersionTrim $true -ApplyToNewDocumentLibraries Append -ApplyToExistingDocumentLibraries to apply only to existing document libraries on a site: Set-SPOSite -Identity $siteUrl -EnableAutoExpirationVersionTrim $true -ApplyToExistingDocumentLibraries
Set Manual limits with Count and time parameters on a site.	To set Manual limits with Count and time parameters for all libraries on a site: Set-SPOSite -Identity $siteUrl -EnableAutoExpirationVersionTrim $false -MajorVersionLimit <delete major versions exceeding limit> -MajorwithMinorVersionsLimit <delete minor versions exceeding limit> -ExpireVersionsAfterDays <delete versions exceeding time limit set in days> Append -ApplyToNewDocumentLibraries parameter to apply only to new document libraries on the site: Set-SPOSite -Identity $siteUrl -EnableAutoExpirationVersionTrim $false -MajorVersionLimit <delete major versions exceeding limit> -MajorwithMinorVersionsLimit <delete minor versions exceeding limit> -ExpireVersionsAfterDays <delete versions exceeding time limit set in days> -ApplyToNewDocumentLibraries Append -ApplyToExistingDocumentLibraries to apply only to existing document libraries on a site: Set-SPOSite -Identity $siteUrl -EnableAutoExpirationVersionTrim $false -MajorVersionLimit <delete major versions exceeding limit> -MajorWithMinorVersionsLimit <delete minor versions exceeding limit> -ExpireVersionsAfterDays <delete versions exceeding time limit set in days> -ApplyToExistingDocumentLibraries
Set Manual count with no expiration limit on a site.	To set Manual limits with Count limits set the -ExpireVersionsAfterDays parameter to 0: Set-SPOSite -Identity $siteUrl -EnableAutoExpirationVersionTrim $false -MajorVersionLimit <delete major versions exceeding limit> -MajorWithMinorVersionsLimit <delete minor versions exceeding limit> -ExpireVersionsAfterDays 0 Append -ApplyToNewDocumentLibraries parameter to apply only to new document libraries on the site: Set-SPOSite -Identity $siteUrl -EnableAutoExpirationVersionTrim $false -MajorVersionLimit <delete major versions exceeding limit> -MajorWithMinorVersionsLimit <delete minor versions exceeding limit> -ExpireVersionsAfterDays 0 -ApplyToNewDocumentLibraries Append -ApplyToExistingDocumentLibraries to apply only to existing document libraries on a site: Set-SPOSite -Identity $siteUrl -EnableAutoExpirationVersionTrim $false -MajorVersionLimit <delete major versions exceeding limit> -MajorWithMinorVersionsLimit <delete minor versions exceeding limit> -ExpireVersionsAfterDays 0 -ApplyToExistingDocumentLibraries
Clear the existing version history limits set on a site and inherit Organization version limits on new document libraries created on the site.	Set-SPOSite -Identity $siteUrl -InheritVersionPolicyFromTenant
Cancel in progress update job	Remove-SPOSiteVersionPolicyJob -Identity $siteUrl

Track progress of settings update on existing libraries on a site

Version limits on all new libraries created in the site are immediately applied. Settings on existing libraries are asynchronously updated using a background job. Run the following command to track progress of settings update job.

Get-SPOSiteVersionPolicyJobProgress -Identity $siteUrl

The following table enumerates the various progress status that can be reported when attempting to update the version settings for existing libraries in a site collection:

Status	Description
NoRequestFound	There are no requests on the site to set or update version settings on existing document libraries.
New	The update request is New and is not processed yet.
InProgress	The update request is processed and the settings update request is in progress.
CompleteSuccess	The update request is completed successfully.
CompleteWithFailure	The update request is completed, but setting update on some document libraries has failed.

Learn More:

• Tutorial: Manage Version history limits for a Site, Library, or OneDrive account (Preview)
• Manage Version history limits for a Site using Set-SPOSite
• Track progress of version settings update request for existing document libraries on a site using Get-SPOSiteVersionPolicyJobProgress
• Cancel further processing of version settings update on existing document libraries on the site collection using Remove-SPOSiteVersionPolicyJob