M365Con 2027 – free online conference · 11–22 Jan 2027 · 120 sessions→ m365con.net

Blog · Mirko Peters

Trim SharePoint File Versions with Count Limits: What MajorWithMinorVersionsLimit Really Means

By ·

A trim job with -MajorVersionLimit 100 and -MajorWithMinorVersionsLimit 5 left every minor version in place. Here is how Microsoft describes the two limits, how to run a safe trim, and what stays unclear.

A SharePoint administrator wanted to cut storage by trimming file versions across all sites. They ran a script that read site URLs from a CSV file and called New-SPOSiteFileVersionBatchDeleteJob with -MajorVersionLimit 100 and -MajorWithMinorVersionsLimit 5. The expectation was: keep the last 100 major versions and the last 5 minor versions of each major version. What happened: the major versions were trimmed, but all minor versions of the remaining major versions stayed.

Key points

  • Microsoft Learn describes -MajorWithMinorVersionsLimit as the number of major versions for which all minor versions are kept, not as a cap on the number of minor versions.
  • Both count parameters must be given together, and the Learn tutorial uses -MajorWithMinorVersionsLimit 0 when only major versions should be counted.
  • Trimmed versions are deleted permanently and bypass the recycle bin, so run the what-if analysis first and test on one site.
  • Trim jobs run in the background in batches over the following days, and you can check or cancel them with the progress and Remove cmdlets.
  • Learn does not say how files that only have minor versions (for example 0.192) are handled, so verify that case on a test library.

That question was posted in the Microsoft Community Hub in February 2026. It has no answer. This article does not claim to solve it. It shows what Microsoft Learn says about the two parameters, gives you a careful way to run a trim, and marks the points where documentation and the thread leave a gap. It is not an official Microsoft procedure.

What the two parameters are documented to do

The Learn page "Trim existing versions" lists the count-limit command like this: New-SPOSiteFileVersionBatchDeleteJob -Identity $siteUrl -MajorVersionLimit <n> -MajorWithMinorVersionsLimit <n>. The placeholder text for the second parameter reads "number of major versions for which all minor versions will be kept". The Learn page for library version limits uses almost the same words for Set-SPOListVersionPolicy: the number of major versions for which all minor versions are kept.

The page also says the manual count-limit mode deletes the oldest versions that exceed the specified count limit.

Three more details from the documentation:

  1. In the cmdlet reference, the count-limit syntax requires both -MajorVersionLimit and -MajorWithMinorVersionsLimit. Each page says you need the other one as well.
  2. The Learn tutorial "Queue a trim job" shows -MajorVersionLimit 100 -MajorWithMinorVersionsLimit 0 and labels it as keeping 100 major versions.
  3. The cmdlet reference example uses -MajorVersionLimit 30 -MajorWithMinorVersionsLimit 10.

My reading of this wording is that the second number is not "how many minor versions to keep". It is closer to "for how many major versions do you want to keep every minor version". That reading differs from what the poster expected. It does not fully explain the poster's result either. With a value of 5, you would expect all minor versions to survive only for a limited number of major versions, not for each retained major. Microsoft's pages do not describe the exact pattern, so I cannot say whether the poster saw a delay, a different rule, or a bug. Treat that as open.

Step 1: Decide which trim mode you need

Learn describes three trim modes for existing versions:

  • Age: -DeleteBeforeDays <days> deletes versions older than the number of days you give.
  • Count limit: -MajorVersionLimit and -MajorWithMinorVersionsLimit, as above.
  • Automatic: -Automatic applies the logic of the Automatic version setting to existing versions.

The Learn page on version history limits recommends the Automatic setting for optimized version storage. It says the Automatic setting combines the recovery value of version history with lower storage use, without you having to guess count or age limits. The plan version storage page says Automatic keeps the versions created in the first 30 days (within a 500 count limit), then thins them out to hourly, daily and weekly versions as they age.

For age-based trimming, Learn lists two limits. The job does not delete versions created in the last 30 days, so the input must be at least 30 days. It also always deletes all versions created before January 1, 2023, so the number of days you choose must produce a date after that. Check the current page before you rely on these two points.

Step 2: Generate the report and run the what-if analysis

Learn's trim page says to run a what-if analysis before trimming (the queue-a-job tutorial calls it optional). The tutorials describe a version storage usage report for the site or library, which you download as a CSV file. You then run a script against the report with PowerShell 7. For the count-limit case, the what-if script in the tutorial takes -ImportPath, -ExportPath and -MajorVersionLimit. It does not take a minor-version limit. So the what-if result for count limits only models the major version limit.

The tutorial pages do not name the cmdlet that creates the report, so follow the Learn tutorial for that step. Learn says a trim job can take a few days depending on library size. The what-if tutorial gives no duration.

Step 3: Queue the job on one site first

Connect as a SharePoint Administrator with the current SharePoint Online Management Shell, then queue a job for one test site:

``powershell New-SPOSiteFileVersionBatchDeleteJob -Identity https://contoso.sharepoint.com/sites/site1 -MajorVersionLimit 100 -MajorWithMinorVersionsLimit 0 ``

For one library, use the library variant:

``powershell New-SPOListFileVersionBatchDeleteJob -Site https://contoso.sharepoint.com/sites/site1 -List "Documents" -MajorVersionLimit 100 -MajorWithMinorVersionsLimit 0 ``

Learn warns that versions deleted this way are permanently deleted and do not go to the recycle bin. The cmdlet reference also lists -WhatIf and -Confirm as parameters. The reference describes -WhatIf only as showing what would happen if the cmdlet runs, with no detail on its output for these cmdlets, so do not treat it as a replacement for the report-based what-if analysis.

Step 4: Watch the job

Trim jobs are asynchronous. According to Learn, the deletion happens in batches over the upcoming days, and volume, service health and farm workload affect the timing. Check a site-level job with:

``powershell Get-SPOSiteFileVersionBatchDeleteJobProgress -Identity https://contoso.sharepoint.com/sites/site1 ``

For a library job, the Learn trim page lists Get-SPOListFileVersionBatchDeleteJobProgress -Site <url> -List <name>. To stop a job, use Remove-SPOSiteFileVersionBatchDeleteJob or Remove-SPOListFileVersionBatchDeleteJob. Cancelling stops further deletion but does not restore versions that were already deleted.

Do not expect the storage report to change at once. Learn's page on site storage limits says storage usage does not include changes from the last 24 to 48 hours.

Step 5: Set limits for new versions

A trim job only handles versions that exist today. To control future versions, set the version policy on the site or library:

  • Site: Set-SPOSite -Identity <url> -EnableAutoExpirationVersionTrim $true for Automatic limits. Learn lists -ApplyToNewDocumentLibraries and -ApplyToExistingDocumentLibraries to choose the scope.
  • Library: Set-SPOListVersionPolicy -Site <url> -List <name> -EnableAutoExpirationVersionTrim $true.

Setting a site or library policy does not trim versions that already exist, so queue a trim job for those. Changes to existing libraries are processed in a background job that Learn says can take up to 24 hours. Learn adds that when you lower a count limit on a library, existing versions above the new limit are trimmed gradually, up to 20 per newly created version. The admin center UI does not accept fewer than 100 major versions or an expiration shorter than 30 days. Learn says lower values are possible through public APIs but not recommended, because they can cause inadvertent data loss.

Step 6: Tenant-wide trimming

Learn lists tenant-level cmdlets such as New-SPOTenantApplyFileVersionPolicyJob (with -CollectVersionData, -TrimVersions and -SetVersionPolicy). They are in public preview, need a SharePoint Advanced Management license or a Copilot license, and exclude read-only, locked and archived sites. Only one tenant job can run at a time. If you manage many sites, compare this route with a CSV loop like the one in the thread.

What stays unclear

  • Minor-only files: The poster asked about files that were never published as a major version and have hundreds of minor versions, such as 0.192. Learn does not say how count-limit trimming treats them. Create a test library, add such a file and run a small job before you touch production.
  • Result mismatch: The poster's observation that all minor versions of every retained major version stayed is not explained by the pages I read.
  • Retention: The Learn trim page refers to an FAQ for versions under retention policies or eDiscovery holds. It does not describe the behavior on the page itself.

Related

Sources

Entities in this article

SharePoint Intelligent versioning (SharePoint) SharePoint document libraries SharePoint Advanced Management

Related articles

RSS