SharePoint version history limits: decide the restore window before the trim

Unless someone has changed it, every new SharePoint document library and OneDrive in a tenant keeps up to 500 major versions of each file, with no expiration. The setting lives in the SharePoint admin center under Settings > Version history limits, and it's an obvious lever when storage runs short.

It is also a records setting, whether anyone treats it as one or not. Version history is how a user gets back last week's contract draft, and how a reviewer sees what a procedure said before it was edited. So the decision comes before the PowerShell. The records owner and the site owners agree how far back people need to restore, and only then does the SharePoint administrator change a limit or queue a trim.

Three modes, three different promises

Automatic is Microsoft's recommended setting. It keeps every version, up to the 500 limit, for the first 30 days. From day 30 to day 60 it keeps hourly versions, from day 60 to day 180 daily ones, and after that weekly versions until the 500 limit is reached. History thins out with age, but a file nobody has touched in months still keeps versions at key points in time. In Microsoft's worked example, Automatic used 96 percent less version storage over six months than a count limit alone.

Manual with a count and an expiration keeps everything inside both limits and nothing outside them. Learn spells out the side effect: under a six-month expiration, a file that goes six months without an edit loses all of its versions.

Manual with a count and no expiration is the default. It's predictable, and Learn notes it can use a lot of quota where files are heavily edited.

The admin center won't accept fewer than 100 versions or an expiration shorter than 30 days. The APIs will, and Learn warns that limits that low can lose data.

Changing the default touches less than people expect

An organization-level change applies only to libraries and OneDrive accounts created after it, and can take up to 24 hours to show. Existing libraries keep their limits, and existing versions aren't trimmed. Site owners can also break inheritance for a site or for one library, so the limit governing a given file may not be the tenant one. Learn recommends keeping those exceptions few.

One more control is PowerShell-only. Set-SPOTenant with -FileTypesForVersionExpiration @("audio", "video") gives those file types their own count and expiration. For large media, that beats a blanket cut across everything.

Where retention overrides the limit

This part is for the records owner.

• Items under a retention policy or an eDiscovery hold ignore the library's version limits until the retention period ends or the hold is released. Users can't delete versions in the meantime.

• Items with a retention label, but no retention policy or hold, behave differently. The version limits still apply and older versions are deleted automatically; users just can't delete them by hand. The label keeps the file. It doesn't keep every version.

• Items marked as records can't have versions deleted at all.

• When a trim job reaches a version under retention or hold, it stamps an expiration date instead of deleting it. If the hold still applies when that date arrives, the date is extended.

If a long version history exists for legal or regulatory reasons, check that a retention policy, or a label that marks items as records, covers that library. A standard label alone won't hold the versions.

Trimming is permanent

Versions deleted by a trim job bypass the recycle bin. Learn says they can't be recovered unless the data was backed up beforehand, with Microsoft 365 Backup or a similar product. Versions that expire under a library limit skip the recycle bin the same way.

That fixes the order. Run a version storage report first: New-SPOSiteFileVersionExpirationReportJob writes a CSV of every file version on the site, with its size, who created it, and the date it would expire under the automatic policy. It takes more than 24 hours on a small site and a few days on a large one, and it's saved to a location on that site, so put it in a folder only site owners can open. Run the what-if analysis against that CSV. Only then queue the trim, for example New-SPOSiteFileVersionBatchDeleteJob -Identity $siteUrl -Automatic.

Manual expiration trim mode has two rules that catch people out. It never deletes versions from the last 30 days, and it always deletes every version created before 1 January 2023.

Trimming the whole tenant in one job is in private preview, according to Learn's "Trim existing versions" page, and needs SharePoint Advanced Management or a Copilot license. It skips read-only, locked and archived sites, and any site that has broken version policy inheritance.

Who signs what

The records owner names the libraries where version history is evidence, and confirms what covers them. Site owners say how far back their people actually restore. The SharePoint administrator runs the report and the what-if, and shares the projected deletions before queuing anything.

Purview audit records every change to organization, site and library limits, every queued report or trim job, and every version deleted on expiry or in bulk. So the log will show who changed the restore window either way. Better that it shows a decision than a storage emergency.