In my recent blog post, Hidden Connection Between SharePoint File Versioning and Storage, I delved into the mechanics of file versioning in SharePoint. Each version is a full copy of the file, meaning that large files can rapidly consume storage space. For instance, a 200MB PowerPoint file with 10 versions will use up 2GB of storage. If you have 500 such files, that’s a whopping 1TB of storage consumed. This versioning system can lead to SharePoint becoming cluttered with outdated and often irrelevant file versions. However, it’s not all bad news. Microsoft has recently introduced Version History Limits (Preview), which offers better control over file versions at both the organization and site levels. With these new limits, you can optimize SharePoint storage by deleting excessive versions, thereby freeing up and making better use of your valuable storage space.
Let’s explore how to use Version History Limits to optimize SharePoint storage and enhance your document management efficiency.
How to use Version History Limits to optimize SharePoint storage
SharePoint Version History Limits enable administrators to set version limits at the organization rather than relying on the default 500 file versions that do not expire. The benefits of the new SharePoint file version limits are that you can:
- Choose the maximum number of versions to keep
- Decide if you want file versions to expire after a period of time.
- Use automatic versioning, where the number of versions decreases over time based on activity and the age of the content.
✅This means you can now optimize SharePoint storage with Version History Limits so that you have the option to keep fewer versions, thus freeing up SharePoint storage for active data.
Let’s take a closer look at how SharePoint Version History Limits works.
Step 1: Opt into the SharePoint Version History Limits Preview
You can only opt into the Version History preview using SharePoint Online Management PowerShell (⚠️Important, make sure you update the SharePoint PowerShell module first).
Set-SPOTenant -EnableVersionExpirationSetting $true
After enabling the preview, go to SharePoint Admin Center > SharePoint settings and look for the new menu item called “Version history limits.”
Step 2: Decide on your organization’s SharePoint version history limits settings
Now that you have enabled version history limits, you must decide on one of the three default versioning limits to apply to your organization.
⚠️Please note that these organization controls will only apply to new locations, including new Document Libraries added to an existing site, new SharePoint sites, and new OneDrive accounts. You need to take another step to update your existing Document Libraries and OneDrive accounts. This is discussed in a later section.
Automatic Versioning (Microsoft recommended setting)
The Automatic Version History setting dynamically adjusts the number of versions based on data activity. Active data will have many versions, while inactive data will retain fewer versions.
✅Storage optimization is a key benefit. As content ages and becomes inactive, the system keeps fewer versions, thus freeing up SharePoint storage for active data.
Manually set the maximum number of major versions to keep with no time limit
With this setting, you set the maximum number of major document versions to keep but do not set an expiration. When the number of versions exceeds the set limit, the system automatically deletes the oldest version. For example, if you set the number of major versions to 500, the system removes the first version when it saves the 501st version, ensuring the total number of versions remains at 500. Because you set the expiration to “never expire,” the number of versions stays the same as the content ages. This means that even after 5 years, there will still be up to 500 versions.
⚠️This setting does not reduce storage consumption because the system treats active and inactive content equally. Consider whether you need up to 500 versions of data not accessed for 5 years. This is the current default setting for all Document Libraries and OneDrive accounts.
Manually set the maximum number of major versions to keep and expire versions when they reach a time limit
With this setting, you set the maximum number of major document versions to keep and how long to retain them before deleting. For example, if you set the limits of 365 days then when a version exceeds 365 days it is deleted. Note that the current version is never deleted.
⚠️ Deleting content over time can result in having only the current file version. This impacts data resilience, as it is not longer possible to restore previous file versions should the main version be accidently or maliciously damaged.
Why does Microsoft recommend the Automatic SharePoint version history limits?
Microsoft recommends using the automatic versioning in SharePoint Version History Limits because of the following benefits:
- Storage Optimization: Automatic versioning dynamically adjusts the number of versions based on data activity. Active data will have many versions, while inactive data will retain fewer versions. This helps in freeing up SharePoint storage for active data.
- Efficiency: The number of file versions reduces as content ages and becomes inactive, optimizing SharePoint storage usage and ensuring that only relevant versions are maintained.
- Dynamic Expiration: Different versions will expire at various times based on the file’s activity and age, while some versions will not expire at all. This ensures that the most relevant versions are always available.
✅The automatic setting provides the most effective way to optimize SharePoint Storage with version history limits.
Comparing the three settings
Microsoft has created a helpful diagram illustrating the number of file versions over time.
🟡The yellow line, “Count limits,” shows the tenant default of 500 versions with no expiration. This option causes SharePoint storage bloat because it retains old file versions until the final file deletion.
🔵The blue line, “Manual expiration,” shows that SharePoint eventually deletes all file versions except the current one. This option loses built-in resilience because as the file cannot be restored from older versions.
🟢The green line, “Automated limits,” reduces file versions using an algorithm as content ages and becomes inactive. This method optimizes SharePoint Storage with Version History Limits by reducing the number of versions over time, ensuring you never have just a single version of a file.
Step 3: Configure the organization-level version history limits settings
From the SharePoint Admin center, navigate to Settings > Version history limits.
The Version History Limits settings has three options:
- Automatically – the number of major versions decreases as the content ages.
- Manually and not time-limited – Define the number of major versions to keep. The default behavior is to keep 500 versions without expiration
- Manually with a time limit – Delete major version when they get to a specific age, e.g., after one year or keep it forever
New Document Libraries or OneDrive accounts inherit these organization settings when created.
⚠️Important: The organization settings do not impact your existing document libraries, which will retain their original settings (500 versions, with no time limit). You must update your existing sites, document libraries and OneDrive accounts. The blog discusses this topic later.
⚠️Important: Remember that when data is subject to holds such as retention and record management policies or eDiscovery holds, these holds take priority. The system preserves all document versions for the duration of the retention period or the hold.
How does the organization version history settings impact new and existing Sites, Document Libraries and OneDrive accounts?
Let’s use an example to demonstrate the impact on new and existing Document Libraries or OneDrive accounts. In this example, the organization-wide version history settings are set to Automatic.
We want to assess this change’s impact on new and existing document libraries. To check the version settings of a specific Document Library, go to Library settings, choose More Library settings, and then Versioning settings.
New sites, document libraries and OneDrive accounts inherit the organization version history settings
When I create a new document library, it inherits the organization-wide automatic configuration. The screenshot below shows that the new document library settings have been updated to Automatic.
Existing sites, document libraries and OneDrive accounts do not change
The organization version history settings do not impact existing sites, document libraries and OneDrive accounts. So when you look at an existing document library, it retains the original version settings, 500 versions with no time limit.
The screenshot below shows that the settings have not been automatically changed to Automatic. However, you now have the option to manually adjust the Version history settings for the Document Library if you want.
The effect of updating the version history setting at the organization, site, OneDrive, and document library levels
The version history limits settings configured in the SharePoint admin center are organization-level settings. However, you can break inheritance at the SharePoint site, OneDrive and document library levels. The table below shows the impact of updating the version history settings at the organization, site, OneDrive, and document library levels on both new and existing locations.
Update Version History settings | New Sites & OneDrive accounts | Existing Sites & OneDrive accounts | New document library | Existing document library | New file versions | Existing file versions |
---|---|---|---|---|---|---|
Organization | Inherit settings | No changes made | Inherit settings | No changes made | – | – |
SharePoint site | – | – | Inherit settings if selected in PowerShell command | Inherit settings if selected in PowerShell command | Inherit settings | Not trimmed to meet new rules. Must run a separate trim job |
OneDrive account | – | – | – | – | Inherit settings | Not trimmed to meet new rules. Must run a separate trim job |
Document Library with an updated count | – | – | – | – | Inherit settings | Gradually trimmed. 20 versions trimmed with each file update |
Document Library with an expiration | – | – | – | – | Inherit settings | Files not trimmed to new expiration. Must run a separate trim job |
How can I update the SharePoint version history limits for existing SharePoint Sites and OneDrive Accounts?
As mentioned, the organization settings only apply to new sites, OneDrive accounts, and document libraries. Therefore, you must programmatically update existing SharePoint sites and OneDrive accounts with the updated version history settings. When you update a site, you can configure the changes for new document libraries, existing document libraries, or both.
⚠️Please note that this change does not delete any existing file versions. There is a separate process that must be run to trim existing file versions.
⚠️If you have retention policies that retain content or eDiscovery holds on files, then these retention policies and eDiscovery holds will override any version control settings. The system will retain file versions until it releases the hold or retention.
Microsoft provides a step-by-step tutorial on this: Tutorial: Manage version history limits on a site, library, or OneDrive account (Preview) – SharePoint in Microsoft 365 | Microsoft Learn
Can I update version settings for a specific Document Library?
As a site owner or admin, you may want different version history settings for a specific document library. For example, reduce the number of file versions in a document library that stores large images or videos. Having multiple versions of large files quickly uses up your storage limits.
To update the version settings of a specific Document Library, a site owner can navigate to Library settings, select More Library settings, and then choose Versioning settings. They can then choose from automatic, manual with no limits, or manual with an expiration.
Can I see when file versions expire?
As a site owner or member, you can view file versions and any expiration dates for all files you can access.
Experience when file versions are set to not expire
The version history settings for the Document Library are configured to:
- No time limit set
- Specifies a maximum number of versions to keep.
This is the traditional setting, with 500 versions that do not expire.
In this scenario, the system will start to delete historical file versions when the major version threshold is reached. For example, if the threshold is 100 then when the user creates version 101, the oldest version is automatically and permanently deleted to keep within the limit of 100 versions. ⚠️ These file versions bypass the recycle bin and are permanently deleted, meaning their content cannot be recovered.
Users who view a file’s version history see that all file versions never expire.
Experience when file versions are set to expire
The Document Library version history settings are set to:
- Manual
- Have an expiration date in days
In this scenario, the system automatically deletes historical file versions when they reach their expiry date of 365 days. Additionally, the system will also delete the oldest file version when it exceeds the major threshold. ⚠️These file versions bypass the recycle bin and are permanently deleted, meaning their content cannot be recovered.
When a user views a file’s version history, the system sets the newest file version (the current version) to never expire. All the historic versions will display the expiry date based on the setting applied to the Document Library. This expiry date shows when the file version will be permanently deleted. ⚠️Note: These deleted files bypass the recycle bin and are permanently deleted; the content cannot be recovered.
With this configuration, there will be a time when all historical versions have been deleted, leaving only the current version.
Experience when file versions are set to Automatic
The Document Library version history settings are set to Automatic. In this scenario, an algorithm is used to define how many versions to keep and how long to keep them for
When a user views a file’s version history, the newest file version (the current version) will never expire. However, the older versions will have different settings depending on their age. For example, the original version, version 1.0, and the current version will never expire, while intermediary versions like 3.0, 4.0, and 5.0 will have expiry dates. These expiration settings are dynamic, meaning different versions will expire at various times based on their activity and age, while some versions will not.
Can I delete historic file versions to free up storage?
Configuring the organization, site, or document library version history setting does not delete any existing file versions. If you want to free up storage space immediately, you can trim the historical versions of all existing files on a specific site, OneDrive account, or Document library using PowerShell. ⚠️Please note that trimming the files is a decisive action as it permanently deletes them, bypassing the recycle bin. Therefore, Microsoft recommends analyzing the impact of any changes before running the Trim command.
This will involve a three-step process:
- Run a version history report on selected SharePoint sites to understand which sites to target.
- Conduct a “what-if analysis” on the report data to determine the new site version history settings.
- Trim old file versions based on the rules you have chosen. ⚠️Please remember that it will permanently delete the files, bypassing the recycle bin. This action is irreversible, so proceed with caution.
⚠️ Additionally, if you have retention policies that retain content or eDiscovery holds on files, these retention policies and eDiscovery holds will override any version control settings. The system will retain the file versions until it releases the hold or retention.
⚠️ Configuring the organization, site, or document library version history setting does not delete any existing file versions. If you want to realize immediate storage reductions, you have to Trim the historical versions of all existing files on a specific site, OneDrive account or Document Library
1. Run File Version Storage Usage Report
There is a PowerShell command to generate a Version Usage report for a specific site, OneDrive account, or Document library. The script creates a CSV file containing detailed information about all file versions, including their last updated date and the storage space they occupy for the specified site. Additionally, it will display the current version history setting and indicate whether there is an expiration date for each version. Note this export excludes the current file version which will always be kept.
It’s important to note that this report will run in the background and may take several days to complete, depending on the site size. You can run a PowerShell command to check on the report’s progress. In addition, the storage output report must be stored in the specific site, OneDrive account, or Document library and to view the report you must be a site admin or site owner.
An example Version Usage report is shown below. It shows:
A separate row for every major and minor file version for the Document Library or SharePoint site in scope of the report. In the example below, the first file has five major versions and no minor versions. For each version of the file you see:
- WebId.Compact, DocId.Compact, WebUrl.Compact and FileUrl.Compact = Unique identifiers
- MajorVersion = Major file version number. Note in this report version 1 is the orginal version. Then as the file is updated new versions are created.
- MinorVersion = Minor version number.
- Size = File version size
- ModifiedBy_DisplayName.Compact = Who modified the file
- LastModifiedDate = When it was last modified
- SnapshotDate = When the file version became a historical version.This may show an estimated date
- IsSnapshotDateEstimated = True or False
- CurrentExpirationDate = based on the current schedule the date the file will expire. Note the default setting is never to expire, therefore this column will be blank
- AutomaticPolicyExpirationDate = The date the file version will expire if the File versions Auto setting is applied
- TargetExpirationDate = This is currently blank but will be populated if you rune the “what-if” analysis which is explained in the next section.
Example storage output report.
2. Run the What-If Analysis
Next run one or more of the “what if” analyses to see the effect of trimming files. The benefits of conducting a “what-if” analysis is help you understand the potential consequences of trimming files before making changes. When you trim a file it is permanently deleted.
The “what if” analysis updates the “TargetExpirationDate” column in the storage output report. Microsoft provide three PowerShell scripts to see the effects of the three trimming options:
- Automatic trimming algorithm
- Deleting versions older than a specific date e.g. after 365 days
- Deleting versions that surpass the specified count limit e.g. keep the last 5 versions and delete all version greater than 5.
Microsoft provides a step-by-step tutorial on this: Tutorial: Run ‘What-If’ analysis (Preview) – SharePoint in Microsoft 365 | Microsoft Learn
2. Analyze the report data to define new Version History settings
Once the “what if” analysis step has been completed and the “TargetExpirationDate” column in the storage output report has been populated you can evaluate the effects of trimming (deleting) the file versions, including the number of files that will be removed and the amount of storage freed.
Microsoft has provided an Excel template and a PowerShell script to analyze your data. These can be adapted to meet your needs.
Example of a Versions Expired Before and After Policy graph from the Excel template chart that shows a rolling average of the potential storage savings in GB over time.
Example of a Target expiration schedule report generated from the PowerShell script shows the potential storage savings in GB over the next 12 months. The table shows that 106GB of storage is immediately released. This increases to 113 GB over the next 12 months.
Microsoft provides a step-by-step tutorial on using the Excel template and the PowerShell scripts they provide : Tutorial: Generate and analyze version usage report (Preview) – SharePoint in Microsoft 365 | Microsoft Learn
3. Trim file versions
After completing the what-if analysis, you can utilize PowerShell to trim (delete) files on a specific site, OneDrive account, or document library. You can set up the trim job to:
- Use an automatic trimming algorithm
- Delete versions older than a specific date. For example, delete all versions after 01/01/2024
- Delete versions that exceed a specified count limit. For instance, only retain the newest 50 versions
The PowerShell command runs as a background job to trim (delete) existing file versions asynchronously. ⚠️Keep in mind that trimming file versions will permanently delete the file versions, bypassing the first and second-stage recycle bins and is irreversible. Therefore, proceed with caution.
✅You will observe reductions in the site storage as soon as the process has completed as the files versions are permanently deleted. In the example below, 114870185640 Bytes (106.9812 GB) storage was released. This equated to a 44% saving in storage space.
Microsoft provides a step-by-step tutorial on trimming files: Tutorial: Queue a trim job(Preview) – SharePoint in Microsoft 365 | Microsoft Learn
Conclusion on how to optimize SharePoint storage with the new Version History Limits
The new SharePoint Version History Limits feature provides a robust solution for managing file versions and optimizing storage. By leveraging both manual and automatic versioning options, administrators can ensure efficient use of storage while maintaining data integrity and accessibility. The ability to trim historical versions and run detailed reports further enhances the control and flexibility offered by this feature.
To optimize SharePoint storage with the new Version History Limits, administrators should follow these five steps:
1️⃣ Opt into the Version History Limits preview using SharePoint Online Management PowerShell.
2️⃣ Configure the organization versioning settings in the SharePoint Admin Center. This only applies to new sites, OneDrive accounts and document libraries.
3️⃣ Review and update version history limits your existing sites and OneDrive accounts with the updated settings.
4️⃣ Use the reporting and analysis tools to decide which historical file versions to trim (delete) to free up storage.
5️⃣ Review versioning limits for specific sites, OneDrive Accounts or Document Libraries based on data activity and storage needs
By following these steps, organizations can effectively optimize their SharePoint storage and ensure their data remains organized and accessible.
More information
Want to know about file versioning Hidden Connection Between SharePoint File Versioning + Storage (nikkichapple.com)
Reshmee Ackloo | MVP has also written a great post on using PnP PowerShell to manage file versions Enhanced Version Controls/Intelligent Versioning Trim with PowerShell | Blog about anything related to my learnings (reshmeeauckloo.com)
Official Microsoft documentation.
How versioning works in lists and libraries – Microsoft Support
Versioning in SharePoint | Microsoft Learn
About version history (Preview) – SharePoint in Microsoft 365 | Microsoft Learn