Skip to main content

Migrate OneDrive for Business to OneDrive for Business with PowerShell

Updated over a month ago

Use PowerShell to automate your migration from OneDrive for Business to OneDrive for Business.
​

Tip: To migrate your documents to a new OneDrive folder, see Walkthrough - Migrate to a new OneDrive folder in PowerShell.

Note: At the end of January 2026, Microsoft began deprecating the IDCRL cookie, meaning that only Browser and Modern authentication methods with the parameters -Browser and -ModernAuth will work in most Microsoft 365 tenants. To learn more about this change, see Important change to "Other user" authentication for Microsoft 365.

Prerequisites

Note: You must be a site collection admin on each OneDrive, even if you have higher admin privileges. In step (9) below, you will use SharePoint admin or global admin permissions to apply site collection permissions to all your OneDrives. The PowerShell script will remove site collection admin permissions as you migrate each OneDrive.

How-to

For your OneDrive for Business migration, you will need to list all your source and destination OneDrives in a CSV file and create a PowerShell script that loops through these parameters to copy each OneDrive.

Create a CSV guide for your migration

  1. Go to All reports.

  2. Click Create custom report in the top right corner.

  3. Select OneDrive for Business as your object type.

  4. Click Continue without saving.

  5. Select your source Tenant.

  6. Click Run.

  7. Select all your OneDrives with the checkmark box at the top of the list.

  8. Click Edit in the Quick actions menu

  9. Select Add administrators in the Transformations dropdown.

  10. Search and add your account in the Select user or group field that appears.

  11. Click Apply.

  12. Click Back two times to go back to your report results.

  13. Click Export in the top right corner.

  14. Save the file on your drive.

  15. Repeat steps (1) to (14), selecting your destination tenant at step (5).

  16. Open Excel.

  17. Add titles SourceSite and DestinationSite to the first two columns.

  18. Open the two files you saved in steps (14) and (15).

  19. Combine the data from both files into the new document so that the source URL corresponds to the destination URL under their respective column.
    ​

    Screenshot of the column information


    If sorting alphabetically doesn't work, you can reorganize your data manually or use Excel macros or PowerShell to find a solution.

  20. Save this new file as a CSV on your drive.

Create your script

Copy and paste the following script into the PowerShell application of your choice.

Import-Module Sharegate

# Define the CSV file path
$csvFile = "C:\CSV\CopyContent.csv"

# Import the CSV file
$table = Import-Csv $csvFile -Delimiter ","

# Define the source and destination connections
$srcSiteConnection = Connect-Site -Url "https://sourcetenantname-my.sharepoint.com/" -ModernAuth
$dstSiteConnection = Connect-Site -Url "https://destinationtenantname-my.sharepoint.com/" -ModernAuth

# Set variables for site and list operations
Set-Variable srcSite, dstSite, srcList, dstList

# Loop through each row in the CSV
foreach ($row in $table) {
    # Clear previous values of variables
    Clear-Variable srcSite
    Clear-Variable dstSite
    Clear-Variable srcList
    Clear-Variable dstList

    # Connect to source and destination sites
    $srcSite = Connect-Site -Url $row.SourceSite -UseCredentialsFrom $srcSiteConnection
    $dstSite = Connect-Site -Url $row.DestinationSite -UseCredentialsFrom $dstSiteConnection

    # Get source and destination lists
    $srcList = Get-List -Site $srcSite -Name "Documents"
    $dstList = Get-List -Site $dstSite -Name "Documents"

    # Copy content from source list to destination list
    Copy-Content -SourceList $srcList -DestinationList $dstList

    # Remove site collection administrator permissions
    Remove-SiteCollectionAdministrator -Site $srcSite
    Remove-SiteCollectionAdministrator -Site $dstSite
}

Adjust your script to work in your environment. Here are a few guidelines:

  • $csvFile: Adjust the path to point to the CSV file you saved before.

  • $table: The delimiter is the symbol your CSV uses to separate items in a row. Ensure your script uses the same delimiter as your file (a quick way to verify this is to open the CSV in Notepad).

  • $srcSiteConnection and $dstSiteConnection: Replace the URL with the root URL of your OneDrives in the corresponding source and destination tenant.

  • Connect-site: The command to connect to a SharePoint site or OneDrive for Business. If you need to change the authentication method from Modern authentication, see Connect Site.

  • Set-Variable and Clear-Variable: These commands help prevent an issue where a connection failure can cause your data to end up in the wrong OneDrive.

  • foreach: We use foreach to loop through the values in your CSV file. You can find more about it here.

  • -UseCredentialsFrom: This script uses Modern authentication with the -UseCredentialsFrom parameter to reuse a single connection. This script will prompt you for your Microsoft 365 credentials when you start it. If MFA isn't enforced on your tenant(s), you can set your script to use a username and password for unattended scheduling. To learn more, see Connect-Site and Avoid repeatedly entering your credentials with the browser and modern connection methods.

  • Remove-SiteCollectionAdministrator: This function removes your user account as site collection administrator on OneDrive after its migration. For more information, see Remove Site Collection Administrator.

Run your script once it's properly adjusted and tested.

Considerations

  • Modern authentication with -ModernAuth is the most secure and persistent authentication method for Microsoft 365, and it can be used with Username and Password variables as long as Multi Factor Authentication (MFA) is not enforced. There are also a few limitations. See Connect-Site to learn different ways to use this connection method, or to switch to Browser authentication if needed.

  • Migration reports are automatically generated, and you can find them in Tasks. You can also export the reports in your script with Export-Report.

  • You can schedule your migration using PowerShell to run it off-hours and optimize performance.

  • To perform an incremental migration, see the Incremental update using PowerShell article.

  • To replicate the copy options from ShareGate Migrate, see Copy options in PowerShell.

  • If you have hundreds of gigabytes of data to migrate, we recommend creating multiple CSVs to run the migration in smaller batches.

  • Script Errors and Testing: Test your PowerShell script on a small subset of OneDrive accounts before applying it broadly. Testing helps identify potential issues in a controlled scope.

Did this answer your question?