Version history alone can add five times the visible file size to a cross-tenant migration. An 80 GB document library with active versioning can require 400 GB to transfer, and that number determines whether you finish in an evening or spend a week troubleshooting a mid-job quota error on the destination tenant. This guide covers every step from pre-migration audit to post-migration sign-off.
What migrates and what does not
Several common items migrate with limitations or not at all. Knowing which before you start avoids surprises at sign-off.
| Item | Migrates? | Notes |
|---|---|---|
| Files and nested folder structure | Yes | All files including subfolders replicated to destination |
| Custom column values (metadata) | Yes | Copy structure and content creates the columns at the destination first; if you pre-build the library yourself, internal names must match |
| Version history | Yes, all or a set number | The copy options keep every version or a number you choose per file; see Step 2 |
| Library and item permissions (broken inheritance) | Yes, with user mapping | Copied when Copy all permissions is on. Source accounts are matched to destination accounts through the user mapping you set up, so map anyone whose account name differs in the new tenant |
| Sharing links | No | Links point at the source tenant and are not recreated; review and revoke them before migrating |
| Content types and views | Yes | Created on the destination as part of the library structure |
| Column default values | Check after the copy | Column definitions travel with the structure, but confirm default values, especially folder-level defaults, on the destination library |
Step 1: Audit the source library before touching anything
A thorough pre-migration audit takes 20 minutes and prevents hours of cleanup after the fact. Connect ShareMaster to the source site and run two reports from Reports: Site Storage Metric for the storage picture and Security Matrix for permissions and sharing links on the libraries you plan to move.
Check the storage breakdown
The storage report gives each library's total size, current file size and the amount taken by version history. If version history is more than 30 to 40 percent of the total, limiting the versions you carry is the single most impactful thing you can do to reduce transfer time and cost.
Note the largest individual files, which the report lists on a separate sheet. A single 10 GB video or CAD archive can dominate a migration window on its own. Knowing those outliers in advance lets you schedule the job accordingly rather than discovering them halfway through.
Audit and revoke sharing links
Sharing links created in the source tenant reference URLs specific to that tenant's domain. After migration, those links point nowhere. More critically, any active guest access associated with those links could carry over as metadata that creates confusion in the destination permission picture.
In ShareMaster's Share Link Finder (under Explore & Inspect), pick the library and run Report on shared links to get every link and who it reaches in Excel. Confirm with the content owner which links are still needed, then run Remove shared links (paid licence) to revoke the rest before the migration starts.
Step 2: Decide how much version history to carry
Most SharePoint libraries accumulate version history without a cap. A library of 10,000 documents that has been actively used for three years can hold 50 or more versions per file. The math adds up fast: 50 GB of live content with 40 versions per document can approach 2,000 GB to transfer.
You have two levers. The copy itself can carry fewer versions: in the copy options, turn off Retain all versions and set the Number of versions to retain per file, which leaves the source untouched. If the source library should shrink as well, run Space Master's Version Trimmer on it first, in report mode before the real run. For general document storage, 10 to 20 major versions covers most recovery needs. For libraries used for formal document control records, confirm the retention requirement with the business owner first.
If you trim the source, run the storage report again to capture the updated figure. That number tells you whether the destination tenant has sufficient quota headroom before you start the job.
Step 3: Prepare the destination site
Cross-tenant migrations are cleaner when the destination is ready before you start. Do this before opening the copy.
- Create the destination site. Match the site and library names and URLs where possible to reduce post-migration link updates. If Replace Master is part of your toolset, you can fix URL mismatches after the fact, but eliminating them upfront is simpler.
- Let the copy build the library. Copy structure and content creates the library with its columns, views and content types on the destination before it copies the files, so you do not need to recreate them by hand. If you would rather build the library yourself and use Copy content, give every column the same internal name and type as the source.
- Confirm destination quota. Check available storage headroom against the expected migration size. Leave at least 20 percent margin above the expected transfer volume. If the destination is close to its limit, address that before starting: running out of quota mid-job creates a partially migrated library that is difficult to reconcile cleanly.
Step 4: Run the cross-tenant document library migration
Both tenants must be accessible from the same Windows machine running ShareMaster. Open Copy & Move (the Clone Master tools) and choose Copy structure and content.
- Sign in to the source site, then to the destination site on the other tenant.
- On the Lists & Libraries tab, select the source library.
- Open the options and set version history, Copy all permissions, and whether to skip files that already exist at the destination.
- Open the user mapping and pair each source account with its destination account where the names differ between tenants.
- Start the copy.
If the job is interrupted by a network drop or machine restart, run it again with Skip file/item if exists at destination. ShareMaster checks what is already there and copies only what is missing, so nothing already transferred is duplicated.
For large libraries, schedule the job to run overnight or across multiple evenings to avoid bandwidth competition with business users. SharePoint throttles sustained high-volume API traffic, so running during off-peak hours reduces the chance of 429 responses slowing throughput. For detail on how throttling works and how to respond to it, see the SharePoint migration throttling limits reference.
Step 5: Verify results and sign off
After the copy reports complete, verify before decommissioning anything on the source side.
Run the Compare Items Report from Reports with the source library on one side and the destination library on the other. It lists each item's ID, path, name and size for both sides, so missing or mismatched files stand out. Then spot-check five to ten documents from different folders: open each in SharePoint Online, confirm the current version content is correct, check that custom column values are present, and verify the version history list contains the expected number of entries.
Bring in a business user who works regularly with the library for a brief acceptance check. An admin verifying file counts is not the same as a content owner confirming that a key document's metadata and version history look right. Both checks serve different purposes and together provide a solid basis for signing off.
Once verified, revoke remaining source access, update any navigation or search links pointing to the old library URL, and leave the source library in read-only mode for an agreed handover period before decommissioning it.
Frequently Asked Questions
Does Clone Master preserve metadata when migrating a SharePoint library cross-tenant?
Yes. With Copy structure and content, ShareMaster creates the library's columns, views and content types on the destination and then copies the files with their column values. If you copy content into a library you built yourself instead, its columns need the same internal names as the source for values to land.
What happens if a cross-tenant SharePoint migration is interrupted?
Run the copy again with the option Skip file/item if exists at destination (or Skip file/item if newer at destination). ShareMaster checks the destination and copies only what is missing or out of date, so files already transferred are not duplicated. Whole-site copies also record which stage they reached and offer to carry on from there.
Should I trim version history before migrating cross-tenant?
Usually you should limit it, but you do not have to trim the source to do so. Version history multiplies effective data volume significantly on actively edited libraries, and the copy options let you carry all versions or only a set number per file. Trim the source as well only if you also want to reclaim its storage.
What admin permissions are needed for a cross-tenant library migration?
SharePoint Administrator rights on both tenants, or at minimum Site Collection Administrator access for the specific sites on each side. Global Administrator access covers all required permissions on both source and destination.
A trial licence copies with items skipped at random intervals by design, so use it to test the workflow on a sample library, not to produce the real copy.