Without a version limit, a single frequently-edited document in SharePoint Online accumulates hundreds of copies. The 500-major-version default applies to every new document library unless an admin has changed the organisation default, and most organisations never change it. On an active site with 200 files, that means up to 100,000 version copies sitting in storage, most of which no one will ever open again.
Setting a version limit is the simplest proactive storage governance step available in SharePoint Online. Unlike a manual trim, it works continuously once set, removing the oldest excess versions each time a file gets a new one. This guide covers the library settings UI, the PowerShell equivalent for bulk rollout, and when to use a dedicated tool for sites that are already over-grown.
What is a version limit in SharePoint Online?
SharePoint Online maintains a separate stored copy of a file each time it is edited and saved (or checked in, for libraries with checkout required). Each copy is a version. A version limit is the maximum number of copies SharePoint will keep per file before it begins discarding the oldest.
Two types of versions exist in document libraries:
- Major versions (1.0, 2.0, 3.0) are full published copies. All document libraries can use major versioning.
- Minor versions (0.1, 0.2, 1.1) are draft copies, by default visible only to users with edit access. They require a library configured with major and minor versioning enabled.
The version limit setting controls each independently. Most libraries only need a major version limit; minor version limits matter in publishing workflows with approval steps.
Step-by-step: setting a version limit through the library UI
You need Site Owner or Site Collection Administrator access to change these settings.
- Open the document library in the SharePoint site where you want to apply the limit.
- Open Library settings. Click the gear icon (Settings) in the top-right corner and choose Library settings. In modern SharePoint this opens a settings panel on the right. Click More library settings to reach the full settings page.
- Click Versioning settings under the General Settings section on the Library settings page.
- Enable major versioning if it is not already on. Under Document Version History, confirm that Create a version each time you edit a file in this document library is selected.
- Check "Keep the following number of major versions" and enter your limit. The page will not accept fewer than 100 or more than 50,000. Newer tenants show the same choice as a manual count limit alongside an automatic option and a time limit. See the table below for guidance on choosing the number.
- Set a minor version limit if needed. If the library uses major and minor versions, you will see a separate field for keeping drafts. Setting this to 3-5 is usually sufficient; minor versions accumulate quickly in active approval workflows.
- Click OK to save. The limit takes effect immediately for new edits. SharePoint won't delete versions already beyond the new cap instantly; each new version of a file removes up to 20 of its oldest excess versions, and a file nobody edits keeps the lot.
Choosing the right version limit
| Library type | Recommended major version limit | Rationale |
|---|---|---|
| General document library (contracts, reports, policies) | 25-50 | Provides meaningful history while keeping storage controlled. Most users only look at the last 5-10 versions in practice. |
| Project working library (frequently edited drafts) | 10-25 | High edit frequency means the limit is reached quickly. A lower cap prevents runaway growth. |
| Archival or records library (rarely changed) | 10, or Microsoft's automatic version limits | Files change infrequently; a low cap is sufficient and keeps the library lean. |
| Site Pages library (news and intranet pages) | 20 | Pages accumulate minor edits rapidly. A moderate limit preserves meaningful history without storing dozens of minor text tweaks. |
| Image or media library | 3-5 | Binary files like images, videos, and presentations create large version copies. Even a few versions of a 50 MB file add up quickly. |
Every figure under 100 in that table needs PowerShell, because the library settings page refuses it, and Microsoft warns that limits below 100 versions can let ordinary user activity cause data loss. Treat the low numbers as a deliberate decision for libraries where old versions genuinely have no value, not as a default.
Rolling out version limits at scale with PowerShell
Visiting every library in every site manually is not practical for larger tenants. A SharePoint admin can set one limit for every library in a site with Set-SPOSite -Identity $siteUrl -EnableAutoExpirationVersionTrim $false -MajorVersionLimit 100 -ExpireVersionsAfterDays 0 -ApplyToExistingDocumentLibraries; Microsoft processes the existing libraries in a background job that can take up to 24 hours. PnP PowerShell can do the same library by library in one script run.
Connect-PnPOnline -Url "https://contoso.sharepoint.com/sites/finance" -Interactive
$libraries = Get-PnPList | Where-Object { $_.BaseType -eq "DocumentLibrary" -and $_.Hidden -eq $false }
foreach ($lib in $libraries) {
Set-PnPList -Identity $lib.Id -MajorVersions 25
Write-Host "Updated: $($lib.Title)"
}
To apply this across multiple sites, wrap the above in a loop over an array of site URLs. The -MajorVersions parameter on Set-PnPList sets the maximum major version count; -MinorVersions controls drafts in libraries with minor versioning enabled.
Note that changing the limit via PowerShell, like the UI method, is prospective. Files already holding more versions than the new cap lose them only gradually, up to 20 per new version, and only when they are edited. For immediate cleanup, SharePoint can queue a trim job (New-SPOSiteFileVersionBatchDeleteJob for a site, New-SPOListFileVersionBatchDeleteJob for a library), and the version history trim guide covers the options.
When a version limit alone is not enough
Setting a cap prevents future bloat. It does not address the version history that already exists in libraries that have been running at 500 versions for two or three years. A library with 300 files, each holding 200 existing versions, will not see meaningful storage savings until those old versions are removed.
The same situation arises after acquiring or inheriting a tenant, where the previous administrators never configured versioning governance. In both cases, the starting point is understanding which libraries hold the most version history before touching anything.
ShareMaster's Report Master storage reports show, per library, the total size, the size of the current files and how much a trim would save, before any cleanup is run. Space Master's Version Trimmer then applies the rule in bulk: keep a number of versions per file, cap versions per day, keep a minimum gap in hours between retained versions, or limit the run by file name or date. SharePoint's own trim job handles a straight count, age or automatic cut-off; the Version Trimmer is for when you need those finer rules or a report-only pass first. Either way the deleted versions are gone for good.
To set the limit itself on many libraries without PowerShell, ShareMaster's Settings Updater applies a version count limit to every document library on the sites you select. It needs a SharePoint Administrator account.
Try ShareMaster free for 14 days
Frequently Asked Questions
What is the default major version limit in SharePoint Online?
Unless an admin has changed the organisation default, document libraries are created with a limit of 500 major versions per file. Lists default to 50. Most organisations leave the library default in place, which allows a frequently-edited file to accumulate hundreds of stored copies over its lifetime.
Does changing the version limit delete existing versions immediately?
No. Lowering the limit applies prospectively: each time a file gets a new version, SharePoint removes up to 20 of its oldest versions over the limit, and a file nobody edits keeps all of them. To reclaim that storage now, queue a SharePoint trim job or use ShareMaster's Version Trimmer. Both delete permanently.
Can I set version limits across all libraries in a site at once?
Not from the library settings page, which works one library at a time. A SharePoint admin can apply one limit to every library in a site with Set-SPOSite -MajorVersionLimit and -ApplyToExistingDocumentLibraries; site-level limits are PowerShell only. PnP PowerShell's Set-PnPList can also loop through the libraries. ShareMaster's Settings Updater applies a version count limit to every document library on the sites you select. Version Trimmer is different: it removes existing excess versions and does not change library settings.
Do Microsoft's automatic version limits replace the need for manual version limits?
Automatic version history limits (sometimes called intelligent versioning) thin out versions by age instead of a fixed count. Microsoft documents the pattern: every version from the first 30 days within a 500-version cap, then hourly versions to 60 days, daily versions to 180 days, and weekly versions after that. It can be set for the organisation, a site or a single library, so it is not all-or-nothing. Explicit count limits are still the more predictable choice when a governance or compliance rule names a number of versions to keep.