How to migrate a file server to SharePoint and OneDrive

List every SMB share and its path, then copy the list into your Mailbox and data inventory sheet. For each share record the business owner and who has access.

Get-SmbShare | Where-Object { $_.Special -eq $false } | Select-Object Name, Path, Description

For each share record size, file count and last-modified spread. The script below gives file counts and sizes per top-level folder. Change \\fs01\Shares to your path.

# Files and size per top-level folder, largest first
Get-ChildItem -LiteralPath '\\fs01\Shares' -Directory | ForEach-Object {
    $m = Get-ChildItem -LiteralPath $_.FullName -Recurse -File -Force -ErrorAction SilentlyContinue |
         Measure-Object -Property Length -Sum
    [pscustomobject]@{ Folder = $_.Name; Files = $m.Count; SizeGB = [math]::Round(($m.Sum / 1GB), 2) }
} | Sort-Object SizeGB -Descending | Format-Table -AutoSize

Add an Action column (Move, Archive, Delete, Leave read-only). Agree with owners which folders are archived, deleted or left read-only on the old server. Moving less is the single biggest time saver.

Personal home drives go to each user's OneDrive. List users with a home folder set, and note any home drive that is really a team folder in disguise.

Get-ADUser -Filter * -Properties HomeDirectory | Where-Object HomeDirectory | Select-Object SamAccountName, UserPrincipalName, HomeDirectory

Add the target site URL and library for each share. Use a site when the audience or permissions differ. Use a separate library when content needs different settings such as versioning or retention. Use folders only for navigation.

The 400-character limit counts the site and library URL too. Promote deep sub-folders to their own libraries or sites rather than moving them as they are.

Short site and library names leave more of the 400 characters for folders and file names, and make synced paths shorter in File Explorer.

Create each target site (a team site, or a Teams-connected site where the group also needs chat), using the short names from your sheet. Add extra libraries from the site's New menu.

OneDrive must exist before you migrate a home drive into it. Request it for the users from Step 1.

Connect-SPOService -Url https://contoso-admin.sharepoint.com
Request-SPOPersonalSite -UserEmails "meganb@contoso.com","alexw@contoso.com"

Export the access list of each top-level folder so owners can see who has access today.

Get-Acl -Path '\\fs01\Shares\Finance' | Select-Object -ExpandProperty Access | Select-Object IdentityReference, FileSystemRights, IsInherited

Map NTFS groups to the site's Owners, Members and Visitors groups, or to Microsoft 365 groups for Teams-connected sites. Use security groups synced from Active Directory or created in Entra ID, not individual users.

Microsoft supports up to 50,000 unique permissions in a list or library, with a recommended general limit of 5,000. If a folder needs different access, it usually needs its own library or site.

Keep a sheet of share, NTFS group, target site and SharePoint group. Owners sign it off before migration.

Save the script as Invoke-SharePointPreScan.ps1, then run it once per share with the share path and the matching site and library prefix from your architecture sheet.

# Save as Invoke-SharePointPreScan.ps1. Read-only: it reports problems and changes nothing.
# Run in PowerShell 7 so paths longer than 260 characters can be read.
# Example:
#   pwsh -File .\Invoke-SharePointPreScan.ps1 -SourcePath '\\fs01\Shares\Finance' -DestinationPrefix 'sites/Finance/Shared Documents'
param(
    [Parameter(Mandatory = $true)]
    [string]$SourcePath,
    [string]$DestinationPrefix = 'sites/Finance/Shared Documents',
    [int]$MaxPathLength = 400,
    [long]$MaxFileBytes = 250GB,
    [string]$ReportPath = '.\prescan-report.csv'
)

$invalidChars  = [regex]'["*:<>?/\\|]'
$reservedNames = @('.lock', 'CON', 'PRN', 'AUX', 'NUL', 'desktop.ini') +
                 (0..9 | ForEach-Object { "COM$_"; "LPT$_" })

$root      = (Get-Item -LiteralPath $SourcePath).FullName.TrimEnd('\')
$results   = [System.Collections.Generic.List[object]]::new()
$fileCount = 0

Get-ChildItem -LiteralPath $root -Recurse -Force -ErrorAction SilentlyContinue -ErrorVariable scanErrors |
    ForEach-Object {
        $item     = $_
        $isFolder = $item.PSIsContainer
        if (-not $isFolder) { $fileCount++ }

        $relative = $item.FullName.Substring($root.Length).TrimStart('\') -replace '\\', '/'
        $destPath = "$DestinationPrefix/$relative"
        $baseName = [System.IO.Path]::GetFileNameWithoutExtension($item.Name)
        $issues   = @()

        if ($destPath.Length -gt $MaxPathLength) { $issues += "Destination path is $($destPath.Length) characters" }
        if ($invalidChars.IsMatch($item.Name))   { $issues += 'Invalid character' }
        if ($item.Name -ne $item.Name.Trim())    { $issues += 'Leading or trailing space' }
        if (($reservedNames -contains $item.Name) -or ($reservedNames -contains $baseName)) { $issues += 'Reserved name' }
        if ($item.Name.StartsWith('~$'))         { $issues += 'Name starts with ~$' }
        if ($item.Name -like '*_vti_*')          { $issues += 'Name contains _vti_' }
        if ($isFolder -and $item.Name -eq 'forms' -and $relative -notmatch '/') { $issues += 'Folder named forms at library root' }
        if ((-not $isFolder) -and ($item.Length -gt $MaxFileBytes)) { $issues += 'File larger than size limit' }

        if ($issues.Count -gt 0) {
            if ($isFolder) { $type = 'Folder'; $size = $null } else { $type = 'File'; $size = $item.Length }
            $results.Add([pscustomobject]@{
                Issues                = $issues -join '; '
                Type                  = $type
                Path                  = $item.FullName
                DestinationPathLength = $destPath.Length
                SizeBytes             = $size
            })
        }
    }

foreach ($err in $scanErrors) {
    $results.Add([pscustomobject]@{
        Issues                = "Could not read: $($err.Exception.Message)"
        Type                  = 'Error'
        Path                  = "$($err.TargetObject)"
        DestinationPathLength = $null
        SizeBytes             = $null
    })
}

$results | Export-Csv -LiteralPath $ReportPath -NoTypeInformation -Encoding UTF8
Write-Host ('Scanned {0} files. {1} items need attention. Report: {2}' -f $fileCount, $results.Count, $ReportPath)
if ($fileCount -gt 300000) {
    Write-Warning 'More than 300,000 files. Do not ask users to sync all of this library.'
}

Open the CSV in Excel, filter by issue and fix at source (rename, shorten or move) or adjust the target design. Run the scan again until only accepted items remain.

Sign in to the admin center as a SharePoint Administrator, select Download agent setup file and save it.

Open the setup file. On the Welcome page choose User Credential Authentication and select Next, then enter the SharePoint admin username and password for the destination. Third-party MFA is not supported for the agent sign-in. Enter the password of the Windows account with read access to the shares and select Install. Optionally test agent access, then select Close. Repeat on more machines for more throughput.

Under Method choose Single source and destination (a few shares) or Bulk migration (a CSV or JSON file in Microsoft's bulk upload format). Enter the source as \\fs01\Shares\Finance and select Next. Choose SharePoint site, OneDrive or Teams, enter the site and library (or the user's email for OneDrive) and select Next. Enter a Task name, review All settings (scan only, permissions, filters, invalid characters), then select Run now. Each agent can queue up to 10 tasks.

Every file is scanned, packaged, uploaded and imported. Download the task reports as Microsoft's Migration Manager reports page describes and fix failures. Re-running a task performs an incremental pass.

File share content arrives with the default Document content type. Apply metadata or content types after migration if you need them.

Ask users to open the library in the browser, select the folders they need and choose Add shortcut to My files. The folder then appears in their OneDrive in File Explorer without syncing every library.

Microsoft recommends syncing no more than 300,000 files in total across a user's cloud storage. Big archive libraries should be opened in the browser, not synced.

Remove the old drive letter mappings on cutover day so people stop saving to the old server. Users see the change after their next sign-in or Group Policy refresh.

gpupdate /force
net use

At the agreed time, change share permissions to read-only so no new changes land on the server. Change the share name and group to match yours.

Get-SmbShareAccess -Name Finance
Revoke-SmbShareAccess -Name Finance -AccountName 'CONTOSO\Finance Staff' -Force
Grant-SmbShareAccess -Name Finance -AccountName 'CONTOSO\Finance Staff' -AccessRight Read -Force

Re-run each task, check the reports and sign off with the share owner. Record file counts in your Data validation report.

Leave the old shares read-only for an agreed period, then archive and decommission the server.