Cross-Tenant SharePoint Migration (Preview): What You Need to Know

Microsoft now offers a native, in-preview way to move SharePoint Online and OneDrive content between tenants — for mergers, acquisitions, divestitures, or restructuring — instead of relying on third-party tools like ShareGate or AvePoint. It’s Microsoft-managed and doesn’t need a separate migration platform, but it comes with its own licensing requirements and prep work.

In this post: Licensing and prerequisites · How it works · Sample PowerShell · Real limitations to plan around · Best practices · When would you actually use this?

Licensing and prerequisites

Group-based permission mapping is preferred over user-level mapping. On the licensing side:

Microsoft 365 E3 or E5 on both source and target tenants (includes SharePoint Online).
Microsoft Entra ID Premium P1 or P2, recommended for B2B direct connect.
A Cross-Tenant User Data Migration Add-On license is required for each user being migrated — this is new and easy to miss when budgeting the project.

A Cross-Tenant User Data Migration Add-On license is required for every user being migrated — budget for this per-user cost before scoping the project, not after.

Official licensing reference.

How it works

Establish cross-tenant trust via Microsoft Entra B2B direct connect.
Configure mappings — domain, user, and group mappings between tenants.
Initiate migration jobs via PowerShell; Microsoft handles the actual transfer through a secure backend pipeline.
Validate and finalize — check migrated content, reassociate permissions, finalize DNS/domain ownership transfers if needed.

Microsoft’s setup guide covers the full prerequisite checklist.

Sample PowerShell

# Connect to the SOURCE tenant's SharePoint admin center
Connect-SPOService -Url https://<sourcetenant>-admin.sharepoint.com

# Check compatibility before queuing anything
Get-SPOCrossTenantCompatibilityStatus -SourceSiteUrl "https://source.sharepoint.com/sites/ProjectX" `
                                       -TargetCrossTenantHostUrl "https://target.sharepoint.com"

# Queue the actual site move
Start-SPOCrossTenantSiteContentMove -SourceSiteUrl "https://source.sharepoint.com/sites/ProjectX" `
                                     -TargetSiteUrl "https://target.sharepoint.com/sites/ProjectX" `
                                     -TargetCrossTenantHostUrl "https://target.sharepoint.com"

Prerequisites and mappings need to be set up before this will run — authentication between tenants has to be configured via Entra B2B policies first. (The cmdlet is Start-SPOCrossTenantSiteContentMove specifically — Start-SPOMigrationJob, which shows up in some older guides, is actually for a different scenario: on-premises-to-SharePoint-Online migration, not tenant-to-tenant.)

Real limitations to plan around

Worth knowing before scoping a migration on this, not after:

No incremental/delta moves — this is one-and-done per site or OneDrive account. There’s no way to do an initial sync followed by a final delta pass the way some third-party tools support; plan for the actual cutover window, not a staged sync.
No merging into existing target content — for OneDrive specifically, the migrating user can’t already have a OneDrive on the target tenant. That has to be resolved (renamed, removed, or the user handled differently) before the move, not during.
Hard capacity limits — 5TB and 1 million items per OneDrive account, with a 400-character path length cap. A handful of very large or deeply-nested accounts can silently blow past these and need a different approach.
Legal holds block the move outright — an account under hold has to have it removed, get migrated, then have the hold reapplied on the target side.
Not available on Government Cloud tenants (GCC, GCC High, DoD) — if either side of the migration is on one of those, this native path isn’t an option at all.

Best practices

Plan thoroughly — map every user, group, and site collection being migrated, and review storage quotas and permissions upfront.
Pilot first — a small test migration before committing to the full scope.
Communicate downtime and timelines to end users before it happens, not during.
Back up critical content anyway — the migration path is secure, but a fallback is cheap insurance.
Use Entra group mappings to avoid broken permission inheritance during the move.
Monitor jobs actively via logs and reporting rather than assuming success.

When would you actually use this?

Your organization is merging with or acquiring another company and needs to consolidate SharePoint content into one tenant.
A divestiture requires splitting off a business unit’s content into its own separate tenant.
You’re currently paying for a third-party migration tool and want to check whether the native path now covers your scenario — worth revisiting given this is still in preview and evolving.

Hope that saves you some time — drop a comment if anything’s unclear.