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, 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, automatically removing the oldest version each time a new one is created beyond the limit. 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, 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. See the recommendations table below for guidance on choosing the right 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; it trims the oldest ones as each new edit pushes the total over the limit.
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 SharePoint Intelligent Versioning | 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. |
Rolling out version limits at scale with PowerShell
Visiting every library in every site manually is not practical for larger tenants. PnP PowerShell can apply a consistent major version limit to all document libraries in a site 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 will not have those excess versions deleted until a new edit pushes the count over the limit and triggers the trim. For immediate cleanup across a large site, the ShareMaster version history trim guide explains how to remove existing excess versions in bulk.
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 Space Master shows a per-library storage breakdown, including the proportion of storage consumed by version history, before any cleanup is run. The Version Trimmer then applies a cut-off rule in bulk, keeping only the most recent N versions per file across an entire library or site and deleting the rest immediately. This is faster and safer than PowerShell-based deletion, which requires writing and testing custom version-deletion logic for each tenancy.
Try ShareMaster free for 14 days
Frequently Asked Questions
What is the default major version limit in SharePoint Online?
Document libraries default to 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. The next time a new version is created that pushes the count past the limit, SharePoint trims the oldest version to bring the total back to the cap. To reclaim storage from existing over-limit histories right now, use a manual bulk delete or ShareMaster's Version Trimmer.
Can I set version limits across all libraries in a site at once?
Not through the SharePoint UI. Each library requires individual configuration. PnP PowerShell's Set-PnPList cmdlet can loop through all libraries in a site and apply a consistent limit in one script run. ShareMaster's Version Trimmer goes further: it applies the limit and removes excess versions across an entire site in a single operation.
Does Microsoft Intelligent Versioning replace the need for manual version limits?
Intelligent Versioning (generally available from 2024) applies an automatic trim algorithm that removes older versions based on a recency and value scoring model, rather than a fixed count. It reduces version history storage without requiring a manual limit. However, it is a tenant-level setting that applies a Microsoft-determined algorithm rather than a specific admin-defined rule. Explicit per-library limits give admins predictable, auditable control over retention, which is often required for governance or compliance reasons.