Edit

Share via

Cross-tenant SharePoint migration (preview)

  • Article

Note

Cross-Tenant SharePoint migration is currently in a private preview stage of development. As an unfinished project, any information or availability is subject to change at any time. Support for private-preview customers will be handled via email. Cross-Tenant SharePoint migration is covered by the preview terms of the Microsoft Universal License Terms for Online Services.

SharePoint sites can now be moved from one tenant to another using the Cross-tenant SharePoint migration feature.

Using SharePoint Online PowerShell, SharePoint Admins can to transition sites into their new tenants.

Up to 4,000 SharePoint accounts can be scheduled for migration in advance at a given time. Once scheduled, migrations occur without content ever leaving the Microsoft 365 cloud and with minimal disruption. When migrations are complete, a redirect is placed in the location of the user's original SharePoint site, 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.

How to participate

The Cross-Tenant User Content Migration feature and licenses are currently only available to Enterprise Agreement customers.

If you're an Enterprise Agreement customer who will be purchasing Cross-Tenant User Content Migration licenses, and you would like to evaluate Cross-Tenant SharePoint migration to improve your migration experience, sign-up at:

Make sure to include all of the requested information, and indicate your interest in "SharePoint cross-tenant data migration (Mergers and Acquisition scenario)".

For more information on licensing:

Prerequisites and settings

Target SharePoint sites and Group-connected SharePoint sites

Important

  • Don't create any target SharePoint sites before starting your migration. If the site already exists on the target tenant the migration will fail. You can't overwrite or merge an existing site.

  • Target Microsoft 365 Groups for group-connected SharePoint site migrations can't be linked to existing SharePoint sites. Target Microsoft 365 groups must be pre-created in a specific way.

Before starting any migrations, make certain that your source SharePoint sites are set to Read/write mode. If they are set to read-only the migration will fail.

  • Each individual SharePoint site being migrated must have no more than 5 TB of storage, or 1 million items. If during a migration of multiple sites a site with more than 5 TB is encountered, that site will eventually timeout and fail. Sites less 5 TB will continue until completion.

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

  • Ensure all users and groups identified for migration have been pre-created on the target tenant.

  • Assign the appropriate licenses to each user on either the Source or the Target tenant. The license does not need to be applied in both locations.

Path size limits

Microsoft character path limit cannot exceed 400 characters. We recommend shortening your Target User and Site URL names to stay within the character limit.

Consider the length of User and Site ULR names in your Target tenant when planning your migrations. Longer user and site URL names may result in migrations failing. Remember that the source's file or folder path name is combined with the new user or site name on the Target. Make sure that total doesn't exceed the 400-character path limit.

If your migration fails, rename the User or Site URL or work with the user to rename or move the affected files or folders higher up the directory structure to ensure it remains under the character threshold limit. Once resolved, you should be able to complete the migration.

Support SharePoint features

The following types of site can be migrated between geographic locations:

  • Microsoft 365 group-connected sites, including those sites associated with Microsoft Teams
  • Modern sites without a Microsoft 365 group association
  • Classic SharePoint sites
  • Communication sites

Important

This feature does not include migration of Teams content, channels or associated structure. If a Teams-connected SharePoint site is migrated, only the SharePoint site content will be migrated to the target.

When the SharePoint site migration completes, the existing shared links for the files that were migrated will automatically redirect to the new geographic location.

Permissions

Users with permissions to site may continue to have access to the site after the migration is complete, provided those users/groups were accounted for in the Identity Mapping step.

SharePoint Workflows

Workflows (2010 or 2013) must be re-created and republished on the Target tenant.

Apps

If you're migrating a site with Apps, you must republish & potentially modify the App on the target tenant.

PowerApps/PowerAutomate

PowerApps & Automation Tasks must be re-created and reconnected to the Site on the target tenant.

Web Parts

Web parts that reference content in other SharePoint Sites and/or other Microsoft 365 services (such as email, calendars) may need to be modified or re-created on the target tenant.

Sensitivity labels

Labels associated with migrated files may not display correctly in M365 user experiences. In addition, any protection or policy associated with the original label won't be present after migration. To apply protection or policy, the recommendation is to remove labels from files before migration, and reapply new labels as appropriate after migration.

Sensitivity Labels with User-Defined Permissions

Sites containing Sensitivity labels with user-defined permissions can't be migrated using cross-tenant migration. This guidance refers to sensitivity labels where the setting Let users assign permissions when they apply the label is selected in the label definition. More information can be found here: Enable sensitivity labels for files in SharePoint and OneDrive.

In order to migrate sites containing Sensitivity labels with user-defined permissions, the labels must first be removed from files within the sites. This action can be done either manually, or by using Unlock-SPOSensitivityLabelEncryptedFile.

Example:

Unlock-SPOSensitivityLabelEncryptedFile. -FileUrl "https://contoso.com/sites/Marketing/Shared Documents/Doc1.docx" -JustificationText "Need to decrypt this file".

Communicating with your users

When migrating SharePoint sites between tenants, it's important to communicate to your users what to expect.

  • How will this migration impact them?
  • Will they be able to continue to work during the migration?
  • When will the migration start and how long will it last?
  • What is the new URL in which to access their new site plus any other details about the new tenant
  • Advise users to close their files and not make any edits during their migration window.
  • Advise of any file permissions or sharing changes that may occur as part of the migration.

Scheduling SharePoint site migrations

You can schedule SharePoint site migrations in advance but consider the following recommendations:

  • Start with a small number of sites to validate your workflows and communication strategies
  • Once you're comfortable with the process, you can schedule large batches of migrations.
  • You can schedule up to 4,000 migrations at a time per batch
  • As the migrations begin, you can schedule more, with a maximum of 4,000 pending migrations in the queue at any given time.

Get started

Step 1: Connect to source and target tenants