Cross-tenant OneDrive migration

  • Article

Note

Information in this article refers to Cross-tenant OneDrive migration. For mailbox migration, see Cross-tenant mailbox migration.

Overview

During mergers or divestitures, you commonly need the ability to move users OneDrive accounts into a new Microsoft 365 tenant. With Cross-tenant OneDrive migration, tenant administrators can use familiar tools like SharePoint Online PowerShell to transition users into their new organization.

SharePoint administrators of two separate tenants can use the Set-SPOCrossTenantRelationship cmdlet to establish an organization relationship, and the Start-SPOCrossTenantUserContentMove command to begin cross-tenant OneDrive moves.

Up to 4,000 OneDrive accounts can be scheduled for migration in advance at a given time. Once scheduled, migrations occur without the user's data ever leaving the Microsoft 365 cloud and with minimal disruption, requiring only a few minutes where a user's OneDrive will be read-only. When migrations are complete, a redirect is placed in the location of the user's original OneDrive, so any links to files and folders can continue working in the new location.

Important

Cross-Tenant moves are a one and done migration activity. The content will be moved from the Source to Target, leaving behind a redirect link on Source. Incremental and delta migration passes cannot be performed.

Note

This feature is not supported for users of the Government Cloud, including GCC, Consumer, GCC High, or DoD.

Licensing

Important

As of Nov. 2022, Cross Tenant User Data Migration is available as an add-on to the following Microsoft 365 subscription plans for Enterprise Agreement customers, and is required for cross-tenant migrations. User licenses are per migration (one-time fee) and can be assigned either on the source or target user object. This license also covers Cross-tenant mailbox migration. Contact your Microsoft account team for details.

The Cross Tenant User Data Migration add-on is available as a separate purchase for Microsoft 365 Business Basic, Standard, and Premium; Microsoft 365 F1/F3/E3/E5; Office 365 F3/E1/E3/E5; Exchange Online; SharePoint Online; and OneDrive for Business.

Warning

You must have purchased, or verified that you can purchase, cross tenant user data migration licenses prior to the next steps. Migrations fail if this step has not been completed. Microsoft does not offer exceptions for this licensing requirement.

Prerequisites and settings

Pre-create target accounts

  • Ensure all users and groups identified for migration have been pre-created on the target tenant.
  • Assign the appropriate licenses to each user on the target tenant.

Important

OneDrive sites should NOT be created before OR during a migration.

OneDrive site creation should be restricted in the target tenant to prevent users from creating OneDrive sites. If a OneDrive site already exists for the user on the target tenant, the migration will fail. You can't overwrite an existing site.

If users continue to access resources in the source tenant, you should restrict OneDrive creation in the source tenant to prevent creating new OneDrive sites.

Note

To learn more about restricting OneDrive site creation, see Disable OneDrive creation for some users

Path size limits

Microsoft limits the number of characters in a path to not exceed 400 characters. This is the full path limit, not just the file name. In planning your migrations, review the length of OneDrive URL names in your target tenant. Failure often occurs when files or folder paths from the source, combined with the OneDrive URL on the target exceed the 400-character path limit.

A migration will detect if you have exceeded the character limit. Work with the site owner to update the file/folder directory structure to reduce file path lengths.

Any legal URL will be accepted when creating your Identity Map from Source to Target for your migrations. At this current time usernames/URLs that contain an apostrophe character ( ' ) in a username/URL will fail with an "invalid character" error when attempting the migration.

Tip

We recommend keeping your target OneDrive URL names short to avoid exceeding the character limit.

OneDrive account size limits

Each OneDrive account can have a maximum of 5 TB of content or 1 million items.

Important

The 1 million item limit can be any "item", including files (including versions), folders, and list line entries if it is a list or library.

If you attempt to migrate any OneDrive site that exceeds the 5 TB quota, the transfer will fail.

Permissions

All users and groups included in the identity mapping file that you uploaded to the target tenant will maintain permissions in the target tenant related to the migrated OneDrive site.

OneDrive accounts with a Hold policy applied will be blocked from migration. To migrate these OneDrive accounts, remove the hold policy, migrate, then reapply the hold as needed on the target tenant.

Shared files

After a OneDrive account is migrated, anyone clicking on a shared link to the old location will be redirected to the new one, provided they still have access to the destination.

Those redirects remain until the source tenant is deprovisioned. The admin can also selectively remove redirects site-by-site.

How does it work?

Step 1: Connect to source and target tenants