Microsoft Teams to Microsoft Teams Migration Guide

Teams Private Chats 

Teams Private Chats now migrate. Follow the steps in the new guide to migrate private chats and linked files.

Teams to Teams Migration 

This document is an end-to-end migration guide that demonstrates how to perform an Office 365 Teams to Teams migration using MigrationWiz. MigrationWiz supports the migration of teams, channels, conversations, permissions, and files.  

We are not able to support migrations with two-factor or multifactor authentication. 

For more information on special case migrations, frequently asked questions, and other information, see Microsoft Teams Migration FAQs and Teams Troubleshooting & Error Lookup

MigrationWiz is a migration tool, not a syncing tool. If changes are made at the source after migration, they will not sync to the destination, nor will changes made at the destination sync to the source. We do not have “live” monitoring of changes (as with a sync agent) and we cannot handle scenarios such as conflict resolution without user interaction.


This migration type requires the MigrationWiz-Collaboration (per Team) license type.

  • Each license allows up to 100GB of data to be migrated per license per team.
  • If more than 100GB of data per team is being migrated, purchase enough licenses to cover the total amount of data being migrated. For example, if you have six teams and two of them have 200GB of data, you will need to purchase 8 licenses. 
  • Each license is applied to a single team and expires 12 months after its purchase date. 


Ensure consent has been given for the Teams application permission.

Use either Teams-ReadOnlyApp or MigrationWiz-Teams-FullControl for Source and MigrationWiz-Teams-FullControl for destination. 

Refer to recommended steps. 

  1. Ensure you are signed in as a Global Admin in the Office 365 Admin Portal.

  2. To enable permission at the Source, go to either Teams-ReadOnlyApp or MigrationWiz-Teams-FullControl and consent to the app access when prompted.

  3. To enable permission at the Destination, go to MigrationWiz-Teams-FullControl and consent to the app access when prompted.
  4. Note that if you are migrating 'Document Permissions', you will need to use MigrationWiz-Teams-FullControl for both Source and Destination tenant. 
    Perform below steps 5 to 7 for both Source and Destination: 
  5. Create new Security Group named “MigrationWiz” on the Office 365 Admin Portal. If you have not created a security group before, follow Microsoft's instructions.

  6. Create new user. This user must have an active Teams license applied.

  7. Add new user to previously created security group as a member. Important: ADFS and MFA must be turned off for this user.

  8. Create MigrationWiz project.

  9. When creating the endpoints, enter the new user credentials.

Create a New Project

  1. Go to Projects.
  2. Click Create Project.
  3. Select Collaboration Project.
  4. Update the project information: add a Project Name, select a Customer from the drop down, then click Next Step.
  5. Create the source endpoint by selecting Microsoft Teams (Source) from the drop down.  
  6. Provide your Office 365 credentials (these will be the same Office 365 username and password      you use for the MigrationWiz security group), then click Add.
  7. Next, create a destination endpoint by choosing an Endpoint Name and selecting Microsoft Teams (Destination) from the endpoint-type drop down. 
  8. Enter your Office 365 credentials. These will be the same username and password you used for the MigrationWiz security group. Once your credentials are selected, click Add.
  9. One of the two Azure Storage options listed is required to create the endpoint. For migrations of less than 5GB, you may use the Microsoft Provided Azure storage. For anything over 5GB, we recommend using Custom Azure Storage. The following steps will help you set up the custom storage:
    1. Prepare Azure Environment. If using Microsoft-provided Azure storage, you can skip this section.
    2. Estimate Azure storage costs. This step is optional but is useful in order to provide the customer with upfront storage costs ahead of time. For more information, see Estimate Azure Storage costs for migrations. 
    3. Buy an Azure subscription. You can also use the free one-month trial but be aware that this option is only viable if you are performing a very small migration. 
    4. See How to create Azure StorageV2 storage for destination endpoints to create your storage account. You will need to set up a STORAGE (General Purpose v2) account rather than a storage blob. Take note of the storage account name and the primary access key. (In Azure, from the storage screen, click Manage Access Keys at the bottom of the screen.) These need to be entered into the MigrationWiz migration project when specifying the destination settings. We recommend that you create your Azure storage account in the same Microsoft data center as the destination Office 365 tenant. There is no need to create any Azure containers for this migration. 
    5. The access key information that is needed are these: 
    6. -accesskey – This is the Storage account name for the Blob – example “accountname 
    7. -secretkey - This is the access key for the Storage account – example “W1RrDfkPNkfYfdVqizMNJjn5mXchwMP5uYBY8MsMqWTA7EubG911+4fZlki0Gag==” 
  10. Once complete, click Save and Go to Summary.
  11. Verify that both the source and destination are Microsoft Teams. Variable endpoints are not supported.
  12. For the following step, credentials are mandatory. Ensure all the mandatory fields are filled to activate the Update button. Click this once all steps above are completed.

Add Teams

There are three ways to add teams to the migration. Either of these may be used, or both. Read through each of the options before beginning your process. Follow the Autodiscover process to find all the teams you are moving, and then select either Quick Add or Bulk Add. Generally, Quick Add will be used for small migrations, proof of concept migrations, and other tests, while Bulk Add will be used for large migrations and full migration passes. The Team name added to the project use the mailnickname only.


  1. On the MigrationWiz project page, click the Add dropdown, then click Autodiscover Items.
  2. Click Start Autodiscover.
  3. Click Discover ItemsMigrationWiz will now discover teams at the source. If the authentication/credentials verification is successful, discovery status will show as Completed however, if the authentication/ credentials verification fails, error messages will be shown.
  4. To download a CSV, click the Download CSV icon. This will generate a CSV file that includes all the teams discovered at the Source. This file can be uploaded via Bulk Add during that stage.
  5. Click Import Items. The discovered Teams at the Source will be populated as line items. By default, destination mail nickname will be set to the same as Source mail nickname.

Quick Add

This option is generally used for small migrations, proof of concept migrations, and other tests. It allows you to migrate specific teams without the full CSV management.

  1. Click Add.
  2. Select Quick Add Item.

You may now add a specific team to be migrated, based on the Team Mail Nickname at the source, e.g. TeamAwesome. You will be able to select the mapping at the destination, including renaming teams if desired. For example, TeamAwesome may be mapped to TeamAwesome at the destination, or to TeamFantastic. 

If TeamFantastic exists at the Destination, the contents from TeamAwesome will be merged to the existing TeamFantastic. If TeamFantastic does not exist at the Destination, it will be created with the data from TeamAwesome.

Bulk Add

You also have the option to use Bulk Add via the CSV template file to manage adding your teams. This is a good option if you are mapping a large number of teams to new destinations, or simply have a large migration. Previously, this had to be done manually, but with the Parallel update, this is now all done within the user interface.

  1. In your project dashboard, click Add.
  2. Select Bulk Add. 
  3. The interface will now walk you through the steps up upload the CSV found through the Autodiscover process. You may edit the columns after upload to change team names or mapping. 

Start Migration

Use the checkbox to select the team(s) you will be migrating.

You will need to run a single verify credentials pass before migrating multiple items.


    1. Click the Start dropdown and select Full Migration. This will bring up a new window to select what data you want to migrate in this pass. 
    2. Select Setting Up Teams, then Teams Creation if it is not selected by default. 
    3. Click Start Migration. This pass will create the teams at the destination. Once the teams creation process has been successfully completed, wait a few hours to allow the data to finalize.  
      Important: Due to an API limitation, the channels may not be fully provisioned until they are used.
  1. You will now repeat the full migration process for the data. Repeat step 1, but select Migrate Data this time. Perform the following data migration steps as best practice:
    1. Migrate conversations and documents first.
    2. Migrate OneNote tabs.
    3. Migrate Teams permissions
    4. Migrate Document Permissions
  2. Check the Status column for each team migration progress to ensure your teams are migrating correctly. If teams are not migrating correctly, check the credentials and run another full pass if necessary.startmig3.png
  3. User mapping: By default, we match users from the source to the destination based on the prefix in their User Principle Name (UPN). For example, if the user UPN is “”, we match the “name” portion. If there are multiple people with the same prefix at the destination (e.g. and, or the prefix of a particular user is changed in the destination (e.g. →, it is necessary to use the advanced option UserMapping=">" to set the new or correct name for each user.
  4.  The User Mapping command goes in the Support Options section and will require one line per user that needs mapping. Click the + to add additional lines. Replace the UPN addresses in the example with the actual UPN addresses. 

Resolve Errors 

Errors vary widely, so if you encounter migration errors, refer to the Collaboration error list and follow the steps listed under Resolution.

If a migration completes successfully, but not all members show on the Teams destination, the users may be taking extra time to sync.  

This can happen when a Team has a large number of users. It is possible to verify that all the users were migrated by logging into the Office 365 Admin portal, going to the migrated group (Team), and viewing the members list to verify that the expected number of members were migrated. This should be synced to the Teams interface within the next few hours. 

Post Migration

Once the migration has finished, remove the Office 365 user account created for the migration, as well as the MigrationWiz Security Group. 

You will also need to remove the Azure app:

  1. Once the migration has finished, remove the Office 365 user account created for the migration, as well as the MigrationWiz Security Group. You will also need to remove the Azure app using these steps:
    1. Launch PowerShell.
    2. Connect PowerShell to Office 365.
    3. Enter the command: Connect-AzureAD
    4. Enter the admin credential in the prompt.
    5. Enter the command: Get-AzureADServicePrincipal -SearchString Migration
    6. Look for the ObjectId of the app you want to remove and enter the following command: Remove-AzureADServicePrincipal -objectId <the object id>

Special Circumstances

Migrating Channel Conversations

MigrationWiz will migrate 60 messages per team by default.

A Conversation History tab will be created for each corresponding channel at the destination. Each team will show the most recent 60 messages, while all older messages may be downloaded as an HTML file in the Conversation History tab.

  • The total number of messages to be migrated can be increased via this Advanced Option: TeamsMaxConversationPostPerTeam=XX

    Replace XX with the number of messages you wish to migrate.
    E.g. TeamsMaxConversationPostPerTeam=1000 would load 1000 messages per team.

    This may slow your migration, so plan accordingly if this option is used

Migrating Private Channels


Important: If using the "TeamsMigratePrivateChannel=1" Advanced Option, Private Channels will not be created during the scaffolding run in order to improve the success rate for their SharePoint site provision. Tests have shown that if private channels are created before the parent team SharePoint sites are ready, the private channel SharePoint site will not be created automatically.

This script must be run with either Teams Admin or Global Admin credentials or it will fail.

The csv file will be exported to the location from which the script was run. If the script was run from a different location than where it is stored, the csv will be found in the location from which the script was run, not from where it was stored.

If there are no private channels in the source tenant, then no csv file will be exported.

To migrate teams with private channels:

  1. Identify the teams with private channels in the source tenant via the MWTeamsPrivateChannelMembers.ps1 script attached at the end of this page.
  2. Add the Advanced Option TeamsMigratePrivateChannel=1 into the project.
  3. Do a scaffolding run ONLY first:
    1. Select “Teams Creation” in the Start Full Migration flyout.
    2. If there are any errors encountered during the scaffolding run, wait a few hours, then re-run.
    3. Important: Private Channels will not be created during the scaffolding run in order to improve the success rate for their SharePoint site provision. Tests have shown that if private channels are created before the parent team SharePoint sites are ready, the private channel SharePoint site will not be created automatically.
  4. Wait 24 hours for the Teams sites to provision. 
  5. Private channels will then be created during any content migration (Documents and OneNote, Conversations, Teams Permissions) but we strongly advise you to also follow the next steps to ensure a successful migration.
  6. First, carry out Documents and OneNote During this step we create the private channels.
    1. Frequently, private channel’s SharePoint site alone may still not get provisioned, a typical error might be as follows: Failed to get SharePoint site URL for private channel. <mailnickname:privatechannelname>. If the private channel was recently created, retry migration after 5 minutes.
    2. In this case, the user needs to manually click on the Files tab of the associated private channel, which triggers the provisioning of the private channel SharePoint site.
    3. Optionally, the user can confirm the provisioning by uploading a small document to the private channel’s SharePoint site.
  7. Once the provisioning is successful, reset errors only and re-run the Documents and OneNote migration.
  8. In this second pass of the Document and OneNote migration, the content will be migrated for private channels too.
  9. Next, carry out a conversation migration.
  10. Then carry out the OneNote tabs migrations if necessary. (Wait for at least 4 hours between Documents and OneNote migration and OneNote tabs migration to avoid any sync issues.)
  11. Finally, you can migrate the Teams permissions.
    1. Private channel permissions (membership) can only be migrated using the PS script MWTeamsPrivateChannelMembers.ps1
  12. After the migration is completed, delete the migration admin user from both source and destination to remove the user from all teams and private channel.

Private Channel Permissions

Private channel permissions are not automatically migrated, and require the use of a PowerShell script. If you are migrating private channels, follow the steps listed in the collapsible section below.

Migrating Private Channels via PowerShell


  1. Latest PowerShellGet is loaded
    The PowerShellGet module can be updated by running the command below.

    • Install-Module PowerShellGet -Repository PSGallery -Force -AllowClobber

    After the update is done, close and reopen an elevated PowerShell session to ensure that the latest PowerShellGet is loaded.

  2. Teams PowerShell module is version 1.1.3-preview
    If the Teams PS module version is lower or higher than 1.1.3-preview, MigrationWiz will prompt to allow uninstall and install the required version.


  1. Run the attached script: MWTeamsPrivateChannelMembership.ps1
  2. If you run into any errors, likely due to a TLS issue, run the below command first; then re-run MigratePrivateChannelUsers.ps1.

  3. [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

  4. If prompted to update Teams PowerShell module, approve the update.
  5. Press 1 to get a list of source teams with private channels.
  6. Enter source credentials.
  7. If invalid credentials were entered, it is easiest to close the PowerShell window, start a new window, and rerun the MigratePrivateChannelUsers.ps1 script.
  8. Once credentials are verified, a CSV file will be generated. This CSV will be titled ListOfTeamsWithPrivateChannels.csv
  9. User may modify the CSV now and remove any team mailNickName entries for teams whose private channels will not be migrated to the destination tenant. 
  10. Save the CSV.
  11. Run the script again. 
  12. Press 2 to retrieve all owners and members of private channels for the respective teams as specified in the CSV file.
  13. This will generate a CSV file named OwnersAndMembersOfPrivateChanels.csv
  14. In the User column, change the user's domain from source domain to destination domain.
  15. If user mapping or teams mapping was done, ensure that these are also updated in the User and TeamMailNickName columns. 
  16. Save the CSV file.
  17. Run the script again. 
  18. Press 3 to add owners and members into the proper private channels of the corresponding teams at the destination tenant. 
  19. Enter destination credentials.
  20. If the credentials are successfully verified, you will now be able to see if the user was successfully added.

OneNote Tabs migration 

OneNote Tabs can now be migrated as part of a Teams to Teams migration. This item can be added in the Start Migration flyout window. 


Migrated OneNote tabs will also be reflected in the Folder Summary section under the relevant team/channel: 


Migrated Items will also show the total number of OneNote tabs migrated:  


All emailed project statistics will now also include the OneNote tabs data. 

OneNote tabs cannot be migrated independently without migrating Documents.  

Migrated Items 

The following items will only be migrated if the OneNote Tabs item type is selected. 

OneNote Documents/Notebooks 

  • The existing/default OneNote notebook for each migrated team (both public and private teams). 
  • New OneNote notebook. This notebook will automatically be stored in a particular folder associated with each channel (inside the SharePoint site). 
  • Password-protected notebooks will be migrated as well. 
  • Only OneNote documents relevant to the team/line items in the project will be migrated. 

OneNote Tabs  

Only migrated if the "OneNote tabs" item type is selected.

  • OneNote tabs will be migrated and created at the destination tenant. This is for both public and private channels. 
  • For private channels, if the OneNote document is originally created/added in the destination private channel itself, the contents are migrated, but tabs cannot be created. However, if the OneNote tab was originally created/added in a parent Team and thereafter added as a link into the private channel of that team, the OneNote contents gets migrated into the OneNote tab created. 

OneNote Contents 

  • OneNote permissions will be migrated if the document permissions type is checked to enable document permissions. 
  • All the OneNote content structure/formatting will also be migrated - including section, pages, title, tables. 

Scenarios/Use Cases: Where was the OneNote tab added from?  

OneNote Notebook migrated? 

OneNote Tabs created?  

Default/existing OneNote notebook per source team 



New OneNote notebook created in the source team 



OneNote notebook that was originally created/added in a parent source team and thereafter added as a link into the private channel of that team  



OneNote notebook that was originally created/added in the private channel at the source 



OneNote notebook present in another team’s SharePoint site 

Yes; only if this other team is already migrated in MigrationWiz 


Personal OneNote (stored in personal OneDrive at source) 



If there are failures during OneNote tab migrations, do a "Reset Items" pass to reset errors before resubmitting the migration. Otherwise, all OneNote notebooks and tabs will be recreated.  

Items Not Migrated 

  • A OneNote document present in an individual user’s OneDrive account. 
  • This type of item will be migrated via standard MigrationWiz document project. A warning message will be shown.



  • If the OneNote associated with the tab is not stored in the specified team, the OneNote tab will not be created at the destination. A warning message will be shown. This may be due to a changed personal OneDrive URL or from a lack of visibility into other teams and their migration status.  
  • After migration, the OneNote tab will show the first page of the section by default. 


  • If the source team name and destination team name are different, and the destination team notebook is already provisioned, default mapping will apply. This means that contents in the source notebook will be automatically migrated to the destination notebook even though the team names are different. 
  • If the source team display name and the destination display name are different, and the destination team notebook was not provisioned due to Microsoft limitations, the source notebook will be migrated as-is.  
  • Source default notebook content will be migrated but will not show as the default if the destination notebook has not been provisioned. 

Migrating OneNote Tabs 

This should be done as part of the migration process. It is included separately as it is not a required part of a Teams migration. 

  1. Ensure the MigrationWiz User has already consented to either Teams-ReadOnlyApp or MigrationWiz-Teams-FullControl.
  2. Log in to MigrationWiz.
  3. Create a Teams Collaboration project. 
    • Required endpoints: Microsoft Teams (Source) and Microsoft Teams (Destination). 
  4. Start adding Teams via Autodiscover, Quick Add, or Bulk Add. 
  5. Select which teams to migrate.
  6. Click Start Migration for a ‘Teams Creation’ pass first.
  7. Wait 24 hours for the Teams to provision. 
  8. Migrate Data without OneNote tabs.
    1. Select teams to migrate.
    2. Click Start Migration with ‘Documents and OneNote’ with any other item types but do not select OneNote Tabs.
    3. Wait approximately 4 hours for the OneNote documents to be discovered by the OneNote service.  
  9. Migrate data with OneNote tabs. 
    1. Select ‘OneNote tabs’ and any other item types which still need to be migrated. 
    2. Documents and OneNote can be selected again to bring over any newly created documents since the last migration.  

Migrating Teams with Special Characters in the Name 

This section is specific to migrations utilizing Autodiscover. If any team names have special characters, such as emoji icons, Excel may not be able to open the generated CSV file. The steps below may allow the CSV file to be imported with these special characters.

Once Autodiscover has been completed: 

  1. Download the CSV generated by the Autodiscover process.
  2. Open Excel and import the data using Data--> Import External Data--> Import Data. 
  3. Select the file type csv, then browse to your file. 
  4. In the Excel import wizard, change the File_Origin to 65001 UTF (or choose correct language character identifier). 
  5. Change the delimiter to comma.
  6. Select the location to import to CSV and click Finish. 
    • While these steps should work for most versions of Excel, some versions may still not be able to open the CSV. 
  7. Navigate back to MigrationWiz.
  8. Upload the edited CSV via the Bulk Add function.
  9. Click Start Full Migration
  10. When the migration is complete, verify that the users are able to see their teams and channels in the Destination tenant. 
  11. Click the bar chart icon in the MigrationWiz dashboard to request an email that contains the project migration statistics. 

Migrating Teams for Education templates

MigrationWiz can assist with the migration of Microsoft Teams for Education (Classroom template only, including Classroom Notebook). We currently do not support the migration of Notebooks for Teams based on PLC or Staff templates.
Note: Teams based on these templates will need to be provisioned in the destination prior to migration. Please contact Sales for more information. 

Migrating using U.S. Government Tenants 

Migrating to or from a U.S. Government tenant requires specialized commands for MigrationWiz to connect. Failing to use these options will result in login errors. 

  1. Click Edit Project. 
  2. Click Advanced Options. 
  3. Under Support Options, add the following options below, depending on the specific migration scenario. 
  • If migrating from a U.S. Government Tenant, add: OneDriveProExportEnvironment=AzureUSGovernment 
  • If migrating to a U.S. Government Tenant, add: OneDriveProImportEnvironment=AzureUSGovernment 
  • As U.S. Government Tenant does not natively support Application Permissions, to make sure that the migrating accounts are Global Admin, add: UseDelegatePermission=1
  • For a successful migration, authorize the use of our delegate permission app on Microsoft. The steps for doing this are outlined in Using App-based Authentication. However, it is important to note that you must use the "For Teams Government" link for your migration, otherwise the migration will fail.

 Government-Specific Limitations

  • Conversation History will not be migrated to a tab in the destination. Instead, a message will be posted in the channel with a link to the conversation history HTML file.
  • Due to limitations in the Microsoft system, images will not be migrated as part of the conversation(s). They will still appear in the conversation history HTML file. 

Teams Support Options

Support Options Description
TeamsMaxConversationMessage=XXX Limit the number of conversations to load in the source tenant. E.g. TeamsMaxConversationMessage=1000 would only load 1000 messages

Increase the number of conversation threads that will be posted to the channel. Minimum of 0 and maximum 1000 . Default will be 60 if this option is not added.

*Setting a higher limit will have adverse effect on migration time, as each message post takes 0.5 seconds to post

TeamsMigratePrivateChannel=1 Private channels will be migrated as private channels with conversations and documents. Users will not be migrated; users at the destination must be added manually or via PS script. Refer to section on Migrating Private Channels 


Was this article helpful?
4 out of 11 found this helpful