SharePoint Migration Tool: move file shares to SharePoint and OneDrive

To move on-premises file shares to SharePoint or OneDrive, install the free SharePoint Migration Tool (SPMT) on a Windows machine that can read the share, run a scan-only pass to find blocked names and long paths, then migrate with a bulk CSV or the SPMT PowerShell cmdlets and rerun the same tasks as incremental passes until cutover. For large estates, use Migration Manager in the SharePoint admin center instead, which spreads the same work across agents on several servers. Both tools copy rather than move, so the source stays intact until you retire it.

Who this is for and what you will have at the end

This guide is for Microsoft 365 and Windows file server administrators who need to retire "Z drive" style network shares and home drives. It assumes the target sites and OneDrive accounts live in the same tenant you sign in to.

At the end you will have:

• A decision on SPMT versus Migration Manager for your volume of shares.
• Source and destination mapped in a bulk CSV file that SPMT accepts.
• A scan report that tells you what will fail before you move any data.
• A repeatable migration with incremental passes and a single cutover.
• Reports you can use to prove what was copied and what wasn't.

If the file shares are only one part of a larger move, the planning approach in the Google Workspace to Microsoft 365 migration guide and the enterprise Azure migration playbook covers waves, communication and cutover at programme level.

SPMT or Migration Manager

SPMT is a free download, and Migration Manager is built into the SharePoint admin center. The difference is where they run and how the work is orchestrated.

Microsoft's file share migration guide points self-service file share projects toward Migration Manager because it gives a central place to connect servers, create tasks and load-balance them. Microsoft also advises using the fewest agents that finish the job in your time frame, because extra agents raise the API request rate and throttling. SPMT remains the simplest option when one migration server is enough, and its cmdlets are the most direct way to script a migration. The rest of this guide uses SPMT and shows the Migration Manager equivalent where it differs.

What gets migrated and what doesn't

From a file share, the tools migrate documents, the folder structure, user-level file and folder permissions (when you enable it), and file metadata. They don't convert links embedded inside documents, they don't carry over Windows hidden attributes or explicit deny permissions, and they skip inaccessible or corrupted files and anything that breaks SharePoint limits.

The limits that matter most for file shares:

• File size: SharePoint, OneDrive and Teams accept files up to 250 GB, and Migration Manager supports files up to 250 GB for file share migrations. Microsoft's file share migration guide still lists "files under 15 GB" in its SPMT table, so include your largest files in the pilot and check the scan report for a "File size exceeds limit" failure.
• Path length: the entire decoded path, folder path plus file name, can't exceed 400 characters in SharePoint and OneDrive.
• Names: the characters " * : < > ? / \ | aren't allowed, and neither are leading or trailing spaces or names such as .lock, CON, PRN, AUX, NUL, desktop.ini or anything containing _vti_.
• Permissions: the supported limit of unique permissions in one list or library is 50,000, and the recommended general limit is 5,000. A share with permissions broken on thousands of folders will be hard to manage after migration even if it fits.

How file share permissions map

When Preserve file share permissions is on and users can be matched to Microsoft Entra ID, SPMT migrates three permission types:

Only unique permissions on files and folders are migrated; inherited permissions aren't. Special permissions such as Deny aren't saved. If users can't be mapped, because accounts aren't synchronized and there's no mapping file, files are assigned the default permissions of the destination location. When preservation is on and you migrate into the library root of a library that inherits from its site, the source root folder's role assignments replace the library's role assignments and the library gets unique permissions. If the library already has unique permissions, the source assignments are added to it instead. Test on a pilot library first.

Prerequisites

The migration computer

The working folder defaults to %appdata%\Microsoft\MigrationTool and needs at least 150 GB free, more for large shares. Migration Manager agents have similar CPU, RAM and disk guidance (Microsoft lists a solid-state disk with 150 GB free even for the minimum spec), and for file share sources the server hosting the data must support SMB 2.0 or higher.

Access and accounts

• Destination: to migrate at organization level you sign in as a SharePoint Administrator or Global Administrator; to migrate into a single site you need to be a site admin of that site collection. Microsoft recommends the role with the fewest permissions; for Migration Manager there is also a Microsoft 365 Migration Administrator role that is limited to migration work.
• Source: an account with read access to every share you plan to migrate.
• Identity: to keep permissions there must be a matching user in Microsoft 365. Synchronizing Active Directory to Microsoft Entra ID is the simplest way; otherwise prepare a user mapping file.
• Network: the computer must reach the endpoints Microsoft lists, including login.microsoftonline.com, *.sharepoint.com, *.blob.core.windows.net, *.queue.core.windows.net, graph.microsoft.com and spmt.sharepointonline.com. Microsoft states that proxy connections aren't supported by SPMT, so run it from a machine with a direct route to those endpoints.

SPMT isn't available for Office 365 operated by 21Vianet.

Step 1: Decide where each share goes

Review how each share is used before you map it. Files that belong to one person go to that person's OneDrive, which is private by default but shareable. Content a team works on together goes to a shared library in a SharePoint site or a Teams channel, where members have access by default. Home drive shares usually map one-to-one to OneDrive; departmental shares map to team sites.

Record the mapping in a spreadsheet with source path, destination URL, library and optional subfolder. You will turn it into the bulk CSV in Step 4.

Step 2: Pre-provision OneDrive for home drive targets

A OneDrive is normally created the first time a user opens it, so migrations into OneDrive need the accounts created beforehand. The users must have a SharePoint licence and be allowed to sign in, and the admin running the cmdlet needs the SharePoint Administrator role and a SharePoint licence. Connect with the SharePoint Online Management Shell and run:

$users = Get-Content -Path "C:\Migration\Users.txt"
Request-SPOPersonalSite -UserEmails $users

Users.txt holds one UPN per line, such as meganb@contoso.com. For large numbers, Microsoft's sample script submits batches of 199 users with -NoWait. Provisioning many accounts can take several days, so do this well before the first migration wave. The migration account also needs permission on each destination OneDrive.

Step 3: Install SPMT and review the settings

Download SPMT from the general availability link on Microsoft's install page and sign in with your Microsoft 365 admin account. The credentials you enter are for the destination.

Open the settings before creating any task, because several are global and some can't be changed after the first job is submitted. The ones that matter for file shares:

Keep Replace invalid filename characters on unless you have cleaned names already. With it off, files with invalid characters are skipped, and any package that generates more than 100 errors at the destination is blocked entirely, including the valid files in it.

Step 4: Build the bulk CSV file

SPMT accepts a CSV with one source and one destination per row. Columns can be blank when not needed but must be present, and there's no header row in the examples Microsoft gives. Microsoft's reference also documents two optional hub site columns (7 and 8) that apply only to SharePoint site migrations; its file share examples use the six columns below.

\\fs01\departments\finance,,,https://contoso.sharepoint.com/sites/Finance/,Documents,Archive
\\fs01\homedrives\meganb,,,https://contoso-my.sharepoint.com/personal/meganb_contoso_com/,Documents,

Use the internal name Documents for the out-of-the-box library. Entering Shared Documents produces an "invalid document library" error. If the destination site isn't in English, check the internal name on the site's _layouts/15/viewlsts.aspx page.

Step 5: Scan, then migrate

1. In SPMT settings, set Only perform scanning to On.
2. Select Add new migration, and under Select a method choose Bulk migration using JSON or CSV file.
3. Enter the full path of the CSV file and select Next. SPMT validates the file line by line and won't continue until every error is fixed.
4. Review the settings and select Start.
5. Open the scan reports, fix names, paths and blocked file types at the source, and repeat until the issue count is acceptable.
6. Set Only perform scanning to Off and run the same CSV to migrate.

The same job with PowerShell

The SPMT cmdlets give you the same engine in a script, which helps for scheduled incremental passes. They need Windows PowerShell 5.x; PowerShell 6.0 or later isn't supported.

Import-Module Microsoft.SharePoint.MigrationTool.PowerShell
 
# Interactive sign-in; don't pass -SPOCredential if the account uses MFA
Register-SPMTMigration -ScanOnly $false -PreserveUserPermissionsForFileShare $true `
    -IncludeHiddenFiles $false -Force
 
$rows = Import-Csv "C:\Migration\spmt.csv" -Header c1,c2,c3,c4,c5,c6
foreach ($row in $rows) {
    Add-SPMTTask -FileShareSource $row.c1 -TargetSiteUrl $row.c4 `
        -TargetList $row.c5 -TargetListRelativePath $row.c6
}
 
Start-SPMTMigration -NoShow
$session = Get-SPMTMigration
while ($session.Status -ne "Finished") {
    foreach ($task in $session.StatusOfTasks) { $task.MigratingProgressPercentage }
    Start-Sleep -Seconds 30
}

Register-SPMTMigration -Force stops and unregisters any existing session first. Use Show-SPMTMigration to bring a background run back to the console. If a scan fails on source paths longer than 260 characters, Microsoft's documented workaround is to add the AppContext key under HKLM\SOFTWARE\Microsoft\.NETFramework with the string values Switch.System.IO.BlockLongPaths and Switch.System.IO.UseLegacyPathHandling both set to false.

The Migration Manager equivalent

In the Migration center of the SharePoint admin center the file share flow has three steps:

1. Set up agents. Run the agent setup file on each computer or VM. It asks for SharePoint admin credentials for the destination and Windows credentials with read access to all the shares, and the agent then runs as a service.
2. Scan and assess. Select Add source path and enter the UNC path of each share. Shares are scanned automatically once added; use Download summary report and Download scan log to investigate issues. Only agents in the Default agent group are scheduled for scans.
3. Copy to migrations. Select the scanned rows, choose Copy to migrations, pick OneDrive, SharePoint or Teams as the destination and the location within it, give the migration a name, select an agent group, review the settings and choose Run now or Run later.

Reruns in Migration Manager offer Delta sync, which only looks at items changed since the last run, and Full incremental, which compares every source item with the destination and catches files whose modified time is older than the previous run.

Step 6: Incremental passes and cutover

Microsoft's recommended pattern is to migrate in the background with no user impact, rerun to pick up changes, then hold one cutover event where you disable the file shares and send users to SharePoint and OneDrive. A single cutover for everyone stops people from editing two copies.

When you rerun a saved SPMT task, it checks the destination first:

Because matching is by path, renaming or moving migrated files before the final pass causes files to be overwritten. Ask pilot users to leave migrated content alone until cutover, make the share read-only for the final pass, and then remove the drive mapping.

Verify the migration

Select View reports on a task to open its task-level reports, or Migration details after the job to open the summary reports.

• SummaryReport.csv: the overall picture, with total size, items scanned and migrated, items not migrated, duration and GB per hour.
• FailureSummary.csv: created only when something failed. If it doesn't exist, nothing failed.
• ItemReport.csv and ItemFailureReport.csv: every item the task tried, and the failures with result category, message and error code.
• ScanSummary.csv: totals from the scan, including items with issues and items filtered out by your settings.

A performance report also scores source read speed, local disk, upload speed and SharePoint throughput from 1 to 100, which points you at the bottleneck when a run is slow. Spot-check a few folders in the destination as well: open files, confirm Modified dates and authors, and check permissions on a folder that had unique access on the share.

Troubleshooting

Checklist

• Tool chosen: SPMT for a few shares or scripted runs, Migration Manager for many sources in parallel.
• Migration computer meets the recommended spec, with 150 GB or more free for the working folder and the endpoints open.
• Users synchronized to Microsoft Entra ID, or a mapping file prepared.
• OneDrive accounts pre-provisioned with Request-SPOPersonalSite for home drive targets.
• Settings reviewed: permissions, hidden files, extension filters, character replacement.
• Bulk CSV built with Documents as the default library name and empty source library columns.
• Scan-only pass run and issues fixed at the source.
• Pilot migrated and checked, then full waves with incremental reruns.
• Single cutover with shares made read-only, then retired.
• Summary, failure and item reports archived with the project records.

References

• SharePoint Migration Tool overview
• Install the SharePoint Migration Tool
• SPMT prerequisites and endpoints
• SharePoint Migration Tool settings
• Create a task in SPMT
• Format your JSON or CSV file for data content migration
• File and folder permissions when using SPMT
• Monitor and report on SPMT migration tasks
• Migrate to SharePoint and OneDrive using PowerShell cmdlets
• Register-SPMTMigration
• Add-SPMTTask
• Migrate file shares to SharePoint and OneDrive
• Migrate file shares with Migration Manager
• Set up Migration Manager agents
• Scan and assess file shares in Migration Manager
• Copy file shares to migrations in Migration Manager
• Troubleshooting common SPMT issues and errors
• Migration Manager prerequisites and endpoints
• Pre-provision OneDrive for users
• SharePoint limits
• Restrictions and limitations in OneDrive and SharePoint