Daily SharePoint News
Aboutmerill.net
Content, versions and storage
General

Trim Versions

11 November 2026Doc update+42 / −39 lines

In brief

The article was revised with clearer wording, identifies SharePoint Administrators as able to queue trim jobs, and simplifies the What-if and manual expiration guidance. It now highlights the 30-day minimum and removes the previous text about versions created before January 1, 2023.

What SharePoint admins need to know

Review the guidance before trimming. Deleted versions bypass the recycle bin and cannot be recovered unless previously backed up; use What-if analysis to assess impact.

Summaries are generated from the documentation change itself.

Documentation change

View full page diffView on Microsoft Learn

The comparison below shows only the changed extract. Use the full-page view for complete context.

ms.author: ruihu author: maggierui manager: jtremper ms.date: 2026-07-27T00:10-30T00:00:00.0000000Z audience: Admin f1.keywords:

  • NOCSH

Caution

Versions deleted by using trimming jobs are permanently deleted. This deletion workflow bypasses the normal recycle bin retentionretention, and deleted versions cannotcan't be recovered,recovered unless the data was previously backed up by using Microsoft 365 Backup or a similar backup solution. To prevent unwanted data loss, we highly recommend torun a What-if analysis before trimming activity.

As a Global Administrator or SharePoint Administrator in Microsoft 365, you can queue a job to trim existing versions to reduce the version storage footprint across your organization. Trimming can be applied at different scopes:

  • Site, library, or OneDrive level — Target specific sites, document libraries, or OneDrive user accounts.
  • Tenant level — Apply your tenant-level version policy across all sites in one operation.
    Phase Recommended Actions
    Prepare Evaluate your recovery objectives and target version storage use: Determine the right trim mode and trim scope that you need to meet your organization's recovery objectives. Review Impact: Before committing to trim existing versions, you have the option to review the impact of the purge action by running a 'What-if' analysis operation of the selected trim mode on the specified scope.
    Queue Job Once you're ready to commit to a trim job, you can queue a version trimming job to asynchronously delete versions matchingthat match the criteria specified in the trim mode within a site, library, or OneDrive user account.
    Track Progress You can trackTrack the progress of all queued jobs to review the progress made in trimming versions.

Note

Trim jobs are background jobs that are influenced by factors such as the volume of file versions to be evaluated,evaluate, service health, and other jobs being processed on the farm.farm influence. They are're also subject to off-peak hour processing logic. TheYou can always track the progress of a trim job can always be tracked.job.

Review impact by running 'What-if' analysis

Before committing toyou trim existing versions, you can review the impact of the purge action by running a 'What-if' analysis operation. Running a 'What-if' operation follows these steps:

  • Generate a version storage usage report for a site or library: ThisUse this report supports multiple uses, includingfor version storage analytics and gaining key insights onto understand the impact of applying different trimming settings.
  • Run 'What-If'if analysis by setting: Set different trimming modes to preview the changes and analyze the storage savings impact of applying one of the trimming modes to the version storage report CSV file.

Important

Automatic trim mode (recommended)

The automatic trim mode applies the Automatic algorithm to delete existing versions. Depending on the version age, the job will permanently deletedeletes versions or setsets expiration time according to the automatic version storage algorithm.

To learn more about automatic trim mode, see Understand version storage under Automatic limits.

Manual expiration trim mode

The manual expiration trim mode evaluates the age of versions and deletes versions matchingthat match the expiration criteria.

Example: In the following example, a trim job is queued to trim versions older than 60 days. On August 31, the job is picked up and it starts permanently deleting versions older than 60 days as of August 31.

Known limitations of manual expiration trim mode:

    • The manual expiration trim mode doesn't delete versions created in the last 30 days. This limitation means your input can't be less than 30 days.
    • The manual expiration trim mode always deletes all versions that were created before January 1, 2023. If you want to trim versions, you can't keep any older versions created before January 1, 2023. This limitation means the value you use for the DeleteBeforeDays parameter should result in a date after January 1, 2023.

Manual count limit trim mode

The manual count limit trim mode deletes the oldest versions exceedingthat exceed the specified count limit.

Example: In the following example, a trim job is queued to delete versions that exceed 50 major version counts. On August 31, the job starts permanently deleting older versions that exceed the 50 major version count limit as of August 31.

Queue trim job and track progress

The version trimming workflow uses a job to asynchronously delete versions matchingthat match the criteria specifiedyou specify in the trim mode.

To queue the trim job, you need to determine the scope for version deletion and choose the trim mode to set the criteria for deleting existing version deletion.versions. You can delete old file versions based on version age, count limits, or an automatic algorithm for all document libraries in a site or for a specific document library.

OnceWhen you're ready to commit to the trim, you can queue the job to asynchronously delete versions matchingthat match the trim mode criteria. You'll be able to can monitor the progress of committed trim jobs to keep track of the deletion progress.

Note

To learn more about how version trimming works on versions that are subject to a retention policy or an eDiscovery hold, see FAQs.

Trim existing versions by using PowerShell

Follow these steps to trim existing versions by using PowerShell.

  1. Download the latest SharePoint Online Management Shell.

    Note

    If you installed a previous version of the SharePoint Online Management Shell, go to Add or Remove programs and uninstall SharePoint Online Management Shell.

  2. Connect to SharePoint as a SharePoint Administrator in Microsoft 365. To learn how, see Getting started with SharePoint Online Management Shell.

  3. Run one of the following commands to trim the existing versions:

    | Action | PowerShell Command |

Note

Tenant-level version trimming is currently in privatepublic preview. This feature maymight change based on feedback, including the addition of throttling limits on the number of jobs you can run within a specific time period.

Tenant admins can use tenant-level operations to start a file version trimming job across all sites in a tenant, update document library version policies to match the tenant policy, and estimate the storage impact of trimming by using what-if analysis.

  • Trim existing versions based on that policy.
  • Track progress and delete the tenant-level job.

To help you understand trimming impact, use additional cmdlets let youto run fast, synchronous what-if analysis queries after an initial asynchronous data collection job.

Caution

Versions deletedyou delete by using trimming jobs are permanently deleted. This deletion workflow bypasses the normal recycle bin retentionretention, and deleted versions cannotcan't be recovered,recovered unless the data was previously backed up by using Microsoft 365 Backup or a similar backup solution.

Prerequisites and limitations

  • Requires a SharePoint Advanced Management license or Copilot license.

  • Only one job is allowed per tenant at a time.

  • The following site types are excluded from processing:

    • Read-only sites
    • Locked sites
    • Archived sites
    • Sites with version policy broken inheritance

  • If the tenant-level version policy changes while the job is in progress, the job applies the updated policy to remaining unprocessed sites. Sites already processed are notaren't re-evaluated.

  • The tenant-level trim uses the version policy configured at the tenant level (Automatic, Manual Expiration, or Manual Count Limit). To understand these trim modes, see Version trim modes above.

  • The what-if analysis returns impact data for both SharePoint sites and OneDrive accounts.

  • If your tenant is Multi-Geo, run the what-if analysis and version trimming must be run separately for each geo location.

Recommended workflow

1. Prerequisites

  1. Download the latest SharePoint Online Management Shell.

  2. Connect to SharePoint as a SharePoint Administrator in Microsoft 365. To learn how, see Getting started with SharePoint Online Management Shell.

  3. Confirm your tenant-level version policy by running:

    You can run multiple what-if queries with different policy options using `Get-SPOVersionPolicyWithChanges` to create modified policy objects for comparison.

  4. Review the projected impact and choose a desired version policy.

    Note

    The projected impact includes both SharePoint sites and OneDrive accounts.

3. Trim existing versions and update document library policies

Once you've confirmed confirm your tenant version policy and reviewedreview the projected impact:

  1. Run the trim job with desired options:

    Note

    Once the cmdlet executes successfully, all new asynchronous version deletion is stopped.stops. Canceling a trim job does notdoesn't impact versions that were permanently deleted while the job was in progress.

Tenant-level PowerShell cmdlet reference

| Get current tenant version policy | Get-SPOTenantVersionPolicy | Get-SPOTenantVersionPolicy | | Create a modified policy object locally | Get-SPOVersionPolicyWithChanges | Get-SPOVersionPolicyWithChanges |

Learn moreRelated information

For more information, check out the following resources: