SharePoint · Version history

Version history trimming: what it actually reclaims, and what retention quietly blocks

Published 24 September 2026 · 9 min read · All figures from Microsoft Learn, linked at the end

In most tenants that are over their SharePoint pool, previous versions are the biggest bucket that can be reclaimed without deleting anything a user can see. They are also the bucket where the most admin effort goes to waste, for one reason: changing a version limit does not reclaim a single byte of existing versions. Existing versions only go away through a trim job, the trim job only frees space where no retention setting covers the file, and the freed space takes days to show. This article is the mechanics: the three ways versions disappear, what the automatic algorithm keeps, what a hold does to a trim, and how to know the real number before you queue anything.

Why versions are worth this much

Every library keeps previous versions of every file, 500 major versions by default, and every version is stored as a full copy that counts against the site's storage and therefore against the tenant pool. A 200 MB design file saved forty times is eight gigabytes, thirty-nine of which nobody has opened since the week they were created. Multiply by every actively edited library and versions are routinely a third or more of a busy site, which is why the version storage report from the four-layer audit is the first thing to run on any site that is bigger than its file count suggests.

Three ways a version disappears, and where the bytes go

This is the part that decides whether a "cleanup" changes the storage bar or not.

What happensWhere the version goesStorage effect
A user deletes a version from a file's version historySite recycle bin, then second stage: recoverable for 93 daysNone until the bin purges. Recycle bin contents still count against the pool
Versions exceed the library's limit (count or expiry)Marked for permanent deletion. Bypasses the recycle bin, cannot be restoredFreed, but gradually: count limits are enforced only when the file is next edited, about 20 old versions per edit; expiry limits are stamped on new versions only
A queued trim job (site, library, OneDrive, or tenant)Permanently deleted. Bypasses the recycle bin, cannot be restored unless you have Microsoft 365 Backup or similarFreed. This is the only path that reclaims existing versions on demand

Two consequences follow. First, a policy change alone is a promise about the future: when you lower a library from 500 to 300 versions, a file that already has 500 keeps them until someone edits it, and then loses about twenty per save. A file nobody touches keeps its 500 for ever. When you change the organisation default, it applies to new libraries only; existing libraries and existing versions are untouched until you push the setting down and queue a trim. Second, the recycle bin path is the one users take, and it is the one that shows nothing on the storage bar for three months.

Trimmed means gone. Learn's own caution: versions deleted by a trim job bypass the recycle bin and cannot be recovered. A count or expiry value that is too aggressive is silent data loss for anyone who needed to undo a change. The UI refuses values under 100 versions or under 30 days for exactly that reason; the APIs allow lower, and Microsoft recommends against it.

Automatic versus manual: what each one keeps

There are three modes, and the choice is really about restore points, not storage.

ModeWhat is keptStorage behaviour
Automatic (Microsoft's recommendation)Everything created in the last 30 days (up to 500); hourly versions between 30 and 60 days; daily between 60 and 180; weekly beyond 180 days, until the 500 capThins out intermediate versions as they age. Microsoft's own examples put the reduction at roughly 94–96% of version storage over six months compared with count limits alone, while a file with no recent edits still keeps restore points
Manual: count + expiryUp to N major versions, none older than X daysLowest quota impact. The trade-off Learn spells out: a file not edited in six months under a six-month expiry ends up with no previous versions at all
Manual: count onlyUp to N major versions regardless of agePredictable, and the most expensive if N is high or files are edited heavily

The same three modes exist for trimming existing versions: an automatic trim applies the algorithm above to what is already there, an expiry trim deletes versions older than a date, and a count trim deletes the oldest versions above N. Two documented limits of the expiry trim catch people: it cannot delete anything from the last 30 days, and it always deletes every version created before 1 January 2023, whatever date you give it. If a library has versions from 2022 that someone wants kept, an expiry trim is the wrong tool.

What retention does to a trim

This is the block that makes the what-if number and the reclaimed number differ. The rule is simple: the retention setting always wins, whether it is a hold or a deletion policy. The details are what matter for the storage bar.

The file is under…What the library limit doesWhat a trim job does
A retention policy or an eDiscovery holdIgnored. Versions accumulate past the limit until the retention period ends or the hold is releasedDoes not delete. It stamps an expiration date on the version; when that date arrives, the date is extended if the hold still applies, and the version is deleted only once the hold is lifted
A retention label that does not mark it as a recordHonoured. Old versions are trimmed to make room for new ones; users still cannot delete versions themselvesDeletes as normal, unless a policy or hold also covers the file
A label that marks it as a recordVersion deletion is blockedBlocked
A read-only or locked site (including sites locked for retention)—Suspended until the site is unlocked

Three things people miss here. The Preservation Hold library is never touched by version trimming; for files under a retention policy, all versions of a retained file have been kept as a single file there since July 2022, and that copy is governed by the policy, not by the library's version settings. A tenant-wide retention policy (the common "retain everything seven years" one applied to all SharePoint sites) therefore turns every site into the first row of the table: a trim on those sites reclaims nothing today; it schedules deletions for whenever the policy stops covering the version. And a trim on a held site is not wasted, because the expiry stamps are how those versions eventually leave, but it should not be sold internally as storage coming back this quarter.

The practical test. Before trusting any projected saving, check the site against Purview: is it in scope of a retention policy, is it on an eDiscovery hold, and does the library carry record labels? If the answer to any of those is yes, the what-if figure is the ceiling on what the policy will eventually release, not what the pool gets back after the job.

The safe order: report, what-if, trim, wait

All of this is SharePoint Online Management Shell as a SharePoint administrator. The first two steps change nothing.

1. Version storage report. Writes a CSV of every version on the site with its size to a library you name. Takes minutes to days depending on the site.

$site = "https://TENANT.sharepoint.com/sites/design"
$rpt  = "$site/Shared Documents/VersionReport.csv"
New-SPOSiteFileVersionExpirationReportJob -Identity $site -ReportUrl $rpt
Get-SPOSiteFileVersionExpirationReportJobProgress -Identity $site -ReportUrl $rpt

2. What-if. Learn's tutorial runs the automatic, expiry and count modes against that CSV and shows the projected version storage under each. This is where you choose the mode, and it is the number to put in the deck, with the retention caveat above.

3. Trim. One command per scope, one mode:

# Automatic algorithm on the whole site
New-SPOSiteFileVersionBatchDeleteJob -Identity $site -Automatic

# Or: expire versions older than 365 days on one library
New-SPOListFileVersionBatchDeleteJob -Site $site -List "Documents" -DeleteBeforeDays 365

# Or: keep 100 majors, and minors for the newest 10 majors
New-SPOSiteFileVersionBatchDeleteJob -Identity $site -MajorVersionLimit 100 -MajorWithMinorVersionsLimit 10

# Push the site's version policy to every library, then trim to it
New-SPOSiteManageVersionPolicyJob -Identity $site -SyncListPolicy -TrimUseListPolicy

Get-SPOSiteFileVersionBatchDeleteJobProgress -Identity $site
Remove-SPOSiteFileVersionBatchDeleteJob -Identity $site   # stop an in-progress job

4. Wait, then measure. Trim jobs are background jobs subject to off-peak processing; the purge of expired versions "may take a couple of days" after expiry; and the Active sites storage figure itself lags 24 to 48 hours. Measure the site a week after the job reports complete, not the next morning, or you will conclude the trim did nothing.

Tenant-wide trimming exists as a private preview: New-SPOTenantApplyFileVersionPolicyJob -TrimVersions -SetVersionPolicy applies the tenant policy to every site in one job, with its own what-if (-CollectVersionData then Get-SPOTenantApplyFileVersionPolicyJobImpact). It needs a SharePoint Advanced Management or Copilot licence, allows one job per tenant at a time, and skips read-only, locked, archived and broken-inheritance sites, so the sites most likely to be under retention are also the ones it skips.

What a trim is worth

Versions cost the same as everything else in the pool: nothing while you are under it, and the pay-as-you-go SharePoint storage meter at $0.20 per GB per month, or an Extra File Storage add-on, once you are over. A trim is therefore worth money in exactly two cases: it moves the tenant back under the pool, or it defers an add-on purchase at renewal. Reclaiming 700 GB on a tenant that is 3 TB over changes the bill by a rounding error; reclaiming the same 700 GB on a tenant that is 400 GB over removes the line. Run the numbers against your pool position first, which is Layer 0 of the four-layer audit.

Two more consequences that are easy to forget. Versions in the recycle bin and in the Preservation Hold library are not reclaimed by any of the above, and if you are about to archive a cold site with Microsoft 365 Archive, trim it first: archived storage is billed on its full size, versions included, and trim jobs skip archived sites.

Checklist

  1. Run the version storage report on the ten largest active sites. Sum by library.
  2. For each candidate site, check Purview: retention policy scope, eDiscovery holds, record labels. Mark the held sites as "deferred", not "savings".
  3. What-if the automatic mode on the rest. Use its number.
  4. Set the organisation default (automatic, or count + expiry) so new libraries stop accumulating, and push it to existing libraries with -SyncListPolicy.
  5. Queue the trim on unheld sites. Record the job time.
  6. Measure a week later against the Active sites figure, and log the delta against the pool, not the site.

Free: pool position, top sites and departed-user OneDrives in one run

StorageScout Lite is a read-only PowerShell audit that gives you the pool position and the top-site list this article starts from, plus every departed-user OneDrive with its size. No server, nothing leaves your tenant. The paid tiers add the per-site version, recycle-bin and Preservation Hold breakdown, dollar-quantified against the meters above, so the "deferred" and "savings" columns are filled in for you.

Download StorageScout Lite — free See what Solo adds

Disclosure: StorageScout is our product. Prices are Microsoft's public US list prices as documented on Microsoft Learn at the time of writing; your agreement, region and currency may differ. The examples are hypothetical. StorageScout is independent and not affiliated with or endorsed by Microsoft.

Sources