Optimize SharePoint Storage: How Version History Limits Can Help

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:

  1. 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.
  2. 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.
  3. 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.

Microsoft has provided this helpful diagram that shows how many file versions remain over time depending of which of the three setting are selected
Image by Microsoft

Step 3: Configure the organization-level version history limits settings

From the SharePoint Admin center, navigate to Settings > Version history limits.

Screenshot of the SharePoint admin center setting menu

The Version History Limits settings has three options:

  1. Automatically – the number of major versions decreases as the content ages.
  2. Manually and not time-limited – Define the number of major versions to keep. The default behavior is to keep 500 versions without expiration
  3. 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.

Screenshot of setting the version history limits on a document library

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.

Screenshot of Accessing the document library 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.

Screenshot of Document library version settings for a new document library that inherits the tenant level version history settings

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.

Screenshot of Document library version settings for an existing document library showing that it has not inherited the tenant level version history settings

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 settingsNew Sites & OneDrive accountsExisting Sites & OneDrive accountsNew document libraryExisting document libraryNew file versionsExisting file versions
Organization Inherit settingsNo changes madeInherit settingsNo changes made
SharePoint siteInherit settings if selected in PowerShell commandInherit settings if selected in PowerShell commandInherit settingsNot trimmed to meet new rules.
Must run a separate trim job
OneDrive accountInherit settingsNot trimmed to meet new rules.
Must run a separate trim job
Document Library with an updated countInherit settingsGradually trimmed. 20 versions trimmed with each file update
Document Library with an expirationInherit settingsFiles 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.

Screenshot of Version History settings

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.

Screenshot of File version settings showing 100 versions with no time limit

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.

Screenshot of the version history of a file when versions when the setting are set to no time limit, so the files so Never expires

Experience when file versions are set to expire

The Document Library version history settings are set to:

  • Manual
  • Have an expiration date in days
Screenshot of File version settings showing 500 versions and versions expire after 365 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.

Screenshot of the version history of a file when versions expires. The current version is always set to never expire. All other versions have an expiry date.

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

Screenshot of File version settings showing the setting set to automatic

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.

Screenshot of the version history of a file when file versions are set to automatic. The current version and some other versions are set to never expire. All other versions have an expiry date.

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:

  1. Run a version history report on selected SharePoint sites to understand which sites to target.
  2. Conduct a “what-if analysis” on the report data to determine the new site version history settings.
  3. 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:

  1. Automatic trimming algorithm
  2. Deleting versions older than a specific date e.g. after 365 days
  3. 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:

  1. Use an automatic trimming algorithm
  2. Delete versions older than a specific date. For example, delete all versions after 01/01/2024
  3. 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

Keep Reading

Previous