How to move a file share to SharePoint: setup, CSV mapping, and final sync

Use Migration Manager in the SharePoint admin center to move a file share: install a migration agent, scan the file share, choose a destination for each source folder, run the migration, reconcile the reports, and make a final incremental pass before the team switches to the new location.

Start by separating ordinary team documents from folders that an application still reads through a Windows network path. A SharePoint document library is a sensible destination for shared Office files. Keep application-dependent folders on the file share until the application’s replacement workflow has been verified. Likewise, set aside folders whose access depends on complex deny rules until their destination permissions have been designed and reviewed.

Prepare the agent and access

Migration Manager is available in the SharePoint admin center’s Migration center. It uses agents installed on computers or virtual machines that can reach the source shares. The Windows account used by an agent needs Read access to every share assigned to it; the destination requires a SharePoint or OneDrive administrator account. Use the destination administrator role required for the work. Review Microsoft’s system and endpoint prerequisites, including the SMB 2.0 or higher requirement, before installing an agent. Migration Manager supports individual files up to 250 GB.

On a computer that can reach the shares, open SharePoint admin center > Migration center > For file shares > Get started > Agents > Add > Download agent setup file. The installer offers User Credential Authentication, which uses a destination administrator sign-in, and Certificate Authentication, which uses a configuration file. Supply the Windows source account password, select Install, optionally use Test agent access, and close the installer. Confirm that the agent appears as available. The account must be able to read all the source locations you plan to give it, including source folders outside the first path you checked. Microsoft’s agent setup instructions also specify at least 150 GB of free space in the working folder, %appdata%\Microsoft\SPMigration; some migrations may need more.

You can install agents on multiple computers or VMs. Migration Manager assigns work automatically within an agent group: when you configure a task, choose the appropriate agent group. The service selects an available agent within it. If an agent is installed as an app on a computer that is not joined to a domain, its work pauses while that computer sleeps.

Scan the actual network path

Add a source using its UNC path, such as \\files01\Departments\Operations. A personal mapped drive such as Z: is not a suitable shared source definition: it may refer to a different location, or nothing at all, for the agent’s account.

Adding a UNC source starts a scan of the files at that root. Select its scan row and download the summary report and scan log. Review warnings about invalid characters and read permissions before treating the source as ready. If you correct a problem or change the scan scope, use Scan content to scan again. The file count displayed for a scan can exclude items affected by filters, settings, or scan failures, so do not treat that single number as a complete inventory. Long destination paths also need attention: Microsoft’s path calculation includes the tenant URL, site and folder path, and character encoding, with a 400-character limit. The scan instructions describe these reports and controls.

A scan can show permission entries at a root, but that count does not establish who will have the intended access in SharePoint. Review sensitive folders against the destination’s membership and inherited permissions before including them.

Map each source to a destination

For a scanned row that is ready, choose Copy to migrations, select SharePoint, then select the site path and destination location. Give the task a recognizable name, choose its agent group, review its settings, and run it now or schedule it. These are the documented scan-to-migration steps. Migration Manager also has an Add task route for a single source and destination or a bulk migration; there you enter the source UNC path, the SharePoint site and document folder, and the task settings. Scanning first gives you a chance to resolve source problems before building the migration tasks. Microsoft documents both task routes.

For many folders, a UTF-8 CSV can define the mappings. Every row has six columns: source file-share path, two empty columns, SharePoint site URL, document-library name, and an optional destination subfolder. This synthetic example maps two sibling source folders into separate subfolders:

FileSharePath,,,SharePointSite,DocLibrary,DocSubFolder
\\files01\Departments\Operations,,,https://contoso.sharepoint.com/sites/operations,Documents,Working files
\\files01\Departments\Archive,,,https://contoso.sharepoint.com/sites/operations,Documents,Reference archive

The first line is an optional header. In each data row, the three commas after the UNC path preserve the empty second and third fields. Check the raw six fields before uploading: a missing comma shifts the site URL or library name into the wrong column. The fourth field must be the site URL, not a document-sharing link. The fifth must be the name of a library that actually exists at that site; Documents is an example, not a guaranteed library name. The sixth field selects a subfolder inside that library. To use the library root, leave that field empty but retain its trailing comma.

Download the illustrative six-column mapping CSV. Replace both source paths, the site URL, library, and destination folders before using it. It is a planning template with two invented source locations; it has not been uploaded or used to migrate files.

Avoid mapping a parent share and its child as separate tasks when their source files would overlap. Microsoft says destination links in the first 20 CSV rows are validated; inspect the remaining rows yourself before submitting the tasks. The bulk-upload format defines the columns.

Review settings that change the file count

Open the task’s settings before you select Run. If you used Add task, Microsoft calls the full settings view All settings. Only perform scanning is a preassessment setting; a task left in that mode will not carry out the intended migration. If the plan is to preserve file-share permissions, select that setting deliberately and review the user-mapping method. Microsoft Entra lookup is on by default. With lookup on, a supplied mapping file can provide mappings while lookup serves as a fallback for unmapped domain users. With lookup off, the tool does not look up a source user missing from your mapping file in Entra ID. Check the required user entries before choosing that behavior. Review the access users receive at the destination as well as the source identities being mapped. Migration Manager’s settings reference explains these options.

Check content filters as carefully as destination paths. With Migrate hidden files off, hidden content is skipped; the Windows hidden attribute itself is a separate matter and is not preserved. Date filters select files created or modified after the chosen date. An extension exclusion list leaves specified file types out. If you specify extensions, the list uses colon-separated names without dots. Record which omissions are intentional so they do not later look like unexplained losses.

Permissions need particular care where Share and NTFS rules differ. Microsoft’s file-share-to-Microsoft 365 migration guide, written around the SharePoint Migration Tool, describes user-level mapping based on the more restrictive Share or NTFS permission, removal of advanced NTFS permissions, and exclusion of explicit deny entries. It warns that access may still be available through another or parent permission. Keep a deny-sensitive folder out of the migration until its destination access has been redesigned and checked. Migration Manager’s preservation setting alone does not establish that an NTFS rule has an equivalent in SharePoint. The same guide says embedded URLs are not converted. Put shared team documents in a shared library; a single owner’s private files may fit OneDrive, which is private by default.

Reconcile the run with its reports

After a task completes, select its name and Download task report. For a view across completed tasks, select them and obtain the Summary report. File-share report names include Aggregate Summary Report.csv, ItemSummary.csv, ItemFailureReport.csv, ItemReport.csv, ScanSummary.csv, StructureReport.csv, and StructureFailureReport.csv. Download what you need before the reports expire after 90 days. Microsoft’s report reference describes their fields.

Use ItemSummary.csv to separate Scanned, Item scan failures, Filtered out items, Expected migrated file count, and Migrated. For a hypothetical ItemSummary.csv row, use files as the unit throughout: 1,500 scanned, 100 deliberately filtered, 20 scan failures, and 1,380 expected to migrate. In this example the filtered and scan-failure groups are separate. In your own report, read Expected migrated file count directly; do not reconstruct it from a dashboard count that includes folders. If 1,374 migrated, six expected files remain unresolved. The migrated count is 99.57% of the expected count but 91.6% of the scanned count. Neither percentage proves completion: the 20 scan failures still need investigation, the 100 omissions need to match the plan, and the six remaining files need a result.

Look at ItemFailureReport.csv for failed items, then use ItemReport.csv to locate the source and destination paths and read each item’s status, result category, message, and incremental round. Resolve the underlying source, mapping, or destination issue shown by the report, then rescan or rerun the affected work as appropriate. A source file that could not be scanned needs a different repair from a file that failed during upload. Save the filename, source path, failure message, and run number while investigating so a rerun can be compared with the earlier result.

Make the final incremental pass

A completed task can be rerun. Delta sync looks for files new or updated since the previous run. Full incremental compares all source items with the destination. Consider a January-dated document copied into the source in October, after an initial migration. Its modified time can precede that first run even though it is newly added to the share. Microsoft recommends Full incremental for this case because Delta sync can miss the file.

Incremental migration has specific rules for existing files. Deleting a source file does not delete its SharePoint copy. A source file older than its target is not migrated, and the documentation says a destination-changed file with the same name is not overwritten. Conversely, a previously migrated file that has been renamed or moved within the same library can be overwritten during an incremental run. Leave destination names and paths in place until the final migration is complete. Microsoft’s incremental-run guidance sets out these boundaries.

For the handoff, have the approved administrator stop writes to the source at the agreed cutover time, run the final incremental pass, and reconcile its reports against the planned filters and remaining failures. Check the new document locations and intended access before giving the team the new URLs. Agree separately who retains the old copy and when it may be removed.

Source note: These steps follow Microsoft’s Migration Manager documentation. The paths and report numbers are illustrative; no live tenant migration was performed for this article.