SharePoint Online version history is one of those features that users love but admins eventually have to govern.
Versioning protects users from accidental edits, bad changes, and overwritten content. It gives people a way to restore previous versions of documents without opening a ticket. That is a good thing.
But at tenant scale, version history can also consume a surprising amount of storage.
Highly active libraries, large Office files, frequent edits, migrations, sync activity, and years of retained versions can quietly add up. Eventually, admins need to answer a few practical questions:
- How many file versions do we have?
- How much storage are those versions consuming?
- Which sites would benefit most from cleanup?
- What policy should we apply going forward?
- How much space could we recover before making changes?
- How do we clean up versions safely across many sites?
That is why I built this tool:
The main script is:
Why version history planning matters
Microsoft’s official guidance for SharePoint version storage makes an important point: version limits should support your organization’s recovery objectives while also controlling storage consumption.
Microsoft documents this here:
Plan version storage for document libraries in SharePoint
The key idea is balance.
If you keep too many versions for too long, storage consumption can grow quickly. If you trim too aggressively, users may lose the ability to recover from accidental or unwanted changes.
A good version history strategy needs to consider both:
| Goal | Why it matters |
|---|---|
| Recovery | Users need enough version history to restore useful prior versions. |
| Storage control | Admins need to prevent version history from consuming excessive quota. |
| Consistency | Tenant defaults and site-level policies should be understandable and repeatable. |
| Exceptions | Some business areas may need different version retention behavior. |
| Safe cleanup | Existing versions should be analyzed before deletion jobs are created. |
The goal is not simply to delete versions. The goal is to understand version storage, set the right policy, and clean up intentionally.
What Microsoft recommends admins consider
Microsoft’s documentation calls out three major planning questions:
- Determine the default version history limits for new document libraries.
- Identify exceptions needed from organization default limits.
- Decide whether existing content should be updated to align with the organization limits.
That third point is where many admins need tooling.
It is one thing to configure a tenant default for new libraries. It is another thing to understand what already exists across hundreds or thousands of sites.
Existing content is often where the storage opportunity is.
Automatic vs. manual version limits
SharePoint provides different ways to manage version history.
| Mode | What it does | Best fit |
|---|---|---|
| Automatic | SharePoint uses intelligent trimming based on version age. Recent versions are preserved more densely, while older versions are thinned over time. | Recommended default for many organizations that want Microsoft-managed optimization. |
| Manual with count and expiration | Admins specify how many major versions to keep and how long versions should remain. | Useful when you want more direct control and predictable cleanup. |
| Manual with count only | Admins keep a configured number of versions without age-based expiration. | Useful when a fixed restore count matters, but it can consume more storage. |
Microsoft’s guidance highlights that automatic trimming is designed to preserve high-value versions while optimizing storage. Manual policies can be useful, but they require careful planning because low limits or short expiration windows can affect restore scenarios.
That is why I wanted this tool to include reporting and What-If analysis before cleanup.
What the tool does
Apply-SPOVersions-Tool.ps1 is an interactive PowerShell tool built with PnP PowerShell to help admins manage SharePoint Online version policies across multiple site collections.
At a high level, the tool helps admins:
- Audit current version policies across sites.
- Apply automatic or manual version limits.
- Review version policy status.
- Generate version history reports.
- Run What-If analysis to estimate storage recovery.
- Create batch delete jobs for cleanup.
- Monitor cleanup job status.
- Set tenant-level defaults for new sites.
This makes it useful for both planning and implementation.
Why I built it as an admin workflow
Version cleanup should not start with deletion.
The safer workflow is:
- Discover current settings.
- Generate version history reports.
- Estimate storage recovery.
- Decide the right policy.
- Apply policy to selected sites.
- Queue cleanup jobs.
- Monitor job status.
- Repeat as part of governance.
That is how the tool is structured.
It is not just a cleanup script. It is a planning and execution tool.
Site discovery options
The tool can work from a defined list of site URLs or discover sites automatically.
For larger tenants, I usually prefer a site list because it gives admins better control over rollout scope. You can start with a pilot group, validate results, then expand.
For smaller tenants or discovery scenarios, auto-discovery can be useful.
The tool supports:
- SharePoint sites
- OneDrive for Business sites
- Exclusion of common system sites
- Confirmation before processing discovered sites
That confirmation step matters. When a script can operate across many sites, admins should have a checkpoint before changes are made.
Key operations
1. Get current version policies
Before changing anything, admins can retrieve current version policy settings for all selected sites.
This helps answer:
- Which sites already use automatic trimming?
- Which sites use manual limits?
- Which sites have inconsistent settings?
- Which sites may need exceptions?
This is useful for building a baseline.
2. Set version policies across sites
After planning, admins can apply version policies across site collections.
The tool supports:
- Automatic version trimming
- Manual major version limits
- Optional expiration after a specified number of days
Automatic trimming is useful when you want SharePoint to optimize storage intelligently. Manual limits are useful when the organization has a defined policy, such as keeping a specific number of major versions or expiring versions after a specific period.
3. Check version policy status
Policy changes may take time to apply.
The tool can check propagation status so admins can verify whether pending changes completed successfully.
This is important during staged rollouts because you want to confirm policy state before moving on to cleanup.
4. Generate version history reports
This is one of the most important parts of the workflow.
The tool can submit version history report jobs for each site. Those reports are written to a dedicated document library created by the tool:
Admin_SiteCollection_VersionReport_DONOTDELETE
Using a dedicated library avoids some of the issues that can happen when report files are written into normal user-facing document libraries.
The reports provide the raw data needed to understand version storage usage.
5. Run What-If analysis
This is the feature I think most admins should start with.
The What-If analysis downloads completed version history reports and simulates a version policy without making changes.
That means admins can estimate:
- Total versions analyzed
- Versions that would be deleted
- Total version storage
- Storage that could be recovered
- Percent of version storage that could be freed
- Per-site savings
This gives admins data before they commit to a cleanup policy.
For example, a What-If analysis might show that one site can recover a large amount of storage while another site has very little benefit. That helps prioritize action.
6. Create batch delete jobs
Once the admin understands the impact and chooses a policy, the tool can create batch delete jobs to remove excess versions.
This is the destructive part of the workflow, so it should come after reporting and What-If analysis.
Admins can use automatic or manual cleanup criteria depending on the desired policy.
Important reminder: deleted versions are not recovered from the Recycle Bin. Treat batch delete jobs as permanent cleanup operations.
7. Monitor batch delete job status
After cleanup jobs are created, admins need to know whether they completed and how much storage was released.
The tool can check batch delete job status across sites, including completion state and storage released where available.
This closes the loop from planning to execution.
Tenant-level defaults vs. existing content
One important distinction in SharePoint version management is the difference between tenant-level defaults and existing content.
Tenant-level settings affect new sites or new libraries going forward. Existing sites and existing file versions may need additional steps.
Microsoft’s guidance describes multiple approaches:
| Scenario | What it means |
|---|---|
| Apply defaults to new libraries only | Least disruptive; existing settings and versions remain unchanged. |
| Update existing library settings without trimming versions | Future versions follow the new policy, but existing versions are not deleted. |
| Update settings and trim existing versions | Aligns current and future behavior, but requires careful planning and cleanup jobs. |
This tool helps with the third scenario, where admins need to understand and manage existing version storage across sites.
A practical rollout approach
For most tenants, I would not recommend starting with the entire environment.
A safer rollout looks like this:
| Phase | Action |
|---|---|
| Phase 1: Baseline | Get current version policies across a small set of sites. |
| Phase 2: Report | Generate version history reports for pilot sites. |
| Phase 3: What-If | Estimate storage recovery under automatic or manual policies. |
| Phase 4: Decide | Choose default policy and identify exceptions. |
| Phase 5: Apply | Apply policy to selected pilot sites. |
| Phase 6: Cleanup | Queue batch delete jobs only after review. |
| Phase 7: Monitor | Check job status and storage released. |
| Phase 8: Expand | Repeat across additional sites or workloads. |
This creates a defensible admin process instead of a one-time cleanup event.
Where this helps most
This tool is especially useful in tenants with:
- Large document libraries
- Heavy collaboration sites
- Long-running project sites
- Migration history
- Large Office files with frequent edits
- Storage pressure
- Inconsistent site-level version policies
- Need for tenant-wide governance reporting
It can also help organizations that want to move toward automatic trimming but need to understand the impact first.
Permissions and prerequisites
The tool uses PnP PowerShell and interactive authentication.
Typical prerequisites include:
- PowerShell 5.1 or later
- PnP.PowerShell 3.1.0 or later
- SharePoint Administrator role
- Entra ID app registration
- Delegated SharePoint permissions required for version policy and report operations
The repository README includes setup details and permission guidance:
As always, review permissions carefully before using any tenant-wide admin automation.
Safety notes
Version cleanup can permanently remove version history.
Before creating cleanup jobs:
- Run reports first.
- Run What-If analysis.
- Start with pilot sites.
- Review business requirements.
- Identify exceptions.
- Communicate expected behavior to site owners.
- Keep exported results for audit and planning.
- Avoid opening or modifying report CSV files while report jobs are still running.
The tool is designed to support safe planning, but admins still need to make policy decisions carefully.
Why this belongs in your governance toolkit
SharePoint storage management is not just about quota.
Version history touches:
- User recovery expectations
- Records and retention requirements
- Collaboration patterns
- Site lifecycle
- Migration cleanup
- Storage forecasting
- Governance consistency
If version history is unmanaged, storage growth can feel mysterious. Once you report on it, it becomes something you can plan and control.
That is the point of this tool: help admins move from guessing to measuring, then from measuring to controlled action.
Final thoughts
SharePoint version history is valuable, but it needs governance at scale.
Microsoft provides flexible version storage options, including automatic trimming and manual limits. The challenge for admins is understanding what exists today and how much storage could be recovered before applying changes.
Apply-SPOVersions-Tool.ps1 helps with that process by combining policy discovery, report generation, What-If analysis, policy application, cleanup jobs, and job monitoring into a single admin workflow.
You can find the tool here:
Microsoft’s official planning guidance is here: